ドキュメントサイトアーキテクチャ

gitlab-docs プロジェクトは GitLab ドキュメントウェブサイトを生成するために使用されるリポジトリをホストし、https://docs.gitlab.comにデプロイされます。 これはNanoc静的サイトジェネレータを使用しています。

アーキテクチャ

ドキュメントコンテンツのソースはGitLabの各製品リポジトリに保存されていますが、_そのコンテンツから_ドキュメントサイトを構築するために使われるソースはhttps://gitlab.com/gitlab-org/gitlab-docs。

次の図は、コンテンツの出所となるリポジトリ、gitlab-docs プロジェクト、公開されたアウトプットの関係を示しています。

graph LR A[gitlab/doc] B[gitlab-runner/docs] C[omnibus-gitlab/doc] D[charts/doc] E[gitlab-docs] A --> E B --> E C --> E D --> E E -- Build pipeline --> F F[docs.gitlab.com] G[/ce/] H[/ee/] I[/runner/] J[/omnibus/] K[/charts/] F --> H F --> I F --> J F --> K H -- symlink --> G

gitlab-docs リポジトリには GitLab docs のコンテンツはありません。すべてのドキュメントファイルは各製品のリポジトリにホストされており、docs ウェブサイトを生成するためにすべて一緒にプルされます：

注：2019年9月、私たちは単一のコードベースに移行し、CEとEEのドキュメントは同一になりました。 歴史的な理由とインターネット上の既存のリンクを壊さないために、私たちはまだCEのドキュメント（https://docs.gitlab.com/ce/）をメンテナーしていますが、それはウェブサイトから隠されており、現在はEEのドキュメントへのシンボリックリンクになっています。 Pagesがリダイレクトをサポートするようになれば、これを完全に削除できるようになります。

資産

最適化されたサイト構造、デザイン、検索エンジンフレンドリーなウェブサイト、そして発見しやすいドキュメンテーションを提供するために、GitLabドキュメンテーションウェブサイトではいくつかのアセットを使用しています。

図書館

SEO

グローバルナビゲーションのドキュメントを読んで理解してください：

  • グローバルナビゲーションの構築方法
  • 新しいナビゲーション項目の追加方法

パイプライン

gitlab-docs プロジェクトのパイプライン：

  • docsサイトのコードの変更をテストします。
  • 様々なパイプラインジョブで使用されるDockerイメージをビルドします。
  • docsサイト自体のビルドとデプロイを行います。
  • review-docs-deploy ジョブがトリガーされると、レビューアプリを生成します。

ドキュメントサイトのDockerイメージの再構築

週に一度月曜日に、スケジュールされたパイプラインが実行され、docs-lintのような様々なパイプラインジョブで使用されるDockerイメージが再構築されます。 Dockerイメージの設定ファイルはDockerfilesディレクトリにあります。

すぐにDockerイメージを再構築する必要がある場合（メンテナー・レベルの権限が必要です）：

注意dockerfile の設定を変更してイメージを再構築すると、メインのgitlab リポジトリとgitlab-docsのマスターパイプラインが壊れる可能性があります。まず別の名前でイメージを作成し、パイプラインが壊れないかテストしてください。
  1. gitlab-docsで、 CI / CD > Pipelinesに進みます。
  2. パイプラインの実行ボタンをクリックします。
  3. 新しいパイプラインが実行されていることを確認します。 画像を構築するジョブは最初のステージにあります。build-imagesパイプライン番号をクリックすると大きなパイプライングラフがbuild-images表示され、ミニパイプライングラフのbuild-images最初の（build-images）ステージbuild-imagesをクリックbuild-imagesすると画像を構築するジョブが表示されます。
  4. 再構築したい画像の横にある再生（{play}）ボタンをクリックします。
    • 通常、image:gitlab-docs-base イメージはほとんど変更されないため、再構築する必要はありません。再構築が必要な場合は、再構築が終了した後にimage:docs-lintを実行するようにしてください。

ドキュメントサイトのデプロイ

4時間ごとに、スケジュールされたパイプラインがdocsサイトのビルドとデプロイを行います。パイプラインはメインプロジェクトのmasterブランチから現在のdocsを取得し、Nanocでビルドし、https://docs.gitlab.comにデプロイします。

すぐにサイトをビルドしてデプロイする必要がある場合（メンテナー・レベルの権限が必要です）：

  1. gitlab-docsで、 CI / CD > Schedulesに進みます。
  2. Build docs.gitlab.com every 4 hours スケジュールされたパイプラインの場合は、再生({play})ボタンをクリックします。

YAMLデータファイルの使用

NanocでJekyllのデータファイルと同様のものを実現する最も簡単な方法は、@items変数を使用することです。

データファイルはcontent/ ディレクトリ内部に配置し、ERBテンプレートで参照できるようにする必要があります。

content/_data/versions.yaml という内容のファイルがあるとします： 

versions:
  - 10.6
  - 10.5
  - 10.4

そして、versions 配列を次のようにループします： 

<% @items['/_data/versions.yaml'][:versions].each do | version | %>

<h3><%= version %></h3>

<% end &>

データファイルの拡張子はyaml でなければならないこと（ymlではありません）、配列をシンボル（:versions）で参照することに注意してください。

CSSとJavaScriptのバージョンをバンプ

content/assets/ 、カスタムCSSファイルやJavaScriptファイルが変更された場合は、必ずそのバージョンをフロントマターにバンプしてください。この方法は、以前のファイルのキャッシュをクリアすることで、変更が反映されることを保証します。

これらのファイルを含めるには、常にNanocの方法を使用し、レイアウトにハードコードしないでください。 例えば、次のように使用します： 

<script async type="application/javascript" src="<%= @items['/assets/javascripts/badges.*'].path %>"></script>

<link rel="stylesheet" href="<%= @items['/assets/stylesheets/toc.*'].path %>">

ファイルを指すリンクは次のようなものでなければなりません： 

<%= @items['/path/to/assets/file.*'].path %>

Nanocは、Rulesで定義された内容に従って、これらのリンクを構築し、正しくレンダリングします。

ソースファイルへのリンク

edit_on_gitlab というヘルパーを使うと、ページのソースファイルにリンクできます。シンプルなエディタとWeb IDEの両方にリンクできます。 Nanocレイアウトでの使い方を紹介します：

  • デフォルトのエディタ：<a href="<%= edit_on_gitlab(@item, editor: :simple) %>">Simple editor</a>
  • ウェブIDE：<a href="<%= edit_on_gitlab(@item, editor: :webide) %>">Web IDE</a>

editor:を指定しない場合、デフォルトでシンプルなものが使用されます。

アルゴリア検索エンジン

ドキュメントサイトは、検索機能にAlgolia DocSearchを使用しています。 このように動作します：

  1. GitLabはAlgoliaの無料ティアであるDocSearchプログラムのメンバーです。
  2. アルゴリアは GitLab ドキュメントサイトのDocSearch 設定をホストしており、私たちはそれを改良するために協力してきました。
  3. この設定は24時間ごとにクローラーによって解析され、DocSearchインデックスがアルゴリアのサーバーに保存されます。
  4. ドキュメント側では、独自のレイアウトを使用しているhttps://docs.gitlab.com/search/以外のほとんど全てのページに存在するDocSearch レイアウトを使用しています。これらのレイアウトでは、Algolia が結果を表示するために必要な API キーとインデックス名 (gitlab) を使用して DocSearch を開始する JavaScript スニペットがあります。
GitLab従業員の方へ：Algoliaダッシュボードにアクセスするための認証情報は1Passwordに保存されています。 検索の使用状況に関する週次レポートを受け取りたい場合は、GoogleドキュメントをタイトルEmail, Slack, and GitLab Groups and Aliasesで検索し、docsearchを検索して、週次レポートを受け取るエイリアスに追加されるあなたのEメールをコメントとして追加してください。

月次リリースプロセス（バージョン）

docsのウェブサイトはバージョンをサポートしており、毎月最新のものをリストに追加しています。 詳細については、毎月のリリースの流れをお読みください。

ドキュメントマージリクエストのレビューアプリ

GitLab ドキュメントに貢献している場合は、マージリクエストごとにレビューアプリを作成する方法をお読みください。