--- title: "mdBook：継続的インテグレーション" documentId: "mdbook:guide/src/continuous-integration.md" order: 27 licenseSource: "mdbook-guide" documentContext: [{"kind": "source", "html": "

mdBook 0.5.4公式文書の非公式日本語訳。文書とその翻訳はMPL-2.0。固定した原典 · 編集可能な日本語文書 · 固定原資料一式。 · 編集可能な英日原稿とビルド資料.

"}, {"kind": "editorial", "html": "

Libxでは全文・コード・図・原目次を静的に提供します。原著の編集・実行機能は原典を参照してください。コードの非表示行は全表示し、数式は原TeX表記を保持します。章の操作説明はmdBookが生成した元の本を対象とします。

"}] prev: {"text": "Markdown", "link": "/v0-5-4/ja/01-guide/20-format-markdown"} next: {"text": "開発者向け", "link": "/v0-5-4/ja/01-guide/11-for_developers-index"} ---

継続的インテグレーションでmdbookを実行する

GitHub ActionsやGitLab CI/CDなど、さまざまなサービスを使って、本を自動でテスト・デプロイできます。

以下では、mdBookを実行するためのサービス設定について、一般的な指針を示します。具体的な手順は、WikiのAutomated Deploymentページを参照してください。

mdBookをインストールする

mdBookのインストールには、いくつかの方法があります。必要なことや好みに応じて選んでください。

ビルド済みバイナリー

おそらく最も簡単なのは、GitHub Releasesページのビルド済みバイナリーを使う方法です。広く使われているCLIツールcurlで実行ファイルをダウンロードする、次のような方法があります。

mkdir bin
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.5.4/mdbook-v0.5.4-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
bin/mdbook build

この方法について、考慮する点を示します。

ソースからビルドする

ソースからビルドするには、Rustをインストールする必要があります。Rustが事前にインストールされているサービスもありますが、そうでなければ、インストールする工程を追加してください。

Rustをインストールすると、cargo installでmdBookをビルド・インストールできます。mdBookの互換性を壊さない最新バージョンを取得するには、SemVerのバージョン指定を推奨します。例を示します。

cargo install mdbook --no-default-features --features search --vers "^0.5.4" --locked

推奨するいくつかのオプションを含んでいます。

mdBookのビルドには少し時間がかかる場合があるため、キャッシュの方法を調べるとよいでしょう。

テストを実行する

変更をpushしたりプルリクエストを作成したりするたびに、mdbook testでテストを実行するとよいでしょう。本に含まれるRustのコード例を検証できます。

Rustをインストールする必要があります。Rustが事前にインストールされているサービスもありますが、そうでなければ、インストールする工程を追加してください。

適切なバージョンのRustがインストールされていることを確認した後は、本のディレクトリでmdbook testを実行するだけです。

リンク切れを調べるmdbook-linkcheck2など、ほかの種類のテストも検討するとよいでしょう。独自のスタイル検査、スペル検査、そのほかのテストも、CIで実行すると便利です。

デプロイする

本を自動でデプロイしたい場合もあるでしょう。変更をpushするたびに行う方法もあれば、特定のリリースにタグを付けたときだけ行う方法もあります。

利用するウェブサービスへ変更を送る、具体的な方法も理解する必要があります。たとえば、GitHub Pagesでは、特定のGitブランチへ出力をコミットするだけです。ほかのサービスでは、SSHなどでリモートサーバーへ接続する必要がある場合もあります。

基本的には、mdbook buildを実行して出力を生成し、bookディレクトリにあるファイルを適切な場所へ転送します。

その後、ウェブサービスのキャッシュを無効にする必要があるか、検討するとよいでしょう。

さまざまなサービスの例は、WikiのAutomated Deploymentページを参照してください。

404への対応

mdBookは、リンク切れに使う404ページを自動で生成します。既定では、本のルートに404.htmlというファイルを出力します。GitHub Pagesなどのサービスでは、リンク切れにこのページを自動で使います。ほかのサービスでも、ウェブサーバーがこのページを使うよう設定するとよいでしょう。読者が本へ戻るためのナビゲーションを提供できます。

本をドメインのルート以外へデプロイする場合、404ページが正しく動くようにoutput.html.site-urlを設定してください。CSSなどの静的ファイルを正しく読み込むには、本の公開場所を知る必要があります。たとえば、このガイドはhttps://rust-lang.github.io/mdBook/へ公開され、site-urlを次のように設定しています。

# book.toml
[output.html]
site-url = "/mdBook/"

本にsrc/404.mdというファイルを作ると、404ページの見た目を変更できます。別のファイル名を使う場合は、output.html.input-404へ指定できます。