Merge branch 'matm-master-patch-51516' into 'master'

Fix for  **Use unique domain** setting changes in URLs

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140821



Merged-by: Russell Dickenson <rdickenson@gitlab.com>
Approved-by: Russell Dickenson <rdickenson@gitlab.com>
Co-authored-by: Mat M <matm@gmx.fr>

doc/user/project/pages/getting_started_part_one.md

@@ -37,6 +37,20 @@ Pages domains are `*.gitlab.io`.
 | Project pages owned by a group | `acmecorp/webshop` | `http(s)://acmecorp.example.io/webshop`|
 | Project pages owned by a subgroup | `acmecorp/documentation/product-manual` | `http(s)://acmecorp.example.io/documentation/product-manual`|
 
+When **Use unique domain** setting is enabled, all URLs
+are flattened with the following structure:
+
+| Type of GitLab Pages | Example path of a project in GitLab | Website URL |
+| -------------------- | ------------ | ----------- |
+| User pages  | `username/username.example.io`  | `http(s)://username-example-io-username.example.io`  |
+| Group pages | `acmecorp/acmecorp.example.io` | `http(s)://acmecorp-example-io-acmecorp-uniqueid.example.io` |
+| Project pages owned by a user  | `username/my-website` | `https://my-website-username-uniqueid.gitlab.io/` |
+| Project pages owned by a group | `acmecorp/webshop` | `http(s)://webshop-acmecorp-uniqueid.example.io/`|
+| Project pages owned by a subgroup | `acmecorp/documentation/product-manual` | `http(s)://product-manual-documentation-acmecorp-uniqueid.example.io/`|
+
+The `unique_id` portion of the URL is an alphanumeric string. For example, if the `unique_id` is `30bae2547a50der6ed7d9a08d417a33525a5c4dc6fdd68`, the last example would be
+`http(s)://product-manual-documentation-acmecorp-30bae2547a50der6ed7d9a08d417a33525a5c4dc6fdd68.example.io/`.
+
 WARNING:
 There are some known [limitations](introduction.md#subdomains-of-subdomains)
 regarding namespaces served under the general domain name and HTTPS.
@@ -44,21 +58,24 @@ Make sure to read that section.
 
 To understand Pages domains clearly, read the examples below.
 
+NOTE:
+The following examples imply you disabled the **Use unique domain** setting. If you did not, refer to the previous table, replacing `example.io` by `gitlab.io`.
+
 ### Project website examples
 
 - You created a project called `blog` under your username `john`,
   therefore your project URL is `https://gitlab.com/john/blog/`.
-  Once you enable GitLab Pages for this project, and build your site,
+  After you enabled GitLab Pages for this project, and build your site,
   you can access it at `https://john.gitlab.io/blog/`.
 - You created a group for all your websites called `websites`,
-  and a project within this group is called `blog`. Your project
-  URL is `https://gitlab.com/websites/blog/`. Once you enable
+  and a project in this group is called `blog`. Your project
+  URL is `https://gitlab.com/websites/blog/`. After you enabled
   GitLab Pages for this project, the site is available at
   `https://websites.gitlab.io/blog/`.
 - You created a group for your engineering department called `engineering`,
   a subgroup for all your documentation websites called `docs`,
-  and a project within this subgroup is called `workflows`. Your project
-  URL is `https://gitlab.com/engineering/docs/workflows/`. Once you enable
+  and a project in this subgroup is called `workflows`. Your project
+  URL is `https://gitlab.com/engineering/docs/workflows/`. After you enabled
   GitLab Pages for this project, the site is available at
   `https://engineering.gitlab.io/docs/workflows`.
 
@@ -66,11 +83,11 @@ To understand Pages domains clearly, read the examples below.
 
 - Under your username, `john`, you created a project called
   `john.gitlab.io`. Your project URL is `https://gitlab.com/john/john.gitlab.io`.
-  Once you enable GitLab Pages for your project, your website
+  After you enabled GitLab Pages for your project, your website
   is published under `https://john.gitlab.io`.
 - Under your group `websites`, you created a project called
   `websites.gitlab.io`. Your project's URL is `https://gitlab.com/websites/websites.gitlab.io`.
-  Once you enable GitLab Pages for your project,
+  After you enabled GitLab Pages for your project,
   your website is published under `https://websites.gitlab.io`.
 
 **General example:**