Merge engine, not overwrite engine
Tag sections of your Markdown as human-owned with a single comment pair. Ovellum updates the auto-generated parts around them; your prose survives every rebuild.
Documentation that doesn't drift.
Ovellum is an open-source documentation tool for TypeScript and JavaScript. Auto-generate from source, hand-write narrative pages, or mix both in the same file. Your prose never gets silently overwritten.
Three modes, one tool
`auto` regenerates from source. `manual` builds a static site from Markdown. `hybrid` (default) merges the two. Switch per-project or per-file.
Orphans are quarantined, never lost
When you rename or delete a documented symbol, any hand-written prose tied to it gets archived to `.ovellum/orphans/`. Reviewable in PRs, recoverable any time.
Markdown-first, no lock-in
Plain `.md` files everywhere. No proprietary format, no required MDX, no special syntax beyond a tagging comment. Your content stays portable.
Fluid type and OKLCH themes
Utopia-derived type and space scales. OKLCH palette with auto/light/dark themes. The pre-paint script keeps theme switches flash-free.
Build-time syntax highlighting
Code blocks render through shiki with dual `github-light` / `github-dark` themes baked into the HTML. Zero runtime JavaScript for syntax colour.
Why Ovellum?#
Documentation tools force you to choose. Either you generate everything from source and lose the human voice, or you hand-write every page and watch it quietly fall out of sync as the code moves on. Teams end up running two parallel worlds — a generated API reference nobody reads and a hand-written guide that's three versions behind reality.
Ovellum refuses the tradeoff. It introduces a small tagging contract between the tool and the author. You mark sections of a page as yours; Ovellum updates everything around them and never touches the parts you own. When the underlying code changes — a function renamed, a class removed — your prose isn't silently dropped. It's quarantined, surfaced in your build summary, and left in version control so you can review what changed and decide what to do.
The same machinery doubles as a Jekyll-style static-site builder. Point Ovellum at a folder of Markdown files and it produces a deployable site: auto-generated sidebar nav, right-side "On this page" table of contents, syntax-highlighted code, auto/light/dark themes. No proprietary format. No runtime JavaScript for the parts the browser doesn't need.
This site you're reading was built by ovellum build from
website/content/
and deployed to GitHub Pages by a workflow that runs on every push to main.
The whole thing is dogfooded; if Ovellum had a bug, this site would have it
too.
Powered by