# Ovellum

> Ovellum is an open-source documentation tool for TypeScript and JavaScript. It lets auto-generated API docs and hand-written narrative live together in the same files, without conflict.

## Docs

- [Getting started](/docs.md): Install Ovellum, point it at your project, and build your first docs.
- [Install](/docs/install.md): Add Ovellum to your project with pnpm, npm, yarn, or bun.
- [Modes](/docs/concepts/modes.md): Auto, manual, and hybrid — three pipelines, one tool.
- [Anchors and protected zones](/docs/concepts/anchors-and-zones.md): The tagging contract that lets auto-generated and hand-written content coexist.
- [Orphans](/docs/concepts/orphans.md): What happens to your prose when the symbol it documents goes away.
- [Ovellum for AI agents](/docs/concepts/ai-ready.md): Your docs are llms.txt-ready out of the box, an agent can drive Ovellum as a tool, and — uniquely — an agent can edit generated docs without its prose being overwritten.
- [Building a manual-mode site](/docs/guides/manual-mode.md): From a folder of Markdown files to a deployable static site.
- [Mixing auto and manual (hybrid mode)](/docs/guides/hybrid-mode.md): One file, two authors — the merge engine that lets them coexist.
- [Development](/docs/guides/development.md): The day-to-day loop — scaffold, write, watch, check, build, deploy.
- [Drafts](/docs/guides/drafts.md): Work-in-progress pages that you preview locally but never publish — marked with frontmatter or per-folder, shown in dev with a ribbon, excluded from production.
- [Assets & downloads](/docs/guides/assets.md): Where to put images, video, audio, PDFs, and other files — and how to reference, embed, or link them.
- [Components](/docs/guides/components.md): Callouts, steps, cards, and tabs — rich content blocks written in plain Markdown with directive syntax.
- [Snippets & includes](/docs/guides/snippets.md): Author a piece of Markdown once and include it on many pages — with the same sanitization, directive support, and link checking as inline content.
- [Theming](/docs/guides/themes.md): How the default theme is structured, where to override, and what the topbar / hero / icon system give you for free.
- [Multiple languages (i18n)](/docs/guides/i18n.md): Publish your docs in more than one language — per-locale content, a topbar language picker, default-at-root URLs, and hreflang, all opt-in.
- [Versioned docs](/docs/guides/versioning.md): Publish v1, v2, and next side by side — directory-per-version with a topbar version picker.
- [Search](/docs/guides/search.md): Full-text site search powered by Pagefind — a build-time index, queried entirely in the browser. No server, no service, no API keys.
- [Deploy](/docs/guides/deploy.md): Build once to a self-contained dist/ folder, then host it anywhere — self-hosted, GitHub Pages, Cloudflare, or any static host.
- [Automation & AI agents](/docs/guides/automation.md): Drive Ovellum from a script, a CI job, or an AI agent — machine-readable --json output, stable exit codes, and an MCP server.
- [Plugins](/docs/guides/plugins.md): Extend the build with plugins — lifecycle hooks for config, per-page transforms, and deploy logic (onBuildComplete).
- [Migrating to Ovellum](/docs/guides/migration.md): Moving from TypeDoc, from a hand-written Markdown site, or from a hosted docs platform — what changes, what Ovellum adds, and how to bring your content across.
- [Troubleshooting](/docs/guides/troubleshooting.md): Fixes for the common snags — zones not merging, unbalanced @manual tags, config not loading, broken asset paths, and recovering quarantined prose.
- [Configuration](/docs/reference/config.md): Every field in `ovellum.config.{json,ts,js}` with its type, default, and effect.
- [CLI reference](/docs/reference/cli.md): Every subcommand and flag in the `ovellum` CLI.
- [Styleguide](/docs/reference/styleguide.md): The typography, scale, rhythm, color, and content elements Ovellum renders — what every Markdown page looks like, and how the system is built.
- [Security](/docs/reference/security.md): Threat model, sanitization policy, and the protections Ovellum applies by default.
- [Glossary](/docs/reference/glossary.md): One-line definitions for terms that appear across the docs.
- [Contributing](/docs/contributing.md): Set up the repo, run the tests, and send a pull request.