Rust製静的ジェネレータ mdBookを試す
そろそろ今後のために家族にいろんな引継事項の残そうかと思います。 当初はAsciidocで書いていましたが、TreeSitterが構文をサポートしておらず 嫌気が差してしまいました。WeblogでもreStructured TextからMarkdownに切り替えたので シンプルなMarkdownで記述できるツールを探しました。
そこで、Markdownファイルからオンラインブックを作成するRust製ツール mdBook を試してみました。
mdBookとは
mdBook とはMarkdownファイルをHTMLに変換しオンラインブックを作成できるRust製ツールです。
選択した理由は、次の通りです。
- Rust製でRubyやPython製の同類のツールと比べると非常に高速である。
- ブログなどを想定した静的ジェネレーターに比べると機能が絞られている分、 デザインや構造に気を取られることなく執筆に集中できる。
- 記事はメタ情報などもないシンプルなMarkdownファイルなので他のPreviewツールも 活用できる。
想定しているのは、家族へのHand Over Letterなのでこれくらいでちょうどよいでしょう。
mdBookのインストール
Rustの環境があれば以下のステップでインストールできます。
$ cargo install mdbook $ cargo install mdbook-toc $ cargo install mdbook-mermaid
本体のみで利用できますが、目次生成を行う mdbook-tocと、
Mermaidを利用できるようになる mdbook-mermaidも合わせてインストールしました。
オンラインブックの作成
初期設定
まずはinitコマンドで初期化した後に、mdbook-mermaid install でMermaidを使えるようにします。
$ mdbook init my-first-book Do you want a .gitignore to be created? (y/n) y What title would you like to give the book? My First Book 2024-02-07 08:32:28 [INFO] (mdbook::book::init): Creating a new book with stub content All done, no errors... $ mdbook-mermaid install my-first-book [2024-02-06T23:34:09Z INFO mdbook_mermaid] Reading configuration file my-first-book/book.toml [2024-02-06T23:34:09Z INFO mdbook_mermaid] Adding preprocessor configuration [2024-02-06T23:34:09Z INFO mdbook_mermaid] Adding additional files to configuration [2024-02-06T23:34:09Z INFO mdbook_mermaid] Saving changed configuration to my-first-book/book.toml [2024-02-06T23:34:09Z INFO mdbook_mermaid] Writing additional files to project directory at my-first-book/ [2024-02-06T23:34:09Z INFO mdbook_mermaid] Files & configuration for mdbook-mermaid are installed. You can start using it in your book. [2024-02-06T23:34:09Z INFO mdbook_mermaid] Add a code block like: ```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ```
以上で、my-first-bookフォルダ以下にmdBookに必要なファイルが展開されています。
次に目次生成ができるようbook.tomlにプリプロセッサーとしてmdbook-tocを追加します。
[book] authors = ["Mark Twain"] language = "ja" multilingual = false src = "src" title = "My First Book" [preprocessor] [preprocessor.mermaid] command = "mdbook-mermaid" [preprocessor.toc] command = "mdbook-toc" renderer = ["html"] [output] [output.html] additional-js = ["mermaid.min.js", "mermaid-init.js"]
これで環境は構築できました。
文書構成の作成
プロジェクトフォルダ直下に SUMMARY.mdというファイルが作成されているはずです。
このファイルはオンラインブックの左側のペインに表示される文書全体の目次のソースとなります。
SUMMARY.mdに目次を作っていきます。
この目次の1ラインが各頁へのリンクになります。リンクはHTMLでなくソースである MarkdownファイルでOkです。後でmdBookが置換してくれます。リンク先のソースがなくても Okです。どんどん項目を作っていきましょう。
以下はSUMMERY.mdのサンプルです。
# Summary [Introduction](README.md) # User Guide - [Installation](guide/installation.md) - [Reading Books](guide/reading.md) - [Creating a Book](guide/creating.md) # Reference Guide - [Command Line Tool](cli/README.md) - [init](cli/init.md) - [build](cli/build.md) - [watch](cli/watch.md) - [serve](cli/serve.md) - [test](cli/test.md) - [clean](cli/clean.md) - [completions](cli/completions.md) - [Format](format/README.md) - [SUMMARY.md](format/summary.md) - [Draft chapter]() - [Configuration](format/configuration/README.md) - [General](format/configuration/general.md) - [Preprocessors](format/configuration/preprocessors.md) - [Renderers](format/configuration/renderers.md) - [Environment Variables](format/configuration/environment-variables.md) - [Theme](format/theme/README.md) - [index.hbs](format/theme/index-hbs.md) - [Syntax highlighting](format/theme/syntax-highlighting.md) - [Editor](format/theme/editor.md) - [MathJax Support](format/mathjax.md) - [mdBook-specific features](format/mdbook.md) - [Markdown](format/markdown.md) - [Continuous Integration](continuous-integration.md) - [For Developers](for_developers/README.md) - [Preprocessors](for_developers/preprocessors.md) - [Alternative Backends](for_developers/backends.md) --- [Contributors](misc/contributors.md)
この状態でmdbookコマンドを起動すると、リンク先に指定した
各頁のMarkdown ファイルが自動生成されています。
オンラインブックの生成
各頁をMarkdownファイルで作成したら、次のコマンドでHTMLに変換します。
--openオプションを付けると生成後にデフォルトブラウザを起動します。
$ cd my-first-book $ mdbook build --open
また次のコマンドによりプロジェクトフォルダを監視し、ソースファイルが 変更される後とにHTMLを再生成して疑似的にリアルタイムのプレビューが可能 となります。
GitLab CI/CD でmdBookを GitLab Pagesに公開する
.gitlab-ci.ymlに以下の設定を行う。
image: rust:latest stages: - build - deploy build_book: stage: build before_script: - cargo install mdbook - cargo install mdbook-toc - cargo install mdbook-mermaid script: - mdbook build artifacts: paths: - book pages: stage: deploy dependencies: - build_book script: - mv book public artifacts: paths: - public only: - main
生成自体はRustなので超高速ですが、mdBookの環境を作る部分が時間がかかるようです。