@odla-ai/docs

⚠️ Early access — pre-1.0. Agents work from bounded runbooks; humans approve credentials, production changes, releases, and merges. APIs and exact package availability can change. Review the documented guarantees and limitations; this software is MIT-licensed and provided without warranty.

A build-time docs engine: point it at a directory of markdown and get one manifest that supports two hosts from a single source —

• a themed human docs site rendered as static HTML, and
• a serializable content manifest rendered inside an application without shipping a Markdown parser.

It is built on @odla-ai/blog's markdown renderer (marked + build-time highlight.js — no client JS) and the @odla-ai/ui design system (one --ui-* token contract, five themes). Node-only: never import it from browser or Worker code — it pulls in the markdown highlighter.

Content

A content dir is markdown with YAML frontmatter:

---
title: Quickstart
group: Start          # nav section
order: 10             # sort within group; group order = min(page.order)
slug: quickstart      # defaults to the filename
summary: One-line lede.
audience: [operator, agent]
goldenPath: build     # optional: tags a page into an agent golden path
packageRef: "@odla-ai/db"
---
markdown body, with `> [!WARN]` admonitions and inline ui elements…

API

import { loadDocs, buildManifest, renderSite, emitManifestModule } from "@odla-ai/docs";

const pages = await loadDocs("content");        // DocPage[] (html + metadata)
const manifest = buildManifest(pages);          // { groups, pages }
await renderSite({ contentDir: "content", outDir: "dist/docs", theme: "juniper" });
const tsModule = emitManifestModule(manifest);  // @generated data module for an app

• loadDocs(dir, { includeDrafts }) — parse + render a content tree.
• buildManifest(pages) — group/order into the nav shape both hosts consume.
• renderSite({ contentDir, outDir, theme, basePath }) — static site.
• renderDocPage(manifest, slug, opts) — one page's HTML.
• emitManifestModule(manifest) — a committed @generated TS module for in-app use.
• renderMarkdown, slugify, escapeHtml, extractHeadings, applyAdmonitions.

Tests

npm test (node's test runner). npm run coverage (c8, ≥95%). The test/fixture/content tree is the golden corpus.

The installed README is the package contract; exported source JSDoc and the public page at https://odla.ai/docs/packages/docs provide the rendered reference.