便利なmdbookの私の使い方 - doctocを添えて -
3 min read
こんにちは、無能です。
仕事でもドキュメント作成にRust公式で使われているMarkdown形式で書けるmdbookの使い心地がとても良いので私の場合の使い方を紹介します。
インストール
cargo installでインストール
cargo install mdbook
あとから使う目次生成にdoctocをインストールします。
sudo npm -g install doctoc
ぶっちゃけ他にMarkdownで目次自動生成できるコマンド他にもありそうですがリサーチ不足です。
初期設定
mdbook initを実行するだけ
~/git/lets-mdbook$ mdbook init
Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book?
test
2024-11-23 22:19:57 [INFO] (mdbook::book::init): Creating a new book with stub content
All done, no errors...](alleycat:[haturatu]:~/git/lets-mdbook$ mdbook init
Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book?
test
2024-11-23 22:19:57 [INFO] (mdbook::book::init): Creating a new book with stub content
All done, no errors...
alleycat:[haturatu]:~/git/lets-mdbook$ ls
book book.toml src
ここでsrcに記事となる.mdファイルをぶっこんで、ビルドするとbookディレクトリにデフォルトでは出力されます。
alleycat:[haturatu]:~/git/lets-mdbook/src$ ls
SUMMARY.md chapter_1.md](alleycat:[haturatu]:~/git/lets-mdbook$ cat src/
SUMMARY.md chapter_1.md
alleycat:[haturatu]:~/git/lets-mdbook$ cat src/SUMMARY.md
# Summary
- [Chapter 1](./chapter_1.md)
このsrc/SUMMARY.mdにはサイドバーに表示されるような目次を作れます。
ビルド作業をシェルスクリプトで自動化し更新履歴も作る
srcディレクトリに更新するたびにdoctocコマンドを実行してmdbook buildして・・・みたいなアホみたいなことしているのがアホみてえだな・・・。と我ながら思って耐えきれなくなったのでvim開きながらでも一連作業を実行出来るようにシェルスクリプトを作成。
#!/bin/bash
pwd | grep "src$" || cd src
doctoc .
sed -i "3d" ./*.md
sed -i "/](\#/d" ./SUMMARY.md
sed -i "8a`date`" ./update.md
cd ..
mdbook build
git add .
git commit -m "wip"
git push
これはpwd | grep "src$" || cd srcでpwd結果にsrcが含まれていれば何もしない。なかったらcd srcに移動する。
なんでこんなことしてるかっていうと、src/*.mdを編集しながら:!../build.shでこのスクリプトを実行するとsrcディレクトリ内でcdしてしまうのでちょっと気持ちが悪いからこうしてる。まあしなくても動作上なんの問題も無いんだけど・・・。 なお、git remote-urlを設定し一度git pushしている前提だったり、update.mdはこんな感じになっている。
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Update Log](#update-log)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Update Log
2024年 11月 23日 土曜日 22:39:24 JST
sed -i "8adate" ./update.mdで8行目にこのスクリプトが走ったときのログとして残る。
ぶっちゃけちゃんとやるならgit commitの戻り値からコミットあったときにだけ更新履歴に残すように判定したときだけとかした方が明らかに親切なんだが即席スクリプトだったのでご了承いただきたい・・・。
Github Actions使えばいいんちゃうの？
このビルド作業はActionsでも実際使える。
ただし、usesで他のyml資産を使えない環境だとどうだろう？
もしGithub Actionsのみで使うなら良いかもしれないが、GitLabをGitサーバーとして使っている場合github.comの資産を使おうとするとちょっとややこしくなってくるみたいなので(まあそりゃそうである・・・。)今回のようにした。
実際Githubのエンタープライズ版は結構ここらへん結構厄介なんだ・・・。
Enterprise でのアクションの使用について
という訳であんま頼りにしちゃらんないなあ・・・。と思ったのでもっと頼りにならないような自分がシェルスクリプトに記述したのであった・・・。