TypeScript の API ドキュメントを Markdown で出力するツールを作った

TypeScript で API ドキュメントを Markdown で出力できるものを作りました。
https://www.npmjs.com/package/typedoc-markdown-theme

使い方

TypeDoc という、 TypeScript のコードから API ドキュメントを HTML で生成してくれるツールがあります。

• http://typedoc.io/

こちらのパッケージ、 theme というのを設定することで、ドキュメントの見た目を変えることができます（未設定の場合はデフォルトの theme が使われる）。
本来は DOM 構造を変えたり CSS をいじったりするような用途が想定されているであろう機能ですが、大胆に Markdown にしてみました。
ということで、 使い方は以下のような感じです。

$ npm install typedoc typedoc-markdown-theme --save-dev
$ node_modules/.bin/typedoc --theme node_modules/typedoc-markdown-theme/bin --out doc path/to/ts/dir

より詳細なオプションの指定方法等は TypeDoc のドキュメントを参照してください。

ちなみに、 TypeScript 1.7 には未対応です。 (TypeDoc 自体がこの記事執筆時点で未対応)

出力例

https://github.com/kimamula/typedoc-markdown-theme/tree/master/examples の中をご覧いただければ。

以下余談

実装について

オプションとして指定できるようになっているくらいだから、 TypeDoc 本体とは疎結合に作れるかなと思っていたのですが、割と密結合になっていて、バージョンアップ対応とかが不安です。
実は TypeDoc は TypeScript 1.7 対応がまだなのですが、ここ 24 時間くらいで対応しようとしている commit があるので、そろそろバージョンアップしそう。

また、 Handlebars をテンプレートエンジンとして使っているのですが、 HTML なら grep すればどこに何が書いてあるかまあ探せると思うのですけれど、 Markdown だと相当厳しい感じがします。
コメントしっかり書いておけばよかったかも。

API ドキュメントについて

API ドキュメントって未だに HTML で出力されるものが主流なので、実はそんなに需要ないのかな？なんて不安になっています。
GitHub 上とかでドキュメント公開したくなったら、 Markdown 欲しくなりますよね？
GitHub Pages だと、それ用に branch 切るので、最新の状態と同期するのめんどくさくならないですかね。
何か僕の知らないすごくいいやり方があるのかな。