Markdown で簡単にオンラインドキュメントを生成できる mdBook の使い方

mdBook とは

Markdown 形式できれいなドキュメントを作成するためのツールです。

チャプター別に執筆した Markdown ファイルから、以下のようなオンラインドキュメントを簡単に作成することができます。

mdBook でビルドすると book ディレクトリに HTML や CSS、JS ファイルが生成されるので、ディレクトリごと Github Pages などに配備すればオンラインでドキュメントを公開することもできます。

同様のツールに gitbook-cli という Node ベースのものがありますが、mdBook は Rust 製で、なにしろ速いのがメリットです。

mdBook の導入

Rust(cargo) が入っていれば以下のようにすれば導入は完了です。

$ cargo install mdbook

~/.cargo/bin の中に mdbook がインストールされます。

Rust をインストールしていない場合は、rustup というRust のツールチェーン管理ツール経由でインストールできます。

以下のコマンドを実行すればインストールは完了です(オプションの選択が求められますがデフォルトのままで問題ありません)。

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Windows の場合は rustup-init.exe をダウンロードして実行します。

インストールが終われば、先のコマンドで mdBook をインストールできます。

mdBook の始め方

適当なディレクトリで以下を実行すれば、ひな形ができあがります。

% mdbook init

Do you want a .gitignore to be created? (y/n)

What title would you like to give the book?
mdBook Sample
20XX-XX-XX 00:00:00 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

book.toml というファイルでドキュメントの設定を定義します。

デフォルトでは以下のようになっています。

[book]
authors = []
language = "en"
multilingual = false
src = "src"

language には、生成された html のlang 属性を指定するものなので ja に変えておくのも良いかもしれませんが、多言語対応しないなら消してしまって大丈夫です。

変更しなくても良いですし、以下のような簡単な定義でも十分です。

[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
src = "src"

SUMMARY.md は以下のようになっており、チャプター別の md を参照しています。

# Summary

- [Chapter 1](./chapter_1.md)

chapter_1.md ファイルは以下のような空のコンテンツとなっています。

# Chapter 1

ドキュメントは、コンテンツを揃えて、各チャプターをSUMMARY.md にリンクとして追加していけばよいだけです。

mdBook でビルドする

mdbook build とすると book ディレクトリの中に html ファイルなどが生成されます。

--open オプションを付ければ自動でブラウザで開きます。

$ mdbook build --open

初期状態では以下のようになります。

ビルド後には、book ディレクトリに以下のようなファイルが生成されます。

生成されたものを一式 Web サーバに配備すればオンライン公開できます。

mdBook のコマンド

以下のようなコマンドがあります。

コマンド	説明
mdbook init	プロジェクトのひな形を生成
mdbook build --open	ビルドしてブラウザで開く
mdbook watch --open	ファイルの変更を監視して自動ビルド
mdbook serve -p 9090 --open	ローカルサーバをポート9090で起動してドキュメントを表示(デフォルトで自動ビルド)
mdbook clean	ビルドしたファイルをクリーン

mdBook での作業

たいていの場合は、以下のようにサーバを起動しておき、ドキュメントを作成していきます(ポートを指定しない場合はデフォルトの 3000 を利用)(-o は --open と同義)。

mdbook serve -o

編集して保存するとブラウザで自動的にリロードされるため、執筆しながら出力結果をシームレスに確認できます。

また、新しいチャプターが必要になれば SUMMARY.md に追加することで自動的にファイルが作成されるので、作成されたファイルに内容を追記していくことで、ストレスのないドキュメント作成ができます。

mdBook で Rust コードを実行

mdBook では、以下のような md を書くと、

mdBook では Rust コードが実行できます。

 ```rust
fn main() {
    let x = 5;
    let y = 6;

    println!("{}", x + y);
}
 ```

<br/>

`#` でコメント化することができます。

 ```rust
# fn main() {
let x = 5;
let y = 6;

println!("{}", x + y);
# }
 ```

コードブロックの矢印ボタンを押すと、ブラウザでコードが実行できます。

Rust 関連のドキュメントを書く際に重宝します。

プログラミングRust

プログラミング言語Rust 公式ガイド