📌

Rustを勉強する場合、mdBookで本を作りながらやるのがオススメという話

2024/02/22に公開

初めに

mdBook はRust界隈だと極めてよく使われる便利なツールですが、このツールにはPlayground機能があり、ある程度メジャーなライブラリは導入されているので、勉強した内容をmdBookで書きつつ、いつでも動的に動かせる環境を作るのがオススメというお話。

Github Pagesへのデプロイも簡単です。
簡単と言ってもやり方の情報を知っていればという話ですが、以下のブログの記事などを参考にするとすぐできます。

具体的には以下のレポジトリにmdBookをGithub Pagesにデプロイするテンプレートがあるので、試しにそれを利用して上手く動くか試すと良いと思います。

Playgroundで導入されているライブラリに関しては、Playgroundのレポジトリの内容を見れば確認できます。

初めにmdBookのインストールをします。

cargo install mdbook

完了したら、mdBookのプロジェクトの初期化を行います。

mdbook init

.gitignoreを作るか、タイトルはどうするかといった質問がされますが自身の希望に応じて調整します。
質問に応じた後に以下のような構成のプロジェクトが生成されます。

.
├── book
├── book.toml
└── src
    ├── SUMMARY.md
    └── chapter_1.md

構成をみて分かるかもしれませんが、この時点で最低限のmdBookの作成がされています。SUMMARY.mdというファイルが目次を扱うファイルで、chapter_1.mdというのは本のコンテンツです。

具体的には以下のような内容のファイルになっています。

SUMMARY.md

# Summary

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

chapter_1.md

# Chapter 1

この時点で最低限の本はできているのでmdbook serveを起動すると作成された本が表示されます。
mdbookを扱う場合、基本的にこのコマンドを常時実行することになります。

次にやることとしては、目次を追加すること。

例えばSummary.mdを以下のような内容に変更します。

# Summary

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

すると、chapter_2.mdというファイルが自動的に生成されます。どういうことかというと、mdbookではSummary.mdの内容を常時監視しており、例えば目次のリンクが存在しないファイルは自動的に生成処理を行っているということです。

mdBookを利用するうえで重要になることは、Summary.md(目次)構成をどうするかという点があるので、どういった感じの目次にするかはある程度決めておいたほうがいいです。

後は、作成したchapterのmarkdownやSummary.mdを充実化していくことで基本的な本を作ることができます。

基本的な実装パターンとしては、

という感じです。基本的にSummary.mdメインで処理を行う感じになります。

mdBookのカスタマイズを行うにはbook.tomlの調整を行う必要があります。

例えばbook.tomlはデフォルトだと以下のような感じのデータになっています。

[book]
authors = ["anonymous"]
language = "en"
multilingual = false
src = "src"
title = "nani"

例えば本のタイトルを変更したい場合、titleを変更するといった具合に調整していきます。

細かいbook.tomlの仕様はmdBookに記載されているのでそこを参照する事をオススメします。