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 tohttps://docs.gitlab.com/<version>/<edition>/
where:- edition is
ce
oree
and - version is the minor version of the instance; e.g.
12.0
,12.1
, etc.
- edition is
- 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 wheresource
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