• リンク先/help
  • HAML の/help へのリンク
  • JavaScriptで/help 。
  • Rubyで/help 。
• /help テスト

GitLab /help

すべてのGitLabインスタンスには、インスタンスのバージョンに合ったドキュメントが/help (https://gitlab.example.com/help) に含まれています。例えば、https://gitlab.com/help。

https://docs.gitlab.com でオンラインで利用可能なドキュメントは、GitLab、Omnibus、Runner、Charts、Operatorのデフォルトブランチから1時間ごとにデプロイされます。ドキュメントを更新するマージリクエストがマージされると、1時間以内にオンラインで利用できるようになります。

ただし、/help 、次のリリースバージョンのセルフマネージドインスタンスでのみ利用可能です。アップデートがマージされた日付は、そのアップデートがどの自己管理リリースに存在するかに影響します。

使用例：

1. gitlab のマージリクエストはドキュメントを更新します。マイルストーンは 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のセルフマネージドリリースに反映されます。

ドキュメントの更新がその月のリリースに存在することが重要であれば、できるだけ早くマージしてください。

リンク先/help

新しい機能をビルドするとき、GitLabアプリケーションからドキュメントにリンクする必要があるかもしれません。これは通常、app/views/ ディレクトリ内部のファイルで行います。help_page_path ヘルパーメソッドを使います。

help_page_path には、リンクしたいドキュメントへのパスを次のような規則で記述します：

• GitLabリポジトリ内のdoc/ ディレクトリからの相対パスです。
• .md の拡張子は省略されています。
• フォワードスラッシュ (/) で終わっていません。

ヘルプテキストはパジャマのガイドラインに従っています。

HAML の/help へのリンク

すべてのリンクテキストが_() の内部にあることを確認して、翻訳できるようにします：

• docページへのリンク。最も基本的な形式では、/help ページへのリンクを生成する HAML コードは次のようになります：

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

• アンカーリンクへのリンク。help_page_path メソッドの一部としてanchor を使用します：

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

• テキストのインラインでリンクを使用します。まず、リンクを定義し、それを使用します。この例では、link_start がリンクを含む変数名です：

   - 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))
  

• ボタンリンクの使用。テキストがページレイアウトの他の部分と文脈がずれてしまうような場所に便利です：

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

JavaScriptで/help 。

JavaScriptまたはVueコンポーネントからドキュメントにリンクするには、help_page_helper.js のhelpPagePath 関数を使用します：

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

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

このヘルパーは、相対URLでインストールされたインスタンスでも動作するため、静的パスよりもこちらの方が推奨されます。

Rubyで/help 。

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)

views/helpersの外部からリンクを生成する必要があり、link_to とhelp_page_url のメソッドが利用できない場合は、メソッドが完全に修飾されている以下のコードブロックを参考にしてください：

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)

既存のコードに見られるように、link_to メソッドを使用可能にするためだけにinclude ActionView::Helpers::UrlHelper を使用しないでください。詳しくはイシュー340567をご覧ください。

/help テスト

GitLab ドキュメントが正しくレンダリングされ、動作することを確認するために、いくつかのRSpec テストが実行されています。特に、メインのdocsランディングページが /help。例えば、GitLab.com の/help。