Skip to content

Make the docs URL configurable in the admin area

Description

This was previously discussed in gitlab-foss#32514 (closed), but we should revisit this plan as we're getting closer to &693 (closed).

Removing support of inline docs (#26046 (closed)) means that we'll start redirecting the existing docs links inside GitLab to docs.gitlab.com. There are some occasions though, where users may not want to use this URL for their own reasons, for example if GitLab is deployed in an environment where it's heavily firewalled with no internet access.

From gitlab-foss#18739 (comment 29211966)

Some environments do not allow user workstations to access the internet. A solution to this would be to allow GitLab server admins to modify the URL that /help leads to and allow admins to host the gitlab-com/gitlab-docs static site on their own servers.

Proposal

Make the docs URL configurable in GitLab's admin area defaulting to https://docs.gitlab.com/. Admins can change that to point to their own URL. We will provide the docs site as a tarball that users will be able to download and deploy on their own servers (gitlab-docs#390 (closed)). Versioning should be taken into account too.

That implies that the helper method help_page_path should be modified and change from <gitlab_url>/help/ to <docs_url>/X.Y/ee/, where X.Y is the current GitLab version. For GitLab.com, we would omit the version.

For example:

= link_to 'Learn more', help_page_path('user/profile/preferences', anchor: 'syntax-highlighting-theme'), target: '_blank'

is now rendering to:

<gitlab_url>/help/user/profile/preferences.md#syntax-highlighting-theme

With this proposal and the default docs URL value, that would need to change to:

For GitLab.com:

https://docs.gitlab.com/ee/user/profile/preferences.html#syntax-highlighting-theme

For self-hosted:

https://docs.gitlab.com/12.4/ee/user/profile/preferences.html#syntax-highlighting-theme

And if someone changes the default docs URL, this would become:

https://example.com/12.4/ee/user/profile/preferences.html#syntax-highlighting-theme

We should also make sure that all URLs open in a new link (target: '_blank').

Edited by Achilleas Pipinellis