TypeDocにmermaid.jsのダイアグラムを埋め込める拡張機能作った

仕事でTypeScriptを書いていていて、「TypeScriptのコメントにフローチャート図ぶち込みたいな」という衝動に駆られて、TypeDocにmermaid.jsのグラフ埋め込めるようにするプラグインを作りました。

背景

TypeDoc とは

TypeScriptのドキュメント・コメントをいい感じでドキュメント整った状態のHTMLで生成してくれるツールです。

typedoc.org

公式のQuick Startより

# npmでグローバルにインストール
npm install --global typedoc

# typedoc を実行する /src下を
typedoc --out docs /src

更に詳しく見たい方は、下記の記事が参考になります。

mermaid.js とは

JavaScriptでフローチャート、シーケンス、ガントなどの図を作れるライブラリです。

mermaidjs.github.io

独自のグラフ記述言語とブラウザ上でのレンダリングエンジンがセットになっているツールですね。

近しいツールに、PlantUML などがありますが、こちらはブラウザだけで描画することができません。 (サーバーで出力したものを埋め込むことはできます。)

成果物

NPM

npm: typedoc-plugin-mermaid

GitHub: kamiazya/typedoc-plugin-mermaid

こんな感じで書くと、

/**
 * Hoge is sample class for example of `typedoc-plugin-mermaid`.
 *
 * @mermaid Make TypeDoc easy to use with mermaid.js
 * graph TB
 *   mermaid.js --> TypeDoc;
 */
export class Hoge { }

こんな感じで表示してくれるようにしました。

Example

動いているのが見たい方は出力されたTypeDocのデモを用意したので、そちらを御覧ください。

製作中にハマったとこと

TypeDocにプラグインとして判断される条件がよくわからない

PluginHostのソースを読むと、typedocpluginとキーワードが設定されていました。

TypeDoc内のイベントがよくわからない

Converterのソース などをみると、EventFactoryというコメントの下にイベント発火のタイミングなどが書いてあります。

流石に全部読んでられないので、TypeDocのプラグインがフックしているイベントをマネして作りました。

まとめ

つかってね。