- アーキテクチャ
- 資産
- グローバルナビゲーション
- パイプライン
- YAMLデータファイルの使用
- CSSとJavaScriptのバージョンをバンプ
- ソースファイルへのリンク
- アルゴリア検索エンジン
- 月次リリースプロセス(バージョン)
- ドキュメントマージリクエストのレビューアプリ
ドキュメントサイトアーキテクチャ
gitlab-docs
プロジェクトは GitLab ドキュメントウェブサイトを生成するために使用されるリポジトリをホストし、https://docs.gitlab.comにデプロイされます。 これはNanoc静的サイトジェネレータを使用しています。
アーキテクチャ
ドキュメントコンテンツのソースはGitLabの各製品リポジトリに保存されていますが、_そのコンテンツから_ドキュメントサイトを構築するために使われるソースはhttps://gitlab.com/gitlab-org/gitlab-docs。
次の図は、コンテンツの出所となるリポジトリ、gitlab-docs
プロジェクト、公開されたアウトプットの関係を示しています。
gitlab-docs
リポジトリには GitLab docs のコンテンツはありません。すべてのドキュメントファイルは各製品のリポジトリにホストされており、docs ウェブサイトを生成するためにすべて一緒にプルされます:
https://docs.gitlab.com/ce/
)をメンテナーしていますが、それはウェブサイトから隠されており、現在はEEのドキュメントへのシンボリックリンクになっています。 Pagesがリダイレクトをサポートするようになれば、これを完全に削除できるようになります。資産
最適化されたサイト構造、デザイン、検索エンジンフレンドリーなウェブサイト、そして発見しやすいドキュメンテーションを提供するために、GitLabドキュメンテーションウェブサイトではいくつかのアセットを使用しています。
図書館
SEO
グローバルナビゲーション
グローバルナビゲーションのドキュメントを読んで理解してください:
- グローバルナビゲーションの構築方法
- 新しいナビゲーション項目の追加方法
パイプライン
gitlab-docs
プロジェクトのパイプライン:
- docsサイトのコードの変更をテストします。
- 様々なパイプラインジョブで使用されるDockerイメージをビルドします。
- docsサイト自体のビルドとデプロイを行います。
-
review-docs-deploy
ジョブがトリガーされると、レビューアプリを生成します。
ドキュメントサイトのDockerイメージの再構築
週に一度月曜日に、スケジュールされたパイプラインが実行され、docs-lint
のような様々なパイプラインジョブで使用されるDockerイメージが再構築されます。 Dockerイメージの設定ファイルはDockerfilesディレクトリにあります。
すぐにDockerイメージを再構築する必要がある場合(メンテナー・レベルの権限が必要です):
gitlab
リポジトリとgitlab-docs
のマスターパイプラインが壊れる可能性があります。まず別の名前でイメージを作成し、パイプラインが壊れないかテストしてください。-
gitlab-docs
で、 CI / CD > Pipelinesに進みます。 - パイプラインの実行ボタンをクリックします。
- 新しいパイプラインが実行されていることを確認します。 画像を構築するジョブは最初のステージにあります。
build-images
パイプライン番号をクリックすると大きなパイプライングラフがbuild-images
表示され、ミニパイプライングラフのbuild-images
最初の(build-images
)ステージbuild-images
をクリックbuild-images
すると画像を構築するジョブが表示されます。 - 再構築したい画像の横にある再生({play})ボタンをクリックします。
- 通常、
image:gitlab-docs-base
イメージはほとんど変更されないため、再構築する必要はありません。再構築が必要な場合は、再構築が終了した後にimage:docs-lint
を実行するようにしてください。
- 通常、
ドキュメントサイトのデプロイ
4時間ごとに、スケジュールされたパイプラインがdocsサイトのビルドとデプロイを行います。パイプラインはメインプロジェクトのmasterブランチから現在のdocsを取得し、Nanocでビルドし、https://docs.gitlab.comにデプロイします。
すぐにサイトをビルドしてデプロイする必要がある場合(メンテナー・レベルの権限が必要です):
-
gitlab-docs
で、 CI / CD > Schedulesに進みます。 -
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を使用しています。 このように動作します:
- GitLabはAlgoliaの無料ティアであるDocSearchプログラムのメンバーです。
- アルゴリアは GitLab ドキュメントサイトのDocSearch 設定をホストしており、私たちはそれを改良するために協力してきました。
- この設定は24時間ごとにクローラーによって解析され、DocSearchインデックスがアルゴリアのサーバーに保存されます。
- ドキュメント側では、独自のレイアウトを使用しているhttps://docs.gitlab.com/search/以外のほとんど全てのページに存在するDocSearch レイアウトを使用しています。これらのレイアウトでは、Algolia が結果を表示するために必要な API キーとインデックス名 (
gitlab
) を使用して DocSearch を開始する JavaScript スニペットがあります。
Email, Slack, and GitLab Groups and Aliases
で検索し、docsearch
を検索して、週次レポートを受け取るエイリアスに追加されるあなたのEメールをコメントとして追加してください。月次リリースプロセス(バージョン)
docsのウェブサイトはバージョンをサポートしており、毎月最新のものをリストに追加しています。 詳細については、毎月のリリースの流れをお読みください。
ドキュメントマージリクエストのレビューアプリ
GitLab ドキュメントに貢献している場合は、マージリクエストごとにレビューアプリを作成する方法をお読みください。