ローカル環境の作成

サイト構造 GitHub Docs について

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

現在は、Express を利用した動的な Node.js Web サーバーであり、ミドルウェアを使用して適切な HTTP リダイレクト、言語ヘッダー検出、動的コンテンツ生成をサポートし、Free、Pro、&GitHub など、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" インストーラーをダウンロードします。必要なノードのバージョンを確認するには、package.json リポジトリでGitHub Docs ファイルを確認できます。 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 リポジトリの環境のトラブルシューティングを参照してください。

さまざまな言語の有効化

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

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

メモ

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

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

GitHub Codespaces の使用

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

GitHubドキュメントでの作業にコードスペースを使用する方法の詳細については、AUTOTITLE を参照してください。

この記事で