1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
---
stage: none
group: Documentation Guidelines
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# 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.
1. It is merged on 2021-10-19 and available online the same day at <https://docs.gitlab.com>.
1. 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).
1. The change shows up in the 14.5 self-managed release, due to missing the release cutoff
for 14.4.
The exact cutoff date for each release is flexible, and can be sooner or later
than expected due to holidays, weekends or other events. In general, MRs merged
by the 17th should be present in the release on the 22nd, though it is not guaranteed.
If it is important that a documentation update is present in that month's release,
merge it as early as possible.
## 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](https://design.gitlab.com/usability/contextual-help#formatting-help-content).
### 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:
```haml
= 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:
```haml
= 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:
```haml
- 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:
```haml
= 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`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/helpers/help_page_helper.js):
```javascript
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](../../install/relative_url.md).
### 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:
```ruby
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:
```ruby
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](https://gitlab.com/gitlab-org/gitlab/-/issues/340567).
## `/help` tests
Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb)
are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../index.md) works correctly from `/help`.
For example, [GitLab.com's `/help`](https://gitlab.com/help).
|
