oku

oku Renders Markdown pages in the browser. Single-source content, no build step for authoring, multi-page site with full-text search when you want one. What the kit is, how it's organised, where the documentation lives. Documentation kit · oku > [!TLDR] > Pages are Markdown. The browser renders them via Custom Elements; no build step needed to read. Run oku build to emit a multi-page site (with Pagefind search) or a standalone single file for offline reading. > > - Source: .md — GitHub-flavored markdown, minus a short list of constructs the kit's linter rejects. Page-JSON sources predate the format and keep rendering. > - Runtime: chrome.js + renderer.js load from a _oku symlink. No copies, no version drift. > - Primitives: callout, kpi-grid, table, compare-grid, step-flow, chart, diagram, live-snippet, annotated-code, glossary tooltips, citation cards. > - Output: dist/site/ (multi-page + Pagefind) and dist/standalone/ (single file with inline page JSON for email / archive). ## Documentation {#docs} Nine pages beside this one. Cards link straight to each — Reference covers core primitives; Charts / Tables / Diagrams break out the heavy ones; Glossary / Architecture / CLI / Format comparison go deeper. ## What a page looks like {#shape} Markdown is what an author types; HTML is what ships. Page-JSON is the second format the walkers still accept — it predates the markdown source and keeps rendering. Code on the left, the actual rendered output on the right. ### JSON source {#shape-json} Hand-authored or AI-emitted. Every block declares its kind explicitly; nothing has to be guessed. Validated against the kit schema before it ships. ### Markdown source {#shape-md} Drop existing .md files into the docs root. ATX headings, code fences (mermaid included), lists, tables, blockquotes, inline formatting all convert. Relative .md links retarget to .html. README / CHANGELOG and friends are surfaced as pages too. The subset is strict, and `oku check` names each thing outside it. A setext (`===` underline) heading is an error. A four-space-indented block after a blank line, a blockquote line continued without its `>`, and a `---` sitting directly under a text line are warnings — each is a construct CommonMark and the kit read differently, so the linter asks you to disambiguate rather than guessing. ## Quickstart {#quickstart} Two commands. Adopt the kit for an existing docs/ directory without rewriting anything. ```bash cd path/to/your-project/docs oku init # creates _oku symlink + index.html oku serve # http://localhost:9876 with live reload ``` After `init`, any `.md` or `.json` file in the docs tree is a page. The sidebar lists them; the on-page TOC builds from H2 / H3; full-text search builds with `oku build` when pagefind is available — install it with the `oku[search]` extra, or have `pagefind` on PATH.