ドキュメントのデプロイ

ドキュメントを様々なホスティングプロバイダーにデプロイするための基本的なガイド

---

GitHub Pages

プロジェクトのソースコードをGitHubでホストしている場合、GitHub Pagesを使用してプロジェクトのドキュメントを簡単にホストできます。GitHub Pagesサイトには、プロジェクトページサイトと、ユーザーおよび組織ページサイトという2つの基本的なタイプがあります。これらはほぼ同一ですが、重要な違いがあり、デプロイ時に異なるワークフローが必要です。

プロジェクトページ

プロジェクトページサイトは、サイトファイルがプロジェクトリポジトリ内のブランチ（デフォルトではgh-pages）にデプロイされるため、よりシンプルです。プロジェクトのソースドキュメントを維持するGitリポジトリの主要な作業ブランチ（通常はmaster）をcheckoutした後、次のコマンドを実行します。

mkdocs gh-deploy

以上です！バックグラウンドでは、MkDocsがドキュメントをビルドし、ghp-importツールを使用してgh-pagesブランチにコミットし、gh-pagesブランチをGitHubにプッシュします。

mkdocs gh-deploy --helpを使用して、gh-deployコマンドで使用できるオプションの完全なリストを取得します。

GitHubにプッシュされる前に、構築されたサイトを確認することはできません。したがって、事前にbuildまたはserveコマンドを使用して変更を確認し、ローカルで構築されたファイルを確認することをお勧めします。

組織とユーザーページ

ユーザーと組織のページサイトは特定のプロジェクトに関連付けられておらず、サイトファイルはGitHubアカウント名で命名された専用のレポジトリのmasterブランチにデプロイされます。したがって、ローカルシステム上に2つのリポジトリの作業コピーが必要です。たとえば、次のファイル構造を考えます。

my-project/
    mkdocs.yml
    docs/
orgname.github.io/

プロジェクトに対する更新を作成して確認した後、orgname.github.ioリポジトリにディレクトリを変更し、そこからmkdocs gh-deployコマンドを呼び出す必要があります。

cd ../orgname.github.io/
mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master

mkdocs.yml設定ファイルは現在の作業ディレクトリにないため、明示的に指定する必要があります。また、デプロイスクリプトにmasterブランチへのコミットを指示する必要があります。remote_branch設定でデフォルトを上書きできますが、デプロイスクリプトを実行する前にディレクトリを変更するのを忘れると、おそらく望まないプロジェクトのmasterブランチにコミットされます。

カスタムドメイン

GitHub Pagesには、サイトのカスタムドメインの使用がサポートされています。GitHubで説明されている手順に加えて、MkDocsがカスタムドメインで動作するように、追加の手順を実行する必要があります。docs_dirのルートにCNAMEファイルを追加する必要があります。このファイルには、1行に1つのベアードメインまたはサブドメインのみを含める必要があります（MkDocs自身のCNAMEファイルを例として参照してください）。ファイルを手で作成することも、GitHubのWebインターフェースを使用してカスタムドメインを設定することもできます（設定/カスタムドメイン）。Webインターフェースを使用する場合、GitHubはCNAMEファイルを作成し、「pages」ブランチのルートに保存します。ファイルを次にデプロイしたときに削除されないように、docs_dirにファイルをコピーする必要があります。docs_dirにファイルが正しく含まれている場合、MkDocsはgh-deployコマンドを実行するたびに、構築されたサイトにファイルを含め、「pages」ブランチにプッシュします。

カスタムドメインの動作に問題がある場合は、カスタムドメインのトラブルシューティングに関するGitHubのドキュメントを参照してください。

Read the Docs

Read the Docsは無料のドキュメントホスティングを提供しています。Gitバージョン管理システムを使用してドキュメントをインポートできます。Read the DocsはMkDocsをすぐに使用できます。リポジトリ内のファイルを適切に配置し、アカウントを作成して公開ホストされているリポジトリを指定するには、サイトの手順に従ってください。正しく設定されていれば、公開リポジトリにコミットをプッシュするたびに、ドキュメントが更新されます。

その他のプロバイダー

静的ファイルを配信できるホスティングプロバイダーであれば、MkDocsで生成されたドキュメントを配信するために使用できます。すべてのホスティングプロバイダーへのドキュメントのアップロード方法を文書化することは不可能ですが、次のガイドラインは一般的な支援を提供します。

サイトを構築する（mkdocs buildコマンドを使用する）と、すべてのファイルがmkdocs.yaml設定ファイルのsite_dir設定オプション（デフォルトは"site"）に割り当てられたディレクトリに書き込まれます。一般的に、そのディレクトリのコンテンツをホスティングプロバイダーのサーバーのルートディレクトリにコピーする必要があります。ホスティングプロバイダーの設定によっては、グラフィカルまたはコマンドラインのftp、ssh、またはscpクライアントを使用してファイルを転送する必要がある場合があります。

たとえば、コマンドラインからの典型的なコマンドセットは次のようになります。

mkdocs build
scp -r ./site user@host:/path/to/server/root

もちろん、userをホスティングプロバイダーのユーザー名に、hostを適切なドメイン名に置き換える必要があります。さらに、ホストのファイルシステムの設定に合わせて/path/to/server/rootを調整する必要があります。

詳細については、ホストのドキュメントを参照してください。「ftp」または「サイトのアップロード」を検索することをお勧めします。

ローカルファイル

サーバーでドキュメントをホストする代わりに、ファイルを直接配布することもできます。これにより、file://スキームを使用してブラウザで表示できます。

最新のすべてのブラウザのセキュリティ設定により、一部の機能は同じように動作せず、一部の機能はまったく動作しない可能性があることに注意してください。実際、いくつかの設定は非常に具体的な方法でカスタマイズする必要があります。

• site_url:

  site_urlを空の文字列に設定する必要があります。これにより、MkDocsはfile://スキームで動作するようにサイトを構築します。

  site_url: ""

• use_directory_urls:

  use_directory_urlsをfalseに設定します。それ以外の場合は、ページ間の内部リンクが正しく機能しません。

  use_directory_urls: false

• 検索:

  検索プラグインを無効にするか、file://スキームで動作するように特別に設計されたサードパーティの検索プラグインを使用する必要があります。すべてのプラグインを無効にするには、plugins設定を空のリストに設定します。

  plugins: []

  他のプラグインを有効にしている場合は、searchがリストに含まれていないことを確認してください。

ドキュメントを作成する際には、説明されているように、すべての内部リンクで相対URLを使用することが不可欠です。ドキュメントの各閲覧者は異なるデバイスを使用し、ファイルはそのデバイス上の異なる場所に存在する可能性があります。

ドキュメントがオフラインで閲覧されることを期待している場合は、選択するテーマにも注意する必要があります。多くのテーマは、ライブインターネット接続を必要とするさまざまなサポートファイルにCDNを使用しています。サポートファイルのすべてをテーマに直接含めるテーマを選択する必要があります。

サイトを構築する（mkdocs buildコマンドを使用する）と、すべてのファイルがmkdocs.yaml設定ファイルのsite_dir設定オプション（デフォルトは"site"）に割り当てられたディレクトリに書き込まれます。一般的に、そのディレクトリのコンテンツをコピーして閲覧者に配布するだけで済みます。あるいは、サードパーティのツールを使用してHTMLファイルを他のドキュメント形式に変換することもできます。

404ページ

MkDocsがドキュメントをビルドすると、ビルドディレクトリに404.htmlファイルが含まれます。このファイルは、GitHubにデプロイする場合、カスタムドメインでのみ自動的に使用されます。他のWebサーバーで使用するように構成できますが、この機能は常に使用できるとは限りません。詳細については、使用するサーバーのドキュメントを参照してください。