プリプロセッサーの設定

プリプロセッサーは、レンダラーへ渡す前のMarkdownソースを変更できる拡張です。

次のプリプロセッサーは組み込まれており、既定で使われます。

• links：章にあるhandlebarsヘルパー{{ #playground }}、{{ #include }}、{{ #rustdoc_include }}を展開し、ファイルの内容を取り込みます。詳しくはファイルを取り込むを参照してください。
• index：README.mdという名前の章ファイルをすべてindex.mdへ変換します。つまり、すべてのREADME.mdは、生成した本ではインデックスファイルindex.htmlとして出力されます。

組み込みのプリプロセッサーは、build.use-default-preprocessors設定で無効にできます。

コミュニティは、いくつかのプリプロセッサーを開発しています。利用できるプリプロセッサーの一覧は、WikiのThird Party Pluginsページを参照してください。

新しいプリプロセッサーの作り方は、開発者向けのプリプロセッサーの章を参照してください。

独自プリプロセッサーの設定

book.tomlに、プリプロセッサー名を付けたpreprocessorテーブルを追加すると、プリプロセッサーを使えます。たとえば、mdbook-exampleというプリプロセッサーなら、次のように指定します。

[preprocessor.example]

このテーブルによって、mdBookはmdbook-exampleプリプロセッサーを実行します。

このテーブルには、プリプロセッサー固有のキーと値の組も追加できます。たとえば、例のプリプロセッサーに追加の設定が必要なら、次のように指定します。

[preprocessor.example]
some-extra-feature = true

プリプロセッサーをレンダラーに結び付ける

プリプロセッサーとレンダラーを結び付けると、そのレンダラーに対してプリプロセッサーを実行することを明示的に指定できます。

[preprocessor.example]
renderers = ["html"]  # example preprocessor only runs with the HTML renderer

独自のコマンドを指定する

既定では、book.tomlへ[preprocessor.foo]テーブルを追加すると、mdbookはmdbook-foo実行ファイルの呼び出しを試みます。別のプログラム名を使ったり、コマンドライン引数を渡したりする場合は、commandフィールドを追加して、この動作を上書きできます。

[preprocessor.random]
command = "python random.py"

任意のプリプロセッサー

有効にしたプリプロセッサーがインストールされていない場合、既定ではエラーになります。プリプロセッサーを任意と指定すると、この動作を変えられます。

[preprocessor.example]
optional = true

これによって、エラーが警告になります。

順序を指定する

プリプロセッサーの実行順序は、beforeとafterフィールドで指定できます。たとえば、linenosプリプロセッサーで、{{#include}}によって取り込まれた行を処理したい場合は、組み込みのlinksプリプロセッサーの後に実行する必要があります。beforeかafterフィールドで、この順序を指定できます。

[preprocessor.linenos]
after = [ "links" ]

または、次のように指定します。

[preprocessor.links]
before = [ "linenos" ]

冗長にはなりますが、上の両方を同じ設定ファイルに指定することもできます。

beforeとafterによる優先度が同じプリプロセッサーは、名前で並べ替えます。無限ループは検出され、エラーになります。