Skip to content

Change the path of /help links in the UI to point to public docs site and/or locally hosted docs site

Description

As part of removing GitLab's documentation from being rendered in GitLab at /help, we need to change the way we generate the links to docs in various UI areas so that there is an option of linking to the public doc page within the right docs.gitlab.com version/edition path instead of /help.

Note: This issue does not yet take into account how to link to a future air-gapped doc site that would replace /help #214164 (comment 382816582). It was authored with the idea that all links would change to docs.gitlab.com links, but this is no longer the plan. &2883 (closed)

For example, a help path currently stored in GitLab as /user/project/pages/index
currently renders as https://<instance_url>/help/user/project/pages/index.md
but would become https://docs.gitlab.com/12.0/ee/user/project/pages/index.html

The /help links are stored:

  • CE: app/views (example), app/helpers/ (example)
  • EE: all the above + ee/app/views (example) + ee/app/helpers (example)
  • Some are also used in app/assets/javascripts (hardcoded links to the docs site) (example).

Proposal

  • The helper method help_page_path should be modified so that the path is no longer appended to <gitlab_url>/help/ but instead to https://docs.gitlab.com/<version>/<edition>/ where:
    • edition is ce or ee and
    • version is the minor version of the instance; e.g. 12.0, 12.1, etc.
  • When building the URL, the file extension automatically appended to the path should be .html. Currently, no extension is provided, BUT the internal links work the same when you append .md or .html.
  • The final rendered URLs in GitLab should be of the format. https://docs.gitlab.com/<version>/<edition>/<help_page_path>.html#<anchor>

Here's an example doc and how it would render:

Doc location relative to CE repository Rails helper path URL under /help URL in the docs site
doc/user/profile/preferences.md help_page_path('user/profile/preferences', anchor: 'syntax-highlighting-theme') https://gitlab.com/help/user/profile/preferences#syntax-highlighting-theme https://docs.gitlab.com/13.0/ee/user/profile/preferences.html#syntax-highlighting-theme

In short, the help_page_path helper, would need to prepend https://docs.gitlab.com/<version>/<edition>/ and append .html to the included string.

Needs

  • The html extension should be explicitly added to links.
  • All URLs should open in a new window/tab (target: '_blank').
  • Version and edition variables need to be populated and included in the URL.
  • Confirm that doc URLs rendered in GitLab are updated to the format:
    https://docs.gitlab.com/<version>/<edition>/<help_page_path>.html#<anchor>
  • Convert hardcoded links in app/assets/javascripts to use docs.gitlab.com
  • Export all new URLs for a 404 check to be performed by the Technical Writing team; a CSV of the format source,url would work well where source is app/<path>/<file> where the link is included. Example output below:
source,url
/app/views/profiles/preferences/show.html.haml,https://docs.gitlab.com/ee/user/profile/preferences.html
  • Ensure the "Help" link under the top-right nav icon is also updated to https://docs.gitlab.com/<version>/<edition>/
Edited by Mike Lewis