Ovellum への移行#

ドキュメントがソースから生成されたものでも、手書きの Markdown でも、ホスト型の プラットフォーム上にあっても、これが Ovellum へ移すための地図です — そしてそうすることで 何が得られるかも。

中心となる考え方#

Ovellum には 3 つのモードがあり、ドキュメントの出所によって適切なものが決まります:

Ovellum が中心に据えているのは hybrid です: 生成されたリファレンスと手書きの物語が 同じファイルにあり、プロースが上書きされることも、黙って失われることもありません。 それが、ほかにはない機能です。

ソース駆動の API ジェネレーターから（例: TypeDoc）#

今日 TypeScript から API ドキュメントを生成しているなら、Ovellum の auto モードが直接の 等価物です — ts-morph でソースを解析し、すでに書いている JSDoc/TSDoc タグ（@param、@returns、@throws、@example、@deprecated、@since、 @see、@remarks、@internal など）を読み、ソースファイルごとに 1 つの Markdown を 出力します。

乗り換える理由は hybrid モードです。純粋なジェネレーターは選択を強います: 手編集は 次の実行で消されるので、すべてのプロースは別ファイルに置かれ、同期がずれていきます。 Ovellum では生成ファイルの中に、@manual ゾーンとして物語を書けます:

<!-- @manual:start id="src/client.ts::Client" -->
`Client` は長命です — プロセスごとに 1 つ作って共有してください。プーリングについては
[接続ガイド](/guides/connections/)を参照。
<!-- @manual:end -->

ジェネレーターはそのゾーンの周りを更新し、上から更新することはありません。そして シンボルをリネーム・削除しても、プロースは捨てられず — 隔離されて .ovellum/orphans/ に入るので、再アタッチできます。その「決して同期がずれないドキュメント」の 保証こそが核心です。

持ち込み方: input をソースに向け、mode: 'hybrid' を設定し、ovellum build を実行。 最初のビルドで生成されたリファレンスができます。物語を入れたいところに @manual ゾーンを 追加してください。（手編集なしの生成出力だけが欲しいなら mode: 'auto' を使います。）

手書きの Markdown サイトから#

すでにドキュメントが静的サイトジェネレーターでビルドされた Markdown なら、Ovellum の manual モードは本格的な静的サイトビルダーです — .md ファイルを入れるだけで、標準で こうしたものが手に入ります:

• ファイルツリーからのナビゲーション（フォルダ → セクション）。順序・タイトル・ 折りたたみは _meta.json で。きれいな URL、右側の自動目次。
• テーマ設定 — ちらつきのない light/dark、5 つのパレットに加え ホストを継承する bare モード、設定可能なアクセント、システムまたはバンドルのフォント。
• オーサリング — GitHub 風のコールアウト、脚注、 コンポーネントディレクティブ（tabs/steps/cards）、 Mermaid 図、コピーボタン付きの Shiki シンタックスハイライト。
• 検索（Pagefind、⌘K）、i18n （ロケールごとのサブツリー + 言語ピッカー）、バージョン管理、 ドラフト、ランディングページ、テーマ付き 404、sitemap.xml
  • RSS、ページごとの読了時間／「Edited」日付。
• AI フレンドリーな出力 — llms.txt、llms-full.txt、 各ページの .md ミラーを HTML と並べて出力。

完全なツアーは manual モードを参照。

持ち込み方（下記の手順を参照）: Markdown をコンテンツ ディレクトリにコピーし、古いナビ設定をフォルダごとの _meta.json に変換し、フロントマター （title、description、tags、permalink）を保持または追加し、ovellum check で リンク切れを捕まえます。

ホスト型ドキュメントプラットフォームから#

ドキュメントがホスト型のプラットフォーム上にあるなら、移行は機能と同じくらい 所有権の話です。Ovellum はポータブルな静的フォルダをビルドします — プレーンな HTML/CSS と少しの JS — それをどこへでもデプロイできます: GitHub Pages、Netlify、Vercel、 Cloudflare、S3 バケット、あるいはホストツール独自のパイプライン。生かし続けるサーバーサイドの ランタイムはなく、出力に独自仕様のものはありません。

保持できるもの — あるいは得られるもの:

• コンテンツはリポジトリ内のプレーンな Markdown のまま。 エクスポート手順も、後で 逃れるべき独自フォーマットもありません。
• デフォルトで AI ネイティブ — 組み込みの MCP サーバー（ovellum mcp、MCP レジストリに 掲載）により、エージェントは検索・読み取り・diff だけでなく、再生成を生き延びる保護ゾーンへ 書き込むこともできます — 読むだけではありません。加えて機械可読な --json と安定した 終了コード。
• ロックインなし — ビルドこそが成果物で、ホストはあなたの選択です。（Ovellum は ビルドし、ホストがデプロイします。）

持ち込み方: ページを Markdown にエクスポートして content/ に置き、下記の手順に従います。 多くのホスト型プラットフォームは十分に近い Markdown をエクスポートするので、主な作業は ナビ（_meta.json）とアセットパスを ルート絶対に 直すことです。

コンテンツを持ち込む#

どこから来ても、同じひと握りの手順です:

1. スキャフォールド — ovellum init がコメント付きの ovellum.config.ts、スターターの content/index.md、AGENTS.md、.gitignore エントリを書き出します。--yes で デフォルトを受け入れます。
2. Markdown を入れる — .md ファイルを設定済みの input（デフォルト content/）の下に 置きます。サブフォルダはサイドバーのセクションになり、各ファイルは <slug>/index.html の ページになります。ルートに既存の README.md があれば自動的にホームページになります。
3. ナビの順序付け — 特定の順序やタイトルが欲しいディレクトリに _meta.json を追加: { "title": "Guides", "order": ["install", "configure"] }。未掲載のページはその後に アルファベット順で並びます。どこでも任意です。
4. フロントマター（すべて任意） — title、description、tags、permalink （/faq/ のようなカスタム URL）、draft: true（dev で表示、build から除外）、 updated（「Edited」日付を固定）。タイトルは最初の # H1、次にファイル名へフォール バックします。
5. アセットパスを直す — 画像／ダウンロードのリンクをルート絶対（img/x.png ではなく /img/x.png）にして、きれいな URL でも壊れないようにします。ルートで配信するファイル （favicon、robots.txt）は public/ に置きます。
6. 検証 — ovellum check がリンク切れの内部リンクを報告します（問題があれば終了 1、 --strict でさらに、--json は CI 向け）。そして ovellum build して dist/ をデプロイ。

途中で問題が起きたら、トラブルシューティングガイドが よくあるつまずきをカバーします。