ローカル環境の作成

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

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

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

このサイトのツールは長年にわたって変更されていますが、元の 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 キーをを押します。

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

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

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

さまざまな言語の有効化

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

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

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

GitHub Codespaces の使用

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

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

参考資料

• 再利用可能なコンテンツの作成
• Components
• Data
• テスト