レンダラーの設定

レンダラー（「バックエンド」とも呼びます）は、本の出力を生成します。

次のバックエンドが組み込まれています。

html — 本をHTMLへ変換します。book.tomlでほかの[output]テーブルを定義していなければ、既定で有効です。
markdown — プリプロセッサーを実行した後、本をMarkdownとして出力します。プリプロセッサーのデバッグに便利です。

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

新しいバックエンドの作り方は、開発者向けのバックエンドの章を参照してください。

HTMLレンダラーの設定

HTMLレンダラーには、以下に詳しく説明するさまざまな設定があります。book.tomlファイルの[output.html]テーブルに指定してください。

# Example book.toml file with all output options.
[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."

[output.html]
theme = "my-theme"
default-theme = "light"
preferred-dark-theme = "navy"
smart-punctuation = true
definition-lists = true
admonitions = true
mathjax-support = false
additional-css = ["custom.css", "custom2.css"]
additional-js = ["custom.js"]
no-section-label = false
git-repository-url = "https://github.com/rust-lang/mdBook"
git-repository-icon = "fab-github"
edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"
site-url = "/example-book/"
cname = "myproject.rs"
input-404 = "not-found.md"
sidebar-header-nav = true

次の設定が使えます。

theme: mdBookには、既定のテーマと必要なリソースファイルが含まれます。この設定を指定すると、指定したフォルダーにあるファイルで、対応するテーマファイルを上書きします。
default-theme: 「Change Theme」ドロップダウンで、既定として選択する配色です。既定はlightです。
preferred-dark-theme: 既定のダークテーマです。ブラウザーがCSSメディアクエリーprefers-color-schemeでサイトのダーク版を要求すると、このテーマを使います。既定はnavyです。
smart-punctuation: 引用符を曲線の引用符へ、...を…へ、--をenダッシュへ、---をemダッシュへ変換します。句読点の自動変換を参照してください。既定はtrueです。
definition-lists: 定義リストを有効にします。既定はtrueです。
admonitions: 注意書きを有効にします。既定はtrueです。
mathjax-support: MathJax対応を追加します。既定はfalseです。
additional-css: スタイル全体を置き換えずに本の見た目を少し変えたい場合は、スタイルシートの集合を指定できます。既定のスタイルシートの後に読み込まれ、部分的にスタイルを変更できます。
additional-js: 本の現在の動作を削らず、新しい動作を追加したい場合は、JavaScriptファイルの集合を指定できます。既定のファイルとともに読み込まれます。
no-section-label: mdBookは既定では、目次欄に「1.」「2.1」などの節番号を追加します。trueにすると、番号を表示しません。既定はfalseです。
git-repository-url: 本のGitリポジトリのURLです。指定すると、本のメニューバーにアイコン付きのリンクを表示します。
git-repository-icon: Gitリポジトリへのリンクに使うFont Awesomeのアイコンクラスです。既定はfab-githubで、のように表示されます。GitHubを使わない場合は、のように表示されるfas-code-forkも候補になります。文字列の先頭は、regularアイコンならfa-、solidアイコンならfas-、brandアイコンならfab-です。利用できるアイコンは無料のアイコン集合を参照してください。
edit-url-template: 編集URLのテンプレートです。指定すると「Suggest an edit」ボタン（）を表示し、閲覧中のページの編集へ直接移動できます。たとえばGitHubのプロジェクトではhttps://github.com/<owner>/<repo>/edit/<branch>/{path}、Bitbucketではhttps://bitbucket.org/<owner>/<repo>/src/<branch>/{path}?mode=editを指定します。{path}は、リポジトリ内のファイルの完全なパスに置き換えられます。
input-404: ファイルが見つからない場合に使うMarkdownファイルの名前です。出力ファイルは同じ名前で、拡張子がhtmlに置き換わります。既定は404.mdです。
site-url: 本を公開するURLです。サブディレクトリのURLへアクセスしても、404ファイルのナビゲーションリンクやscript/cssの読み込みが正しく動くようにするために必要です。既定は/です。site-urlを設定する場合、アセットには文書を基準とした相対リンクを使ってください。つまり、/で始めないようにします。
cname: 本を公開するDNSのサブドメインまたはapexドメインです。GitHub Pagesの要件に従い、サイトのルートにCNAMEというファイルを作り、この文字列を書き込みます（GitHub Pagesサイトのカスタムドメインを管理するを参照）。
hash-files: 静的アセットのファイル名に、内容から作った暗号学的な「指紋」を含めます。内容を変更するとファイル名も変わります。たとえば、css/chrome.cssはcss/chrome-9b8f428e.cssになる場合があります。章のHTMLファイルの名前は変わりません。静的CSSとJSは、{{ resource "filename" }}ディレクティブで相互に参照できます。既定はtrueです。
sidebar-header-nav: trueなら、現在のページの見出しへのナビゲーションをサイドバーに含めます。既定はtrueです。

`[output.html.print]`

[output.html.print]テーブルでは、印刷出力を制御します。既定では、mdBookは本の右上にアイコン（）を置き、本全体を1ページとして印刷できるようにします。

[output.html.print]
enable = true    # include support for printable output
page-break = true # insert page-break after each chapter

enable: 印刷機能を有効にします。falseなら、印刷に関する機能を一切出力しません。既定はtrueです。
page-break: 章の間に改ページを挿入します。既定はtrueです。

`[output.html.fold]`

[output.html.fold]テーブルでは、ナビゲーションサイドバーの章の一覧を折りたたむ動作を制御します。

[output.html.fold]
enable = false    # whether or not to enable section folding
level = 0         # the depth to start folding

enable: 節の折りたたみを有効にします。無効の場合、すべての折りたたみを開きます。既定はfalseです。
level: 値が大きいほど、開いた状態の領域が多くなります。0の場合は、すべて閉じます。既定は0です。

`[output.html.playground]`

[output.html.playground]テーブルでは、Rustのコード例と、Rust Playgroundとの連携を制御します。

[output.html.playground]
editable = false         # allows editing the source code
copyable = true          # include the copy button for copying code snippets
copy-js = true           # includes the JavaScript for the code editor
line-numbers = false     # displays line numbers for editable code
runnable = true          # displays a run button for rust code

editable: ソースコードの編集を許可します。既定はfalseです。
copyable: コードにコピーボタンを表示します。既定はtrueです。
copy-js: エディターのJavaScriptファイルを出力ディレクトリへコピーします。既定はtrueです。
line-numbers: 編集可能なコードに行番号を表示します。editableとcopy-jsの両方をtrueにする必要があります。既定はfalseです。
runnable: Rustのコードに実行ボタンを表示します。falseにすると、playgroundで実行する機能を全体で無効にします。既定はtrueです。

`[output.html.code]`

[output.html.code]テーブルでは、コードブロックを制御します。

[output.html.code]
# A prefix string per language (one or more chars).
# Any line starting with whitespace+prefix is hidden.
hidelines = { python = "~" }

hidelines: 言語ごとにコード行を非表示にする方法を定義するテーブルです。キーは言語、値は文字列で、この接頭辞で始まるコード行が非表示になります。

`[output.html.search]`

[output.html.search]テーブルでは、組み込みの全文検索を制御します。mdBookはsearch機能を有効にしてコンパイルする必要があります（既定で有効です）。

[output.html.search]
enable = true            # enables the search feature
limit-results = 30       # maximum number of search results
teaser-word-count = 30   # number of words used for a search result teaser
use-boolean-and = true   # multiple search terms must all match
boost-title = 2          # ranking boost factor for matches in headers
boost-hierarchy = 1      # ranking boost factor for matches in page names
boost-paragraph = 1      # ranking boost factor for matches in text
expand = true            # partial words will match longer terms
heading-split-level = 3  # link results to heading levels
copy-js = true           # include Javascript code for search

enable: 検索機能を有効にします。既定はtrueです。
limit-results: 検索結果の最大件数です。既定は30です。
teaser-word-count: 検索結果の短い抜粋に使う単語数です。既定は30です。
use-boolean-and: 複数の検索語を論理的にどう結び付けるかを定めます。trueなら、すべての検索語が各結果に含まれている必要があります。既定はfalseです。
boost-title: 検索語が見出しに含まれる場合、検索結果のスコアへ掛ける増加係数です。既定は2です。
boost-hierarchy: 検索語が階層に含まれる場合、検索結果のスコアへ掛ける増加係数です。階層には、親文書のすべてのタイトルと、すべての親見出しが含まれます。既定は1です。
boost-paragraph: 検索語が本文に含まれる場合、検索結果のスコアへ掛ける増加係数です。既定は1です。
expand: 長い単語にも一致させる場合はtrueにします。たとえば、microの検索でmicrowaveにも一致します。既定はtrueです。
heading-split-level: 検索結果は、結果を含む文書の節へリンクします。文書は、指定したレベル以下の見出しで節に分割されます。既定は3です（### This is a level 3 heading）。
copy-js: 検索実装のJavaScriptファイルを出力ディレクトリへコピーします。既定はtrueです。

`[output.html.search.chapter]`

[output.html.search.chapter]テーブルでは、章やディレクトリごとに検索設定を変えられます。各キーは章のソースファイルまたはディレクトリのパスで、値はそのパスへ適用する設定テーブルです。これらは再帰的にマージされ、より具体的なパスが優先されます。

[output.html.search.chapter]
# Disables search indexing for all chapters in the `appendix` directory.
"appendix" = { enable = false }
# Enables search indexing for just this one appendix chapter.
"appendix/glossary.md" = { enable = true }

enable: 指定した章の検索インデックスへの登録を有効または無効にします。既定はtrueです。全体のoutput.html.search.enable設定は上書きしません。どの検索機能を使う場合も、全体の設定をtrueにする必要があります。章の登録を無効にすると、読者が語句を検索して、見つかるはずの結果が見つからずに混乱する可能性があります。章をインデックスに残すと検索結果の品質に問題が生じる、例外的な場合にだけ使ってください。

`[output.html.redirect]`

[output.html.redirect]テーブルでは、リダイレクトを追加できます。ページを移動、改名、削除した際に、旧URLへのリンクを新しい場所へ誘導するために便利です。

[output.html.redirect]
"/appendices/bibliography.html" = "https://rustc-dev-guide.rust-lang.org/appendix/bibliography.html"
"/other-installation-methods.html" = "../infra/other-installation-methods.html"

# Fragment redirects also work.
"/some-existing-page.html#old-fragment" = "some-existing-page.html#new-fragment"

# Fragment redirects also work for deleted pages.
"/old-page.html" = "new-page.html"
"/old-page.html#old-fragment" = "new-page.html#new-fragment"

このテーブルにはキーと値の組を指定します。キーは、リダイレクト用のファイルを作成する場所を、ビルドディレクトリからの絶対パスで表します（例：/appendices/bibliography.html）。値には、ブラウザーの移動先となる任意の有効なURIを指定できます（例：https://rust-lang.org/、/overview.html、../bibliography.html）。

指定した場所へ自動でリダイレクトするHTMLページが生成されます。

フラグメントのリダイレクトを指定した場合、そのページはJavaScriptを使って正しい場所へ移動させる必要があります。節の見出しを改名、移動したときに便利です。フラグメントのリダイレクトは、既存のページと削除したページで使えます。

Markdownレンダラー

Markdownレンダラーは、プリプロセッサーを実行した後、その結果のMarkdownを出力します。主にプリプロセッサーのデバッグに便利で、特にmdbook testと組み合わせると、mdbookがrustdocへ渡すMarkdownを確認できます。

Markdownレンダラーはmdbookに含まれますが、既定では無効です。次の空のテーブルをbook.tomlへ追加すると、有効になります。

[output.markdown]

現時点でMarkdownレンダラーに設定項目はありません。有効か無効かだけを指定できます。

Markdownレンダラーの前に実行するプリプロセッサーの指定方法は、プリプロセッサーの文書を参照してください。