テーマ

既定のレンダラーは、handlebarsテンプレートでMarkdownファイルを表示します。mdBookのバイナリーには、既定のテーマが含まれています。

テーマはすべてカスタマイズできます。プロジェクトのルートで、srcの隣にthemeディレクトリを追加すると、テーマの各ファイルを独自のものへ選択的に置き換えられます。上書きしたいファイルと同じ名前のファイルを作ると、既定のファイルの代わりに使われます。

上書きできるファイルは、次のとおりです。

• index.hbsはhandlebarsテンプレートです。
• head.hbsはHTMLの<head>節に追加されます。
• header.hbsの内容は、本の各ページの先頭に追加されます。
• css/は本のスタイルを指定するCSSファイルを含みます。
  • css/chrome.cssはUI要素向けです。
  • css/general.cssは基本のスタイルです。
  • css/print.cssは印刷出力のスタイルです。
  • css/variables.cssは、ほかのCSSファイルで使う変数を含みます。
• book.jsは、サイドバーの表示・非表示やテーマ変更など、クライアント側の機能を追加するために主に使います。
• highlight.jsは、コードをハイライトするためのJavaScriptです。通常、変更する必要はありません。
• highlight.cssはコードのハイライトに使うテーマです。
• favicon.svgとfavicon.pngは、使うfaviconです。SVG版は新しいブラウザーで使われます。
• fonts/fonts.cssは、読み込むフォントの定義を含みます。独自フォントはfontsディレクトリへ入れられます。

通常、テーマを調整するときに、すべてのファイルを上書きする必要はありません。スタイルシートだけを変えたい場合は、ほかのファイルまで上書きする意味はありません。独自のファイルは組み込みのファイルより優先されるため、新しい修正や機能が追加されても更新されません。

注： ファイルを上書きすると、機能が壊れる可能性があります。そのため、既定のテーマのファイルをひな形に使い、必要な部分だけを追加・変更することを推奨します。mdbook init --themeで、既定のテーマをソースディレクトリへ自動コピーし、上書きしたくないファイルを削除できます。

mdbook init --themeは、上記のすべてのファイルを作成するわけではありません。head.hbsなど、組み込みの対応ファイルがないものもあります。必要なら、そのファイルを作成してください。

組み込みのテーマをすべて置き換える場合は、設定のoutput.html.preferred-dark-themeも必ず指定してください。既定値は、組み込みのnavyテーマです。