先日のNode学園祭で standard-readme という規格が紹介されていました。
これを眺めていたら、ミニマムでも目次(ToC)は必要ですよということでした。たしかにToCは読むほうからすると便利なんですよね。
一方でToCのメンテナンスは人間のやる仕事じゃないですよね。機械的に生成してメンテフリーにしたい。
ということで、vscodeのMarkdown ToCのいい感じの拡張を探したところ、AlanWalk/markdown-toc というのがよさそうだったので使ってみました。
この拡張をインストールしてREADME.mdに以下のように書いておくと:
## Table of Contents <!-- TOC depthFrom:2 --> <!-- /TOC -->
以降、保存するたびにToCが自動的に生成されてこのタグの中に埋められます。これは保存するたびに最新の状態に更新され続けるので、画面分割してToCを眺めながらセクションの構成を考えたりできます。
私の直近のプロジェクトだと、OrmaのREADME.md が1000行近くあってメンテするのがつらかったのですが、これのおかげでだいぶ楽になりました。おそらく読む方も楽でしょう。