自動・手動・ハイブリッド、決して同期がずれないドキュメント。
Ovellum は TypeScript と JavaScript のためのオープンソースのドキュメントツールです。自動生成された API ドキュメントと手書きのナラティブを、競合なく同じファイルの中で共存させます。
# Ovellum をグローバルにインストール
npm install -g ovellum
# インストールせずに実行
npx ovellum init
# プロジェクトに追加
npm install -D ovellum
マージエンジン
コメント 1 組で、Markdown のセクションを人間が所有する部分として印します。Ovellum はその周囲の自動生成部分だけを更新し、あなたの文章はどのリビルドでも生き残ります。
AI ネイティブ
ビルドごとに `llms.txt` とページ単位の Markdown ミラーを出力するので、エージェントは HTML をスクレイピングせずにドキュメントを読めます。最初から AI 対応です。
MCP で操作
Ovellum は Model Context Protocol サーバーを同梱します。エージェントはシンボルの検索・全文検索・diff、そして再生成を生き延びる保護ゾーンへの文章の書き込みができます。
3 つのモード
`auto` はソースから再生成します。`manual` は Markdown から静的サイトを構築します。`hybrid`（デフォルト）は両者をマージします。プロジェクト単位でもファイル単位でも切り替えられます。
孤立ブロックを隔離
ドキュメント化されたシンボルの名前を変更・削除すると、それに結びついた手書きの文章は `.ovellum/orphans/` にアーカイブされます。PR でレビューでき、いつでも復元できます。
どこへでもデプロイ
`ovellum build` は自己完結したフォルダ（HTML・CSS・約 2KB の JS）を生成します。任意の静的ホストに置くか、別のビルドに埋め込めます。
なぜ Ovellum なのか#
ほとんどのドキュメントツールは、二者択一を迫ります。すべてをソースから生成して人間が書いたメモを失うか、すべてのページを手で書いて、コードが変わるたびにそれが静かにずれていくのを見守るか。結果としてチームは2つの並行した世界を抱えることになります。(i) 生成された API リファレンスと、(ii) 現実より3バージョン遅れた手書きのガイドです。
Ovellum はこのトレードオフのバランスを取ります。ツールと書き手のあいだに、小さなタグ付けの取り決めを導入するのです。ページの一部を「あなたのもの」として印を付けると、Ovellum はその周囲のすべてを更新し、あなたが所有する部分には決して手を触れません。関数のリネームやクラスの削除など、背後のコードが変化したとき、その散文は隔離され、ビルドのサマリーに表示され、バージョン管理に残されます。これにより、何が変わったのかを確認し、どう対応するかを自分で決められます。
同じ仕組みが、Jekyll スタイルの静的サイトビルダーとしても機能します。Ovellum に Markdown ファイルのフォルダを指定すれば、デプロイ可能なサイトが生成されます。自動生成されるサイドバーナビゲーション、右側の「このページの内容」目次、シンタックスハイライト付きのコード、自動/ライト/ダークのテーマ。独自フォーマットはありません。ブラウザが必要としない部分のためのランタイム JavaScript もありません。
いまご覧になっているこのサイトは、website/content/ から ovellum build によって生成され、main への push のたびに実行されるワークフローで GitHub Pages にデプロイされています。
すべてがドッグフーディングされています。もし Ovellum にバグがあれば、このサイトにも同じバグがあるはずです。