Ovellum

2 min read · Updated

Modes#

Ovellum has one configuration knob that decides which pipeline runs:

{
  "mode": "hybrid"
}

Three values are valid: auto, manual, and hybrid. Pick once per project, or override per-directory or per-file. They are designed to be mixed freely; nothing forces you to commit to one for the whole repo.

auto#

Generates Markdown documentation from your TypeScript / JavaScript source and writes it to output/. Existing output is overwritten on every build. No merge step, no manual layer.

src/utils/format.ts   →   docs/utils/format.md
src/models/User.ts    →   docs/models/User.md

Use this when:

  • You only have an API reference to publish.
  • You're treating docs as a build artifact, not a hand-edited surface.
  • You're migrating from TypeDoc or similar and want the same workflow with a different output shape.

The output is plain Markdown — you can post-process it with anything that reads .md.

manual#

The opposite end. Ovellum acts as a Jekyll-style static-site builder. It walks input/ for .md files and produces a deployable HTML site — sidebar nav, right-side ToC, syntax-highlighted code, themes. No source parsing involved.

content/index.md            →   dist/index.html
content/getting-started.md  →   dist/getting-started/index.html
content/guides/deploy.md    →   dist/guides/deploy/index.html

Use this when:

  • You're writing docs by hand and want a clean output without source-of-truth generation.
  • You're building a marketing site or landing page alongside your docs (enable site.landing for a Material for MkDocs-style homepage).
  • You're hosting purely-prose content that has nothing to do with your code.

This site you're reading is built in manual mode.

hybrid (default)#

Generates from source, then merges your hand-written content back in. Your prose lives inside the same files as the auto-generated reference. Ovellum respects a tagging contract: anything between <!-- @manual:start --> and <!-- @manual:end --> is yours and never gets touched. Everything else is auto-generated and may be rewritten on every build.

                            ┌──────────────┐
src/utils/format.ts ────►   │  build       │   ────►  docs/utils/format.md
docs/utils/format.md ───►   │  parse + gen │
(existing manual blocks) ►  │  + merge     │
                            └──────────────┘

Use this when:

  • You have an API surface that benefits from generation, plus narrative content that lives alongside it.
  • You want one place to look for everything about a function — its signature, its parameters, and the team note that says "be careful, this is the slow path."
  • You want renamed or deleted symbols to surface their orphaned prose for review rather than silently lose them.

The tagging contract is covered in Anchors and zones; orphan handling is in Orphans.

Per-directory and per-file overrides#

The mode field can also live in:

  • A nested ovellum.config.* in any subdirectory. Deeper wins on conflict.

  • The ovellum: block in a single file's frontmatter:

    ---
ovellum:
  mode: manual
---

    The page is treated as manual content even if the project default is auto or hybrid.

The full override resolution lives in Reference → Config.

Edit this page