Configuration#

Every field that lives in ovellum.config.*. Authoritative; updated alongside any schema change.

Tip: ovellum init writes a fully-commented ovellum.config.ts with every option present — active ones set, the rest commented with their defaults and allowed values. You can tinker entirely in that file; this page is the deeper reference.

File format#

Place an ovellum.config.{ts,mts,cts,js,mjs,cjs,json} at the project root. Discovery is via c12; all the listed extensions work.

TypeScript (recommended):

import { defineConfig } from 'ovellum';

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

JSON:

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

All fields are optional; sensible defaults apply.

Top-level fields#

protect (hybrid mode + merger)#

Used in hybrid mode to govern the merge engine and orphan handling.

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

site (manual mode)#

Settings consumed by the static-site builder.

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 }. When true, the build:

1. Runs Pagefind against the output directory to produce a static search index under dist/pagefind/.
2. Adds the Pagefind UI to the topbar, themed via Ovellum's design tokens so it inherits your accent / fg / bg colors automatically.

There is no runtime indexer — search results come from the static index shipped with the site, so it works on any static host with no server.

pageMeta#

{ readingTime: boolean, lastModified: boolean }. Both default true.

• readingTime — counts visible-prose words (code blocks, inline code, link URLs, HTML, and heading punctuation stripped) and divides by ~200 wpm, rounded up. Always at least 1 min read.
• lastModified — a page's frontmatter updated: wins if set (e.g. updated: 2026-05-20 — pin the date explicitly; an unparseable value warns and falls back). Otherwise tries git (git log --follow --diff-filter=AM -1 --format=%cI -- <path>): it follows the file across renames and counts only commits that changed its content, so moving a file (a git mv) doesn't reset its date. Falls back to the filesystem mtime if the file isn't tracked or git is unavailable. Omitted if none resolve. Renders as the Edited half of the line, worded per dateFormat (Edited today / Edited Jun 14, 2026 / Edited 2026-06-14).

Set either to false to hide that half of the line. Set both to false to hide the meta line entirely.

ai#

{ enabled?: boolean, llmsTxt?: boolean, fullText?: boolean, mdMirror?: boolean }. AI-friendly companions to the HTML, following the llmstxt.org convention — so coding agents and LLMs can read your docs as clean Markdown. The HTML output is untouched; these are additive files served alongside it.

Drafts and the 404 page are excluded from all AI output (the same rule as sitemap.xml / feed.xml). On an i18n site each locale gets its own set at its prefix root — /llms.txt for the default locale, /ja/llms.txt and /ja/**/*.md for the others.

// Opt out entirely:
export default defineConfig({
  site: { ai: { enabled: false } },
});

// Or add the whole-corpus file (off by default):
export default defineConfig({
  site: { ai: { fullText: true } },
});

site.landing#

Opt-in landing page rendered at / instead of the regular doc index. Disabled by default. When enabled, content/index.md is skipped with a warning (the landing replaces it).

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[]#

Command snippets rendered immediately after the hero CTAs and before the feature grid. Each snippet's code runs through the same Markdown/shiki pipeline as doc code blocks, so it gets syntax highlighting and a top-right icon copy button, vertically centered on the right edge. Install snippets render without a language label; doc code blocks elsewhere keep their language eyebrow and text copy button.

The title is folded into the code block as a leading comment line (e.g. # Install Ovellum globally for shell langs, // … for JS/TS-family langs) rather than rendered as a heading above the block. The comment prefix is chosen from lang. The copy button copies only the command (code), never the folded-in title comment.

features[]#

trustStrip#

trustStrip.items[]#

Optional content/_landing.md#

When site.landing.enabled is true, the build looks for {input}/_landing.md. If present, its body renders between the feature grid and the trust strip as the "Why" section. The underscore prefix keeps it out of the regular page walk, so it doesn't appear in the sidebar or as a standalone URL.

update#

Controls the CLI's update check — the one-line "update available" notice printed after a command finishes. It's a courtesy only: nothing is installed without ovellum upgrade.

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

The check is additionally suppressed — regardless of check — in CI, in non-interactive shells, when the NO_UPDATE_NOTIFIER environment variable is set, and when --no-update-check is passed. It never delays or fails a command; every error path (offline, timeout, bad response) is swallowed silently.

Per-file overrides #

Front-matter inside any .md / .mdx file may override the mode for that file:

---
ovellum:
  mode: manual
---

Recognized keys inside the ovellum: block:

The bare ovellum: true marker that the generator writes onto every auto-generated file is not a mode override. The parser distinguishes ovellum: true (marker) from ovellum: { … } (override block).

Per-page frontmatter (manual mode)#

Frontmatter is optional. A .md file with no YAML preamble at the top builds fine. Ovellum infers what it needs from the body and the filename:

So in practice:

• Skip title: if your file starts with a clean # Heading — the sidebar and <title> will both use that H1. Add title: only when you want the sidebar label to differ from the page heading (e.g. short sidebar label, longer page heading).
• Add description: for any page you expect to be linked from social cards or search results, since there's no inferred fallback — the meta tag is omitted when this field is absent.

Recognized keys inside the frontmatter of any .md page (orthogonal to the ovellum: override above):

_meta.json (per-directory, manual mode)#

Place inside any subdirectory of input/ to control sidebar grouping:

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

Validation#

Every load passes through validateUserConfig(). Invalid fields throw a ConfigError with a path-qualified message naming the bad field, and the CLI exits with code 3.

Validated:

• Types of every field.
• Enums (mode, defaultFormat, orphanStrategy, site.defaultTheme, site.landing.hero.ctas[].style).
• Arrays-of-strings for include / exclude.
• protect.orphanRetention >= 0 and finite.
• Required fields on landing-page sub-objects (hero.ctas[].label, features[].title, install[].title, install[].code, etc.).

The validator does not check filesystem existence of paths; that surfaces later in the build if it matters.