weblog of key_amb

主にIT関連の技術メモ

Markdown による中規模ドキュメンテーションシステムについて調べた。

(追記)
タイトルを "【緩募】Markdownによる中規模ドキュメンテーションシステム" から変えました。

(更に追記)
後日談 => Hugo で "bootie-docs" というドキュメンテーション用のテーマを作った #Hugo - weblog of key_amb


下のような疑問を持ったのがきっかけで、Twitter でつぶやきつつ調べたりしていました。

結論としては下の方に書いてある通り、静的サイトジェネレータの JekyllMkDocs あたりを使うのがよさそうです。

最初、Sphinx が手堅いだろうと思いましたが、今や Sphinx でなければならない理由はないかな、と。

Pandoc や MultiMarkdown について補足

Pandoc - About pandoc

上が本家サイトで、日本語の情報は @sky_y さんがよくまとめて下さっています。

http://sky-y.github.io/site-pandoc-jp/:title

多様な入出力に対応しているところが Fluentd / Embulk あたりに似ていて面白いですね。
活発に開発が行われているようです。

が、Pandoc にしろ MultiMarkdown にしろ、単独のファイルを Markdown => HTML に変換することは問題ないようですが、そこそこ構造化されたドキュメント群を生成するには一工夫要りそうな印象です。

その点でもやはり Sphinx はカタくて、特に設定しなくても Qiita に書いたような手順(下)で簡単にドキュメントの雛形から HTML 群を生成するところまでイケました。

逆に、Pandoc OR MultiMarkdown を使って、構造化されたドキュメント群を生成する支援ツールを作るのもいいかもしれませんね。

Twitter でのやりとり

ここまで書いたところ、Twitter で @sonots さんからコメントもらいました。

ブログ形式だとちょっとドキュメントに向かないかもですが、 Octopress のドキュメントも Octopress で書かれてるようだし、問題ない気もします。
…というわけで、これをヒントに静的サイトジェネレータをあさっていたら、まさしくドキュメンテーション用途のものがありました。

また、Jekyll の場合、jekyll-docs-templateというテンプレートがあるので、これを使うとよさそうです。

静的サイトジェネレータについては、下記サイトを参考に探しました。

その他、何か知見をお持ちの方はお知らせいただけるとうれしいです。