Libx mdBook ドキュメント

    継続的インテグレーションで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をインストールする必要がありません。
    • 特定のURLを指定するため、新しい版を取得するには、スクリプトを手で更新する必要があります。特定の版へ固定したい場合は、利点にもなります。一方、新しい版が公開されたら、自動で取得したいユーザーもいます。
    • GitHub CDNが利用できることに依存します。

    ソースからビルドする

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

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

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

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

    • --no-default-features — CIでは通常不要な、mdbook serve用のHTTPサーバーなどの機能を無効にします。ビルド時間を大幅に短くできます。
    • --features search — 既定の機能を無効にした場合、組み込みの検索など、必要な機能を手で有効にしてください。
    • --vers "^0.5.4" — 0.5系列の最新版をインストールします。ただし、0.6.0以降のような、SemVer上の互換性がない版は、ビルドを壊す可能性があるためインストールしません。古いmdBookがすでにインストールされていれば、Cargoが自動で更新します。特定の版へ固定したい場合は、^を=へ置き換えてください。
    • --locked — mdBookのリリース時に使われた依存関係を使います。--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へ指定できます。