Markdownでドキュメントを生成するソフトウェア

有名どころを3つ

ナウさを感じる準に並べます(主観)

• Docusaurus
• MkDocs
• GitBook

いずれも Mermaid でダイアグラムを表現したり、OpenAPIのドキュメントをページに埋め込んでレンダリングするなどカスタマイズが効きます。

Docusaurus はSPA構成になっていたり、Algoliaと連携して全文検索を行うことができるなど最もナウい印象です。

基本設計や詳細設計を書く必要があるプロジェクトでMkDocsを使っていますが特に困ることはなく体験よく仕事を進められています。

「Notionじゃダメなのか」

下記の要求・要件がある場合、Notionより適していると考えます。

• レビューが必須でチーム開発でコラボレーションが必要
• ドキュメントのポータビリティが欲しい
  • そのドキュメントが納品物である
  • 内容をフリーズする必要がある。
  • プロジェクトが終わると更新頻度や閲覧頻度が極端に下がる
  • SaaSの利用が適さない
    • SaaSのランニングコスト決裁を取りづらい
• 社外に公開する必要がある
  • APIなどソフトウェアの設計
    • Protobufのドキュメント化、OpenAPIのドキュメント化など