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