ローカル環境の作成

GitHub Docs のサイト構造について

最初の GitHub Docs サイトは、Ruby on Rails Web アプリケーションでした。しばらくしてから、Jekyll を利用する静的サイトに変換されました。その数年後、別の Ruby 静的サイトジェネレーターである Nanoc に移行されました。

現在、これは Express を搭載した動的な Node.js Web サーバーであり、ミドルウェアを使用して適切な HTTP リダイレクト、言語ヘッダーの検出をサポートしています。また、Free, Pro, & Team や GitHub Enterprise Server など、さまざまな種類の GitHub の製品ドキュメントに対応する動的コンテンツの生成をサポートしています。

このサイトのツールは長年にわたって変更されていますが、元の Jekyll サイトの実績のある作成規則の多くはそのまま残されています。

内容は Markdown ファイルで書かれており、content ディレクトリにあります。

data ディレクトリのファイルは、{% data %} タグを使うことでテンプレートで使用できます。
Markdown ファイルにはフロントマターを含めることができます。
redirect_from の Jekyll プラグイン動作がサポートされています。

ローカル環境を設定する

GitHub Docs リポジトリをクローンして初期セットアップを行うと、コンピューターのローカル環境でアプリケーションを実行できます。

Node.js のインストール

GitHub Docs サイトでは、Node.js が利用されています。それは、macOS、Windows、Linux の環境で実行されます。

サイトを実行するには、Node.js が必要です。 Node.js をインストールするには、nodejs.org から "LTS" インストーラーをダウンロードします。必要な Node のバージョンは、GitHub Docs リポジトリの package.json ファイルで確認できます。 Node のバージョンは、次の例のように engine フィールドに列記されています。これは、Node メジャーバージョン 16 または Node メジャーバージョン 18 を使用できることを示します。

"engines": {
    "node": "^16 || ^18"
}

nodenv を使っている場合、Node.js のバージョンを切り替える手順については nodenv のドキュメントをご覧ください。

ローカル GitHub Docs サーバーの起動

Node.js をインストールしたら (これには、一般的な npm パッケージマネージャーが含まれます)、ターミナルを開いて、次のコマンドを実行します。

git clone https://github.com/github/docs
cd docs
npm ci
npm start

サーバーが実行されるようになるはずです。ローカルプレビュー環境にアクセスするには、ブラウザーで localhost:4000 にアクセスします。

ローカルサーバーを停止する準備ができたら、ターミナルウィンドウで Ctrl + C キーをを押します。

注: 通常は、ブランチの最新バージョンをプルするたびに、npm ci と npm run build を実行することだけが必要です。

npm ci では、依存関係のクリーンインストールが行われ、package-lock.json ファイルは更新されません。
npm run build では、JavaScript ファイルや CSS ファイルなどの静的アセットが作成されます。

GitHub Docs アプリケーションのデバッグとトラブルシューティングについて詳しくは、github/docs リポジトリの「環境のトラブルシューティング」をご覧ください。

ブラウザーショートカットの使用

GitHub Docs リポジトリの src/bookmarklets ディレクトリには、GitHub ドキュメントの確認に役立つブラウザーショートカットが含まれています。詳しくは、ディレクトリの README をご覧ください。

さまざまな言語の有効化

ローカルサーバーの既定の実行では、サポートされている言語の一部だけが有効になっています。特定の言語でローカルサーバーを実行する必要がある場合は、package.json の start スクリプトを一時的に編集して、ENABLED_LANGUAGES 変数を更新できます。

たとえば、英語に加えて日本語とポルトガル語を有効にするには、package.json を編集して、start スクリプトで ENABLED_LANGUAGES='en,ja,pt' を設定できます。その後、サーバーを再起動して変更を有効にします。

注: 変更をコミットする前に、package.json ファイルを元の状態に戻す必要があります。

サポートされる言語コードは、src/languages/lib/languages.js で定義されています。

GitHub Codespaces の使用

ローカル環境で GitHub Docs を実行する代わりに、GitHub Codespaces を使用できます。 GitHub Codespaces を使うと、ブラウザーから直接変更を編集、プレビュー、テストできます。

GitHub ドキュメントでの作業に codespace を使う方法について詳しくは、「codespace での GitHub Docs の操作」をご覧ください。

この記事の内容