GitLab /help

每个 GitLab 实例都包含在 /help（https://gitlab.example.com/help）的文档，这些文档与实例的版本相匹配。例如，https://gitlab.com/help。

在线上 https://docs.gitlab.com 可用的文档，每小时从 GitLab、Omnibus、Runner、Charts 和 Operator 的默认分支部署一次。更新文档的 merge request 合并后，在线上文档中最多一小时内即可看到。

但是，这些更新只有在 GitLab 自托管实例的下一个发布版本中才能在 /help 中看到。更新的合并日期会影响该更新出现在哪个 GitLab 自托管版本中。

例如：

1. gitlab 中的一个 merge request 更新了文档。它有一个 14.4 的里程碑，预计发布日期为 2021-10-22。
2. 它在 2021-10-19 合并，并在同一天在 https://docs.gitlab.com 上线。
3. GitLab 14.4 于 2021-10-22 发布，基于 2021-10-18 的 gitlab 代码库（更新合并前的一天）。
4. 由于错过了 14.4 版本的发布截止日期，这个变更出现在了 14.5 GitLab 自托管版本中。

如果文档更新需要包含在该月的发布版本中，请尽早合并。

页面映射

对 /help 的请求可以被 重定向。如果关闭重定向，/help 会将帮助页面的请求映射到 doc 目录中的特定文件。例如：

• 请求的 URL：<gdk_instance>/help/topics/plan_and_track.md、<gdk_instance>/help/topics/plan_and_track.html 和 <gdk_instance>/help/topics/plan_and_track。
• 映射到：doc/topics/plan_and_track.md。

_index.md 文件

Hugo 静态站点生成器使用 _index.md 文件。为了允许在 /help 中的索引页面可以命名为 index.md 或 _index.md，GitLab 将对 index.md、index.html 或 index 的请求映射为：

• 如果请求的位置存在 index.md 文件，则映射到该文件。
• 否则，映射到 _index.md。

例如：

• 请求的 URL：<gdk_instance>/help/user/index.md、<gdk_instance>/help/user/index.html 和 <gdk_instance>/help/user/index。
• 映射到：
  • 如果 doc/user/index.md 存在，则映射到该文件。
  • 否则，映射到 doc/user/_index.md。

链接到 /help

当您构建新功能时，可能需要从 GitLab 应用程序链接到文档。这通常通过 app/views/ 目录中的文件实现，借助 help_page_path 辅助方法完成。

help_page_path 包含指向目标文档的路径，遵循以下约定：

• 路径相对于 GitLab 仓库中的 doc/ 目录。
• 为清晰起见，应以 .md 文件扩展名结尾。

帮助文本遵循 Pajamas 指南。

在 HAML 中链接到 /help

根据上下文使用以下特殊情况，确保所有链接文本都在 _() 内以便翻译：

• 链接到文档页面。最基本的形式是生成指向 /help 页面的 HAML 代码：

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

• 链接到锚点链接。在 help_page_path 方法中使用 anchor：

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

• 在文本内联使用链接。首先定义链接，然后使用它。在此示例中，link_start 是包含链接的变量名：

  - link = link_to('', help_page_path('user/permissions.md'), 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))

• 使用按钮链接。在文本与页面布局其他部分不协调的地方很有用：

  = render Pajamas::ButtonComponent.new(href: help_page_path('user/group/import/_index.md'), target: '_blank') do
      = _('Learn more')

在 JavaScript 中链接到 /help

要从 JavaScript 或 Vue 组件链接到文档，使用 help_page_helper.js 中的 helpPagePath 函数：

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

helpPagePath('user/permissions.md', { anchor: 'anchor-link' })
// 对于 GitLab.com，评估为 '/help/user/permissions#anchor-link'

这比静态路径更可取，因为该辅助方法也适用于安装在 相对 URL 下的实例。

在 Ruby 中链接到 /help

要从 Ruby 代码中链接到文档，使用以下代码块作为指导，确保所有链接文本都在 _() 内以便翻译：

docs_link = link_to _('Learn more.'), help_page_url('user/permissions.md', 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)

当您需要在视图/辅助方法之外生成链接，而 link_to 和 help_page_url 方法不可用时，使用以下代码块作为指导，其中方法是完全限定的：

docs_link = ActionController::Base.helpers.link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/permissions.md', 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)

不要使用 include ActionView::Helpers::UrlHelper 来使 link_to 方法可用，就像您在某些现有代码中看到的那样。更多信息请参阅 issue 340567。

/help 测试

运行了多个 RSpec 测试 来确保 GitLab 文档正确渲染和工作。特别是确保 主文档首页 从 /help 正常工作。例如，GitLab.com 的 /help。