mdBook を使ってみる

  • mdBook は、Markdown 形式で「本」が書けるツール
    • 少し技術的な言い方をすると、入力した Markdown 形式のファイルについて、「本」としての構造をもった HTML テンプレートをもとに、ウェッブサイトの構築に必要なファイル群を生成する静的サイトジェネレーター
  • よく似たツールに GitBook や MkDocs などがある
  • mdBook は、テンプレートを編集することでデザインを手軽に編集できたり、プリプロセッサを使って機能を手軽に拡張できたりするところが面白い

インストール

brew install mdbook

準備

  • mdbook initコマンドを実行して、質問（本のタイトルなど）に答えると、作業用ディレクトリ（ここではmybook）ができる
mdbook init mybook
Do you want a .gitignore to be created? (y/n)
y

What title would you like to give the book? 
My Book
  • 作業用のディレクトリに移動する
cd mybook
  • 作業ディレクトリ内にあるbook.tomlというファイルで、本の概要を設定する
[book]
title = "My Book"
authors = ["yamnor"]
language = "ja"
src = "src"

書く

  • 作業ディレクトリ内にあるSUMMARY.mdに、各章の Markdown ファイルを指定する
# Summary

- [第１章](./chapter_1.md)
  • 各章の Markdown ファイルを編集するすることで、本を書く
# 第１章

これはテストです。
  • mdbook serveコマンドを実行すると、作業用のディレクトリにある Markdown 形式のファイルが html 形式に変換される
  • --openオプションを付けると、デフォルトの Web ブラウザが立ち上がって、編集した内容をプレビューできる
mdbook serve --open

カスタマイズ

  • 数式を書きたいときには、book.tomlファイル内で MathJaxを有効にする
  • デザインを少し変えたいときには、cssファイルを指定する
[output.html]
mathjax-support = true
additional-css = ["custom.css"]

テンプレートファイル

  • テーマファイルを編集することで、デザインを大幅に変えることもできる
  • mdbook init --themeをすると、設定用のファイルを含むthemeディレクトリができる
    • ファイルの内容は ここ を参照
  • テンプレートファイルの本体はtheme/index.hbs
    • Handlebars というテンプレート用の言語で書かれている
    • Hugo などの静的サイトジェネレータを使ったことがあれば、なんとなく内容が分かると思う

プリプロセッサ & 代替バックエンド

  • プリプロセッサ はまだ試していないけれど、Rust 以外の言語、たとえば、Python でも書けるらしい
  • ここ に、プリプロセッサや代替バックエンドで実装された mdBook のプラグインがある
mdBook
Posted :