読みやすいAPIドキュメントはどういった形でしょうか。様々なソフトウェアが出ていますが、抜群にこれ!といったものにはまだ出会っていません。多機能なものもあれば、シンプルなもの、各言語向けにそれぞれドキュメントフォーマットも異なるのが面倒ですらあります。 しかしまずドキュメントの入力記法を統一しておけば、後から見た目の変更をするのもさほど難しくはないはずです。そこでMarkdownを利用する上で使ってみたいのがdittoです。

dittoの使い方

dittoの例です。左側にメニュー、右側にコンテンツが表示されます。

例えばAPIドキュメントはこのように展開されます。

左側から機能を選ぶと右側のコンテンツに反映されます。

dittoはGitHub Pageで使うことも想定して作られています。そのためオープンソースのGitHubページとして使うと便利そうです。またビルドプロセスはなく、Markdownを修正すれば良いだけで、手軽に使えます。後はJavaScriptのMarkdownパーサーでHTMLを描画します。

処理として常に動的なので、クローラーなどに対応できないのが残念なところかも知れません。人が見る前提であれば十分使えるライブラリと言えそうです。

dittoはJavaScript製、MIT Licenseのオープンソース・ソフトウェアです。

ditto chutsu/ditto