ローカル環境の作成

お使いのコンピューターのローカル環境で GitHub Docs アプリケーションを実行できます。

この記事の内容

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 キーをを押します。

注: 通常は、ブランチの最新バージョンをプルするたびに、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 の操作」をご覧ください。

参考資料