gitlab-ce/doc/development/documentation/help.md

stage	group	info
none	Documentation Guidelines	For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.

GitLab /help

Every GitLab instance includes documentation at /help (https://gitlab.example.com/help) that matches the version of the instance. For example, https://gitlab.com/help.

The documentation available online at https://docs.gitlab.com is deployed every hour from the default branch of GitLab, Omnibus, Runner, Charts, and Operator. After a merge request that updates documentation is merged, it is available online in an hour or less.

However, it's only available at /help on self-managed instances in the next released version. The date an update is merged can impact which self-managed release the update is present in.

For example:

1. A merge request in gitlab updates documentation. It has a milestone of 14.4, with an expected release date of 2021-10-22.
2. It is merged on 2021-10-19 and available online the same day at https://docs.gitlab.com.
3. GitLab 14.4 is released on 2021-10-22, based on the gitlab codebase from 2021-10-18 (one day before the update was merged).
4. The change shows up in the 14.5 self-managed release, due to missing the release cutoff for 14.4.

If it is important that a documentation update is present in that month's release, merge it as early as possible.

Page mapping

Requests to /help can be redirected. If redirection is turned off, /help maps requests for help pages to specific files in the doc directory. For example:

• Requested URLs: <gdk_instance>/help/topics/plan_and_track.md, <gdk_instance>/help/topics/plan_and_track.html and <gdk_instance>/help/topics/plan_and_track.
• Mapping: doc/topics/plan_and_track.md.

_index.md files

• Support for _index.md files introduced in GitLab 16.10.

The Hugo static site generator makes use of _index.md files. To allow for index pages to be named either index.md or _index.md in /help, GitLab maps requests for index.md, index.html, or index:

• To index.md if the file exists at the requested location.
• Otherwise, to _index.md.

For example:

• Requested URLs: <gdk_instance>/help/user/index.md, <gdk_instance>/help/user/index.html, and <gdk_instance>/help/user/index.
• Mapping:
  • doc/user/index.md if it exists.
  • Otherwise, to doc/user/_index.md.

Source files

/help can render Markdown files with the level 1 heading either:

• Specified in YAML front matter using title. For example, title: My Markdown file. Introduced in GitLab 16.10.
• Specified in the Markdown itself. For example, # My Markdown file.

You should not specify the level 1 heading for a page using both methods at the same time, otherwise the level 1 heading is repeated.

Linking to /help

When you're building a new feature, you may need to link to the documentation from the GitLab application. This is usually done in files inside the app/views/ directory, with the help of the help_page_path helper method.

The help_page_path contains the path to the document you want to link to, with the following conventions:

• It's relative to the doc/ directory in the GitLab repository.
• It omits the .md extension.
• It doesn't end with a forward slash (/).

The help text follows the Pajamas guidelines.

Linking to /help in HAML

Use the following special cases depending on the context, ensuring all link text is inside _() so it can be translated:

• Linking to a doc page. In its most basic form, the HAML code to generate a link to the /help page is:

  = link_to _('Learn more.'), help_page_path('user/permissions'), target: '_blank', rel: 'noopener noreferrer'
  

• Linking to an anchor link. Use anchor as part of the help_page_path method:

  = link_to _('Learn more.'), help_page_path('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer'
  

• Using links inline of some text. First, define the link, and then use it. In this example, link_start is the name of the variable that contains the link:

  - link = link_to('', help_page_path('user/permissions'), target: '_blank', rel: 'noopener noreferrer')
  %p= safe_format(_("This is a text describing the option/feature in a sentence. %{link_start}Learn more.%{link_end}"), tag_pair(link, :link_start, :link_end))
  

• Using a button link. Useful in places where text would be out of context with the rest of the page layout:

  = link_to _('Learn more.'), help_page_path('user/permissions'),  class: 'btn btn-info', target: '_blank', rel: 'noopener noreferrer'
  

Linking to /help in JavaScript

To link to the documentation from a JavaScript or a Vue component, use the helpPagePath function from help_page_helper.js:

import { helpPagePath } from '~/helpers/help_page_helper';

helpPagePath('user/permissions', { anchor: 'anchor-link' })
// evaluates to '/help/user/permissions#anchor-link' for GitLab.com

This is preferred over static paths, as the helper also works on instances installed under a relative URL.

Linking to /help in Ruby

To link to the documentation from within Ruby code, use the following code block as a guide, ensuring all link text is inside _() so it can be translated:

docs_link = link_to _('Learn more.'), help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer'
safe_format(_('This is a text describing the option/feature in a sentence. %{docs_link}'), docs_link: docs_link)

In cases where you need to generate a link from outside of views/helpers, where the link_to and help_page_url methods are not available, use the following code block as a guide where the methods are fully qualified:

docs_link = ActionController::Base.helpers.link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer'
safe_format(_('This is a text describing the option/feature in a sentence. %{docs_link}'), docs_link: docs_link)

Do not use include ActionView::Helpers::UrlHelper just to make the link_to method available as you might see in some existing code. Read more in issue 340567.

/help tests

Several RSpec tests are run to ensure GitLab documentation renders and works correctly. In particular, that main docs landing page works correctly from /help. For example, GitLab.com's /help.