mdtoc - The markdown ToC generator

Markdownファイルの見出しからGitHub互換のToCを生成して埋め込むCLIツール、mdtocを作成した。Node.js製でmarkedパッケージに依存している。実行すると引数に指定したMarkdownファイルの中に書かれた<!-- #toc -->と<!-- /toc -->の間がToCになる。

Download: mdtoc.js

例えば以下のようにMarkdownファイル、foo.mdに<!-- #toc -->と<!-- /toc -->を書いておき、

Test
====

<!-- #toc -->
<!-- /toc -->

Foo
---

### Foo Foo

### Foo Bar

Bar
---

### Bar Foo

ターミナルからmdtocを実行すると、

$ mdtoc foo.md

以下のようにToCが挿入される。

Test
====

<!-- #toc -->

* [Foo](#foo)
  * [Foo Foo](#foo-foo)
  * [Foo Bar](#foo-bar)
* [Bar](#bar)
  * [Bar Foo](#bar-foo)

<!-- /toc -->

Foo
---

### Foo Foo

### Foo Bar

Bar
---

### Bar Foo

ToCの生成対象は最初の見出し以外のすべて。インデントは二番目の見出しを基準に調節されるようにした。大抵はREADME.mdに対して使われると思うので、引数を省略した場合はREADME.mdに対して実行するようにもなっている。改行コードは元の文書に従うようにしておいた。

互換性はそこそこありそうだが、Redcarpetを使ったCLIツールの方が確実と思われるので、それを探すか暇な時に書き直したい。そのためnpmで公開するつもりは今のところない。

HTML Best PracticesのToCを簡単に更新できるようにするために色々探したけど良い物が見つからなかった。

marked-tocは記号の扱いにGitHubと互換性がなく、大体はうまくいくのだけど、たまにうまくいかない。別の名前で一から作り直してるみたいだが、今度はまったく英数字以外がまったく考慮されないものになっていて期待できない。

doctocはコード・ブロックに書いた<h1>タグなどを拾ってしまってめちゃくちゃなToCが生成された。他、どうでも良さそうなPRリンクや派手すぎる埋め込みコメントなど色々うっとうしかった。

他にもたくさんあった(npmだけで15くらい見つかる)が、#での見出し限定のものであったり、特殊な記法で見出しを書かなくてはならなかったりと、試すまでもなく使いたくならないものばかりだった。

mdtocでは、markedのレンダラーの差し替えを利用して見出しをすべて拾い、Redcarpetのコードにあった削除する文字を削除し、空白をマイナスに置換し、最後にURLエンコードするというだけにした。余計なことをなるべくしないようにしたので、そこそこ互換性があるんじゃないかと思う。

追記

Repository: node-gfmtoc

リポジトリーを作成し、git cloneからのnpm install && npm linkでサクッと利用可能になるようにしておいた。MarkdownというかGitHub flavored Markdown (正確にはHTML pipeline？)に依存するものなのでgfmtocに名前は変えた。npmレジストリーへ公開はしない。