Kiira

Why it matters

Kiira type-checks code fences in Markdown and MDX against your real project API, closing a gap that no standard TypeScript toolchain addresses out of the box. Docs rot silently as APIs evolve, and AI agents that write or update documentation hallucinate function names, option keys, and package subpaths with total confidence. Kiira runs the same TypeScript compiler your source code uses, so an invalid import or a misspelled prop name in a README fails the check immediately, before any reader copies it.

The big picture

Three packages share one engine. The core lives in kiira-core: extraction, virtual files, type-checking, and diagnostics. The CLI package (kiira) exposes kiira check for local runs and CI. The VS Code extension (kiira-vscode) adds live squiggles inside Markdown fences as you type, and a GitHub composite action (AlemTuzlak/kiira@v1) posts error annotations directly on pull requests. All three surfaces run exactly the same check, so "passes locally" is a genuine guarantee.

How it works

Install with pnpm add -D kiira, run kiira init to scaffold a tsconfig.docs.json and an optional kiira.config.ts, then run kiira check. Kiira reads your include globs, extracts every code fence tagged ts, tsx, js, or jsx, builds virtual TypeScript files, and resolves imports against your real project packages. Errors map back to the original Markdown line number, not to any generated file. The --fix flag auto-rewrites mistagged ts fences to tsx, adds group= tags to continuation snippets, and writes per-framework jsxImportSource overrides.

Zoom in

Fence metadata gives per-snippet control. Tag a fence ignore to skip it, validate=none to silence type errors, fixture=react to prepend a named wrapper, or group=quickstart to chain multiple fences so a later snippet can reference symbols declared in an earlier one. For literate docs where almost every fence builds on the previous one, set defaultGroup: "file" in config to implicitly group all fences in a file without tagging each one individually.

Yes, but

Relative imports (./x, ../x) and unused locals are both ignored by default, because doc snippets routinely reference imaginary sibling files and declare symbols they never use. These checks are opt-in via checkRelativeImports: true and checkUnusedSymbols: true in config. Runtime validation (validate=runtime) is a metadata option, but type validation is the default and primary mode.

The bottom line

If your team uses AI agents to write or update docs, Kiira is not optional. It is the only tool that closes the loop between what an agent writes in a Markdown file and what TypeScript actually compiles. Unlike remark-validate-links, which checks URLs only, Kiira validates full TypeScript types against your real project API, catching hallucinated function names and wrong option keys before any reader runs the example. The MIT-licensed package is on npm and the VS Code extension is on the Marketplace; setup takes one kiira init.