Islands in the byte stream

Technical notes by a software engineer

vscodeの AlanWalk/markdown-toc extensionで目次の自動生成すると捗るぞ

先日のNode学園祭で standard-readme という規格が紹介されていました。

これを眺めていたら、ミニマムでも目次(ToC)は必要ですよということでした。たしかにToCは読むほうからすると便利なんですよね。

一方でToCのメンテナンスは人間のやる仕事じゃないですよね。機械的に生成してメンテフリーにしたい。

ということで、vscodeのMarkdown ToCのいい感じの拡張を探したところ、AlanWalk/markdown-toc というのがよさそうだったので使ってみました。

marketplace.visualstudio.com

この拡張をインストールしてREADME.mdに以下のように書いておくと:

## Table of Contents

<!-- TOC depthFrom:2 -->

<!-- /TOC -->

以降、保存するたびにToCが自動的に生成されてこのタグの中に埋められます。これは保存するたびに最新の状態に更新され続けるので、画面分割してToCを眺めながらセクションの構成を考えたりできます。

私の直近のプロジェクトだと、OrmaのREADME.md が1000行近くあってメンテするのがつらかったのですが、これのおかげでだいぶ楽になりました。おそらく読む方も楽でしょう。