設定#

ovellum.config.* に置くすべてのフィールド。これが正式な情報源であり、 スキーマ変更があれば同時に更新されます。

ヒント: ovellum init は、すべてのオプションを含む完全にコメント付きの ovellum.config.ts を書き出します。有効なものは設定済み、その他はデフォルト値と 許容値とともにコメントアウトされています。すべてそのファイル内でいじることができ、 このページはより詳細なリファレンスです。

ファイル形式#

プロジェクトのルートに ovellum.config.{ts,mts,cts,js,mjs,cjs,json} を置きます。 検出は c12 によって行われ、列挙したすべての拡張子が動作します。

TypeScript（推奨）:

import { defineConfig } from 'ovellum';

export default defineConfig({
  mode: 'hybrid',
  input: './src',
  output: './docs',
});

JSON:

{
  "mode": "hybrid",
  "input": "./src",
  "output": "./docs"
}

すべてのフィールドは省略可能で、適切なデフォルト値が適用されます。

トップレベルのフィールド#

protect（hybrid モード + マージャー）#

hybrid モードでマージエンジンと孤立の扱いを制御するために使われます。

interface ProtectConfig {
  blockTag: string;
  inlineTag: string;
  orphanStrategy: 'quarantine' | 'warn';
  orphanDir: string;
  orphanRetention: number;
}

site（manual モード）#

静的サイトビルダーが利用する設定です。

interface OvellumSiteConfig {
  title?: string;
  logo?: string;
  favicon?: string;
  home?: string;
  description?: string;
  baseUrl?: string;
  basePath?: string;
  locales?: { code: string; label: string; strings?: Record<string, string> }[];
  defaultLocale?: string;
  ai?: { enabled?: boolean; llmsTxt?: boolean; fullText?: boolean; mdMirror?: boolean };
  defaultTheme: 'auto' | 'light' | 'dark';
  palette: 'default' | 'nord' | 'flexoki' | 'solarized' | 'eink';
  accent?: string;
  font: 'sans' | 'serif' | 'inter' | 'geist';
  dateFormat: 'humanized' | 'iso';
  codeTheme: 'github' | 'nord' | 'solarized';
  footer: string;
  credit: boolean;
  editUrlPattern?: string;
  headExtra?: string;
  search: { enabled: boolean };
  pageMeta: { readingTime: boolean; lastModified: boolean };
  sidebar: { collapse: boolean };
  backToTop: { enabled: boolean; threshold: number };
  publicDir: string;
  ignoreFolders: string[];
  ignoreFiles: string[];
  topbarNav: Array<{ label: string; href: string; icon?: string; external?: boolean }>;
  footerNav: Array<{ label: string; href: string; icon?: string; external?: boolean }>;
  landing: OvellumLandingConfig;
}

topbarNav[]#

search#

{ enabled: boolean }。true のとき、ビルドは:

1. 出力ディレクトリに対して Pagefind を実行し、 dist/pagefind/ 配下に静的検索インデックスを生成します。
2. Pagefind の UI をトップバーに追加します。Ovellum のデザイントークンでテーマ付けされ、 アクセント／前景／背景の色を自動的に継承します。

ランタイムのインデクサーはありません。検索結果はサイトに同梱された静的インデックスから 得られるため、サーバー不要であらゆる静的ホストで動作します。

pageMeta#

{ readingTime: boolean, lastModified: boolean }。どちらもデフォルトは true。

• readingTime — 可視の文章の語数を数え（コードブロック、インラインコード、 リンク URL、HTML、見出しの記号を除去）、約 200 wpm で割り、切り上げます。 常に最低 1 min read です。
• lastModified — ページのフロントマターの updated: が設定されていれば それが優先されます（例: updated: 2026-05-20 — 日付を明示的に固定します。 解析できない値は警告を出してフォールバックします）。なければ git （git log --follow --diff-filter=AM -1 --format=%cI -- <path>）を試します。 リネームを追跡し、内容を変更したコミットだけを数えるため、ファイルの移動 （git mv）で日付がリセットされません。ファイルが追跡されていない、 または git が使えない場合はファイルシステムの mtime にフォールバックします。 どちらも解決できなければ省略されます。行の Edited の半分としてレンダリングされ、 表記は dateFormat に従います（Edited today / Edited Jun 14, 2026 / Edited 2026-06-14）。

いずれかを false にするとその半分が非表示になります。両方を false にすると メタ行全体が非表示になります。

ai#

{ enabled?: boolean, llmsTxt?: boolean, fullText?: boolean, mdMirror?: boolean }。 llmstxt.org の慣習に従った、HTML に対する AI フレンドリーな コンパニオン出力です — コーディングエージェントや LLM がドキュメントをクリーンな Markdown として読めるようにします。HTML 出力は一切変更されません。 これらは HTML と並べて配信される追加ファイルです。

ドラフトと 404 ページはすべての AI 出力から除外されます（sitemap.xml / feed.xml と同じルール）。i18n サイトでは各ロケールがそのプレフィックスのルートに 独自のセットを持ちます — デフォルトロケールは /llms.txt、その他は /ja/llms.txt と /ja/**/*.md。

// 完全に無効化する:
export default defineConfig({
  site: { ai: { enabled: false } },
});

// または全文ファイルを追加する（デフォルトはオフ）:
export default defineConfig({
  site: { ai: { fullText: true } },
});

site.landing#

通常のドキュメントインデックスの代わりに / でレンダリングされる、オプトインの ランディングページです。デフォルトでは無効です。有効にすると、content/index.md は 警告とともにスキップされます（ランディングがそれを置き換えます）。

interface OvellumLandingConfig {
  enabled: boolean;
  docsHref?: string;
  hero: {
    title?: string;
    subtitle?: string;
    ctas: Array<{ label: string; href: string; style?: 'primary' | 'secondary' }>;
  };
  features: Array<{ icon?: string; title: string; description: string }>;
  install?: Array<{ title: string; code: string; lang?: string }>;
  trustStrip?: {
    label?: string;
    items: Array<{ name: string; href?: string; image?: string }>;
  };
}

hero.ctas[]#

install[]#

ヒーローの CTA の直後、フィーチャーグリッドの前にレンダリングされるコマンド スニペットです。各スニペットの code はドキュメントのコードブロックと同じ Markdown/shiki パイプラインを通るため、構文ハイライトと、右端に垂直方向で 中央寄せされた右上のアイコン式コピーボタンが付きます。インストールスニペットは 言語ラベルなしでレンダリングされます。他の場所のドキュメントコードブロックは 言語ラベルとテキスト式コピーボタンを保持します。

title は、ブロックの上に見出しとしてレンダリングされるのではなく、コードブロック内の 先頭コメント行として折り込まれます（シェル系の言語では # Install Ovellum globally、 JS/TS 系の言語では // …）。コメントのプレフィックスは lang から選ばれます。 コピーボタンはコマンド（code）のみをコピーし、折り込まれたタイトルコメントは 決してコピーしません。

features[]#

trustStrip#

trustStrip.items[]#

任意の content/_landing.md#

site.landing.enabled が true のとき、ビルドは {input}/_landing.md を探します。 存在する場合、その本文がフィーチャーグリッドとトラストストリップの間に「Why」 セクションとしてレンダリングされます。アンダースコアのプレフィックスにより通常の ページ走査から外れるため、サイドバーにも単独の URL としても現れません。

update#

CLI の更新チェック — コマンドの完了後に表示される 1 行の「update available」通知 — を制御します。これはあくまで案内であり、ovellum upgrade なしに何かがインストールされることはありません。

interface OvellumUpdateConfig {
  check: boolean;
  intervalHours: number;
}

このチェックは、check の値に関係なく、CI、非対話シェル、NO_UPDATE_NOTIFIER 環境変数が設定されている場合、--no-update-check が渡された場合にはさらに抑制 されます。コマンドを遅延させたり失敗させたりすることは決してなく、あらゆるエラー経路 （オフライン、タイムアウト、不正なレスポンス）は静かに握りつぶされます。

ファイルごとの上書き #

任意の .md / .mdx ファイルのフロントマターで、そのファイルのモードを上書きできます。

---
ovellum:
  mode: manual
---

ovellum: ブロック内で認識されるキー:

ジェネレーターがすべての自動生成ファイルに書き込む裸の ovellum: true マーカーは、 モードの上書きではありません。パーサーは ovellum: true（マーカー）と ovellum: { … }（上書きブロック）を区別します。

ページごとのフロントマター（manual モード）#

フロントマターは省略可能です。 先頭に YAML プリアンブルがない .md ファイルでも 問題なくビルドされます。Ovellum は本文とファイル名から必要なものを推測します。

したがって実際には:

• ファイルがきれいな # Heading で始まるなら title: を省略できます。 サイドバーと <title> の両方がその H1 を使います。サイドバーのラベルをページ見出しと 変えたい場合（例: 短いサイドバーラベルと長めのページ見出し）にだけ title: を追加します。
• ソーシャルカードや検索結果からリンクされると見込まれるページには description: を追加してください。推測されるフォールバックがなく、このフィールドがないと meta タグが省略されるためです。

任意の .md ページのフロントマター内で認識されるキー（上記の ovellum: 上書きとは 直交します）:

_meta.json（ディレクトリごと、manual モード）#

input/ の任意のサブディレクトリに置いて、サイドバーのグループ化を制御します。

{
  "title": "Guides",
  "order": ["install", "configure", "deploy"]
}

検証#

すべての読み込みは validateUserConfig() を通ります。不正なフィールドは、その悪い フィールド名を示すパス付きのメッセージとともに ConfigError をスローし、CLI は コード 3 で終了します。

検証される項目:

• すべてのフィールドの型。
• 列挙値（mode、defaultFormat、orphanStrategy、site.defaultTheme、 site.landing.hero.ctas[].style）。
• include / exclude の文字列配列。
• protect.orphanRetention >= 0 かつ有限であること。
• ランディングページのサブオブジェクトの必須フィールド（hero.ctas[].label、 features[].title、install[].title、install[].code など）。

バリデーターはパスのファイルシステム上の存在は確認しません。それは必要なら 後のビルドで表面化します。