mdBookのカスタマイズ

mdBookのカスタマイズ方法を紹介します。

設定ファイル

mdBookの設定ファイルbook.tomlの内容を変更することで、mdBookの動作をカスタマイズできます。 設定項目については、mdBookのドキュメントを参照してください。

mdbook-ja-templateのbook.tomlの内容は以下のとおりです。

[book]
authors = ["gifnksm <makoto.nksm+github@gmail.com>"]
title = "mdbook-ja-templateユーザーズガイド"
language = "ja"
src = "src"
multilingual = false

[output.html]
mathjax-support = true
additional-js = ["js/mermaid.min.js", "js/mermaid-init.js"]
git-repository-url = "https://github.com/gifnksm/mdbook-ja-template"
edit-url-template = "https://github.com/gifnksm/mdbook-ja-template/edit/main/{path}"
site-url = "/mdbook-ja-template/"

[output.linkcheck]

[preprocessor]

[preprocessor.mermaid]
command = "mdbook-mermaid"

プラグイン

mdBookはmdbook-*という形式のコマンドをプラグインとして組み込み、出力内容の変更などを行うことができます。 mdBookで利用可能なプラグインの一覧はThird party pluginsを参照してください。

mdbook-ja-templateでは以下のプラグインが組み込まれています。

• mdbook-mermaid: mdBookにmermaid.jsサポートを追加するプラグイン
• mdbook-linkcheck: ドキュメント中に無効なリンクが含まれていないかチェックするプラグイン

プラグインの追加

新たにプラグインを追加したい場合は、docker/Dockerfileを編集して、 コンテナ内にプラグインをインストールしてください。 プラグインのインストール方法やbook.tomlの設定方法はプラグインのドキュメントを参照してください。 多くのプラグインはcargo install でインストールできます。

以下に、mdbook-tocプラグインをインストールする場合の例を示します。

まず、docker/Dockerfileを以下のように編集してください。

FROM ghcr.io/gifnksm/mdbook-ja:latest

# ↓追加
RUN cargo install mdbook-toc --version 0.9.0 --root /usr/local/bin

次に、book.tomlに以下を追加してください。

[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]

編集後make buildなどを実行すると、プラグインが有効になった状態でウェブサイトが生成されます。