トラブルシューティング#

実際にぶつかる問題を、原因と対処とともに。多くは明確な CLI メッセージとして現れます — このページはそれぞれが何を意味するかを説明します。

保護ゾーンがマージされない#

hybrid モードでは、手書きのプロースがリビルドを生き延びるのは、 生成されたアンカーに紐付いた @manual ゾーンの中にある場合だけです:

<!-- @manual:start id="src/utils/format.ts::padZero" -->
ここにプロース — 毎回のリビルドでそのまま保持されます。
<!-- @manual:end -->

• id がない？ id="…" がないと、Ovellum は位置ベースのフォールバックを合成して 警告します: protected zone "manual-block-1" uses a positional fallback id. Add id="…" on the <!-- @manual:start --> tag so the block survives reordering. ブロックは マージされますが、シンボルではなく位置に紐付きます — ファイルの並べ替えで プロースが別のセクションに移らないよう id を追加してください。id は ジェネレーターが出力するアンカーコメントと一致します: <!-- ovellum:anchor id="src/utils/format.ts::padZero" … -->（形式は <ソースファイル>::<シンボル>）。

• ovellum check --strict は id のないゾーンを positional-zone、アンカーが もう存在しないゾーンを stale-anchor として報告するので、問題になる前に CI で 両方を捕まえられます。

@manual タグの不一致#

これらはハードエラーです（ビルドが終了コード 3 で停止します）:

すべての @manual:start には対応する @manual:end がちょうど 1 つ必要で、ゾーンは ネストできません。

リビルド後にプロースが消えた（孤立）#

消えていません — 隔離されただけで、捨てられてはいません。ゾーンが紐付いていた シンボルがリネーム・削除されるとアンカーが消えるので、マージャーはプロースを失わずに .ovellum/orphans/（protect.orphanDir）へ移します。ビルドサマリーは quarantined: の下に ↪ <path> の行で一覧します。

復旧:

ovellum orphans                 # 隔離されたプロース + アンカーが戻っているかを一覧
ovellum orphans --stale         # protect.orphanRetention（デフォルト 90 日）より古いものだけ
ovellum orphans --reattach      # 各項目を対話的に再アタッチ／削除／スキップ

ovellum orphans は各ブロックのソースドキュメント、経過日数、アンカーの状態を 表示します — present again in source — reattachable、gone from current source、 または unknown (no IR snapshot — run ovellum build)。状態はビルドが書き出す .ovellum/ir.json スナップショットから読まれるので、unknown と出たらまずビルドを 実行してください。

--reattach は対話的です（ターミナルで実行してください）。各孤立について、ソースに 戻ったアンカー（または名前の類似によるリネームの候補）への再アタッチ、別のアンカーへの 再アタッチ、削除、スキップを提示します。再アタッチは対象の下に新しい @manual ゾーンとして プロースを差し込み、アーカイブを削除します。リネーム候補を示す相棒は ovellum diff です。

設定が使われない#

いくつか確認すべき点:

• 場所・名前が違う。 ファイルはプロジェクトルートの ovellum.config.{ts,mts,cts,js,mjs,cjs,json} でなければなりません（検出は c12）。設定がないことはエラーではありません — Ovellum は組み込みのデフォルトにフォールバックし、ビルドサマリーは config: (defaults) と表示します。その行が出たらファイルが見つかっていません。 --config <path> で明示的に指定するか、別の場所から実行しているなら --cwd <dir> を使ってください。

• 不正な設定はビルドを config error: … と終了コード 3 で 停止します — 例: `mode` must be one of: hybrid, manual, auto.。 メッセージは問題のフィールドを示すので、直してリビルドします。

• import { defineConfig } from 'ovellum' が解決できない。 値のインポートには、 設定が読み込まれる場所に ovellum パッケージがインストールされている必要があります。 スキャフォールドされた設定は意図的にそれを避けています — import type { OvellumUserConfig } from 'ovellum' と export default { … } satisfies OvellumUserConfig を使い、読み込み時に消去されるので ファイルにランタイム依存がありません。ovellum をローカルにインストールするか、 import type + satisfies の形を使ってください。

ビルド済みサイトで画像やリンクが壊れている#

ほぼ必ず相対パスです。ページはきれいな URL になるので （guides/install.md → /guides/install/）、相対の architecture.svg は、ファイルの あるフォルダではなく /guides/install/ に対して解決されます。ルート絶対パスを 使ってください:

![Architecture](/guides/architecture.svg)   <!-- ✓ 常に解決される -->
![Architecture](architecture.svg)            <!-- ✗ ページ URL に対して解決される -->

その他のアセットの落とし穴:

• site.basePath は / で始まり、末尾のスラッシュはなしでなければなりません （'/ovellum'）。レンダリング時にすべての内部リンク + アセットパスの前に付加されるので、 ルート相対リンクを書き続けられます。不正な値は検証で失敗します: `site.basePath` must start with `/` … or be the empty string.
• public/ はサイトルートにマッピングされます — public/favicon.ico → /favicon.ico。public/ プレフィックスなしでルートから参照してください。
• ovellum check はページリンクを検証しますが、アセット URL は検証しません。 画像やダウンロードはページではなくファイルを指すので、ローカルの ovellum serve （または ovellum dev）で確認してください。アセットを参照。
• CDN を使う？ site.assetBaseUrl は public/ の参照を書き換えますが、クエリ文字列付きや srcset の URL は書き換えません — それらは最終的な CDN の URL で参照してください。

ovellum dev が manual モードのみと言う#

そのとおりです — dev は manual モードのライブプレビューループです。auto/hybrid では、 ovellum watch（変更ごとに Markdown をリビルド）を実行して出力を自分で配信するか、 単に ovellum build を使ってください。メッセージが代替手段を示します。

終了コード#

コマンド間で安定しているので、CI が分岐に使えます:

--json モードでは ConfigError は stdout に { "ok": false, "error", "hint" } として 出ます — 自動化を参照。

それでも詰まったら#

コマンドに --verbose を付けると、設定解決のパスと各ステージの詳細が出ます（stderr に 出るので --json と併用できます）。完全なフラグ一覧は CLI リファレンスを 参照してください。バグのように見える場合は Issue を立ててください。