diff options
Diffstat (limited to 'doc/development/documentation/index.md')
| -rw-r--r-- | doc/development/documentation/index.md | 51 |
1 files changed, 31 insertions, 20 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index a597ea512c6..75538fe1fe7 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -108,23 +108,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w If you need help determining the correct stage, read [Ask for help](workflow.md#ask-for-help). -### Document type metadata - -Originally discussed in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/1280), -each page should have a metadata tag called `type`. It can be one or more of the -following: - -- `index`: It consists mostly of a list of links to other pages. - [Example page](../../index.md). -- `concepts`: The background or context of a subject. - [Example page](../../topics/autodevops/index.md). -- `howto`: Specific use case instructions. - [Example page](../../ssh/index.md). -- `tutorial`: Learn a process/concept by doing. - [Example page](../../gitlab-basics/start-using-git.md). -- `reference`: A collection of information used as a reference to use a feature - or a functionality. [Example page](../../ci/yaml/index.md). - ### Redirection metadata The following metadata should be added when a page is moved to another location: @@ -154,7 +137,12 @@ Each page can have additional, optional metadata (set in the [default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) Nanoc layout), which is displayed at the top of the page if defined. -## Move or rename a page +### Deprecated metadata + +The `type` metadata parameter is deprecated but still exists in documentation +pages. You can safely remove the `type` metadata parameter and its values. + +## Move, rename, or delete a page See [redirects](redirects.md). @@ -214,8 +202,10 @@ with the following conventions: The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/helping-users/#formatting-help-content). -Use the following special cases depending on the context, ensuring all links -are inside `_()` so they can be translated: +#### 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: @@ -260,6 +250,27 @@ helpPagePath('user/permissions', { anchor: 'anchor-link' }) 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' +_('This is a text describing the option/feature in a sentence. %{docs_link}').html_safe % { docs_link: docs_link.html_safe } +``` + +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' +_('This is a text describing the option/feature in a sentence. %{docs_link}').html_safe % { docs_link: docs_link.html_safe } +``` + +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). + ### GitLab `/help` tests Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb) |