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 thegitlab-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'
).