Merge branch 'docs-self-host-docs-site-update' into 'master'

Style and content edits for self-hosting docs

See merge request gitlab-org/gitlab!77689

doc/administration/docs_self_host.md

@@ -6,18 +6,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # How to self-host the docs site **(FREE SELF)**
 
-The following guide describes how to use a local instance of the docs site with
-a self-managed GitLab instance.
+If you have a self-managed instance of GitLab, you may not be able to access the
+product documentation as hosted on `docs.gitlab.com` from your GitLab instance.
 
-## Run the docs site
+Be aware of the following items if you self-host the product documentation:
 
-The easiest way to run the docs site locally it to pick up one of the existing
-Docker images that contain the HTML files.
+- You must host the product documentation site under a subdirectory that matches
+  your installed GitLab version (for example, `14.5/`). The
+  [Docker images](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635)
+  hosted by the GitLab Docs team provide this by default. We use a
+  [script](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/2995d1378175803b22fb8806ba77adf63e79f32c/scripts/normalize-links.sh#L28-82)
+  to normalize the links and prefix them with the respective version.
+- The version dropdown will display additional versions that don't exist, selecting
+  those versions will display a 404 Not Found page.
+- Results when using the search box will display results from `docs.gitlab.com`
+  and not the local documentation.
+- When you use the Docker images to serve the product documentation site, by
+  default the landing page redirects to the respective version (for example, `/14.5/`),
+  which causes the landing page <https://docs.gitlab.com> to not be displayed.
+
+## Documentation self-hosting options
 
-Pick the version that matches your GitLab version and run it, in the following
-examples 14.5.
+You can self-host the GitLab product documentation locally using one of these
+methods:
 
-### Host the docs site using Docker
+- Docker
+- GitLab Pages
+- From your own webserver
+
+The examples on this page are based on GitLab 14.5.
+
+### Self-host the product documentation with Docker
 
 The Docker images use a built-in webserver listening on port `4000`, so you need
 to expose that.
@@ -42,9 +61,9 @@ services:
       - '4000:4000'
 ```
 
-### Host the docs site using GitLab Pages
+### Self-host the product documentation with GitLab Pages
 
-You can also host the docs site with GitLab Pages.
+You use GitLab Pages to host the GitLab product documentation locally.
 
 Prerequisite:
 
@@ -53,11 +72,11 @@ Prerequisite:
   main domain or subdomain. For example, URLs like `https://example.com/docs/`
   are not supported.
 
-To host the docs site with GitLab Pages:
+To host the product documentation site with GitLab Pages:
 
 1. [Create a new blank project](../user/project/working_with_projects.md#create-a-blank-project).
-1. Create a new or edit your existing `.gitlab-ci.yml` file and add the following
-   `pages` job. Make sure the version is the same as your GitLab installation:
+1. Create a new or edit your existing `.gitlab-ci.yml` file, and add the following
+   `pages` job, while ensuring the version is the same as your GitLab installation:
 
    ```yaml
    image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5
@@ -70,20 +89,22 @@ To host the docs site with GitLab Pages:
        - public
    ```
 
-1. (Optional) Set the Pages domain name. Depending on the type of the Pages website,
-   you have two options:
+1. Optional. Set the GitLab Pages domain name. Depending on the type of the
+   GitLab Pages website, you have two options:
 
-   | Type of website | [Default domain](../user/project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names) | [Custom domain](../user/project/pages/custom_domains_ssl_tls_certification/index.md) |
-   | --------------- | -------------- | ------------- |
+   | Type of website         | [Default domain](../user/project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names) | [Custom domain](../user/project/pages/custom_domains_ssl_tls_certification/index.md) |
+   |-------------------------|----------------|---------------|
    | [Project website](../user/project/pages/getting_started_part_one.md#project-website-examples) | Not supported | Supported |
    | [User or group website](../user/project/pages/getting_started_part_one.md#user-and-group-website-examples) | Supported | Supported |
 
-### Host the docs site on your own webserver
+### Self-host the product documentation on your own webserver
+
+Because the product documentation site is static, you can grab the directory from
+the container (in `/usr/share/nginx/html`) and use your own web server to host
+it wherever you want.
 
-Since the docs site is static, you can grab the directory from the container
-(under `/usr/share/nginx/html`) and use your own web server to host
-it wherever you want. Replace `<destination>` with the directory where the
-docs will be copied to:
+Use the following commands, and replace `<destination>` with the directory where the
+documentation files will be copied to:
 
 ```shell
 docker create -it --name gitlab-docs registry.gitlab.com/gitlab-org/gitlab-docs:14.5
@@ -93,32 +114,18 @@ docker rm -f gitlab-docs
 
 ## Redirect the `/help` links to the new docs page
 
-When the docs site is up and running:
-
-1. [Enable the help page redirects](../user/admin_area/settings/help_page.md#redirect-help-pages).
-   Use the Fully Qualified Domain Name as the docs URL. For example, if you
-   used the [Docker method](#host-the-docs-site-using-docker) , enter `http://0.0.0.0:4000`.
-   You don't need to append the version, it is detected automatically.
-1. Test that everything works by selecting the **Learn more** link on the page
-   you're on. Your GitLab version is automatically detected and appended to the docs URL
-   you set in the admin area. In this example, if your GitLab version is 14.5,
-   `https://<instance_url>/` becomes `http://0.0.0.0:4000/14.5/`.
-   The link inside GitLab link shows as
-   `<instance_url>/help/user/admin_area/settings/help_page#destination-requirements`,
-   but when you select it, you are redirected to
-   `http://0.0.0.0:4000/14.5/ee/user/admin_area/settings/help_page/#destination-requirements`.
-
-## Caveats
-
-- You need to host the docs site under a subdirectory matching your GitLab version,
-  in the example of this guide `14.5/`. The
-  [Docker images](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635)
-  hosted by the Docs team provide this by default. We use a
-  [script](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/2995d1378175803b22fb8806ba77adf63e79f32c/scripts/normalize-links.sh#L28-82)
-  to normalize the links and prefix them with the respective version.
-- The version dropdown will show more versions which do not exist and will lead
-  to 404 if selected.
-- The search results point to `docs.gitlab.com` and not the local docs.
-- When you use the Docker images to serve the docs site, the landing page redirects
-  by default to the respective version, for example `/14.5/`, so you don't
-  see the landing page as seen at <https://docs.gitlab.com>.
+After your local product documentation site is running, [redirect the help
+links](../user/admin_area/settings/help_page.md#redirect-help-pages) in the GitLab
+application to your local site.
+
+Be sure to use the fully qualified domain name as the docs URL. For example, if you
+used the [Docker method](#self-host-the-product-documentation-with-docker), enter `http://0.0.0.0:4000`.
+
+You don't need to append the version, as GitLab will detect it and append it to
+any documentation URL requests, as needed. For example, if your GitLab version is
+14.5, the GitLab Docs URL becomes `http://0.0.0.0:4000/14.5/`. The link
+inside GitLab displays as `<instance_url>/help/user/admin_area/settings/help_page#destination-requirements`,
+but when you select it, you are redirected to
+`http://0.0.0.0:4000/14.5/ee/user/admin_area/settings/help_page/#destination-requirements`.
+
+To test the setting, select a **Learn more** link within the GitLab application.