Skip to content

Change the path of the internal /help links to point to the external docs

Description

As part of removing GitLab's documentation from being rendered in GitLab CE/EE at /help, we need to change the way we generate the links to docs in various UI areas so that they link to the doc within the right docs.gitlab.com version/edition path instead of /help.

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/12.0/ce/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//. Example output below:
source,url
/app/views/profiles/preferences/show.html.haml,https://docs.gitlab.com/ee/user/profile/preferences.html
Edited by Mike Lewis