{"id":51139931,"url":"https://github.com/AlemTuzlak/kiira","last_synced_at":"2026-07-14T05:00:35.005Z","repository":{"id":362675531,"uuid":"1260200602","full_name":"AlemTuzlak/kiira","owner":"AlemTuzlak","description":"Type-check the TypeScript \u0026 JavaScript code in your Markdown against your real project — in your editor, the CLI, and CI.","archived":false,"fork":false,"pushed_at":"2026-06-15T14:50:31.000Z","size":9441,"stargazers_count":76,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T17:38:12.103Z","etag":null,"topics":["cli","developer-tools","docs-as-code","documentation","javascript","linter","markdown","monorepo","type-checking","typescript","vscode-extension"],"latest_commit_sha":null,"homepage":"https://marketplace.visualstudio.com/items?itemName=CodeForge.typedown-vscode","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlemTuzlak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.MD","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T08:48:59.000Z","updated_at":"2026-06-16T18:15:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AlemTuzlak/kiira","commit_stats":null,"previous_names":["alemtuzlak/typedown","alemtuzlak/kiira"],"tags_count":13,"template":false,"template_full_name":"code-forge-io/open-source-stack","purl":"pkg:github/AlemTuzlak/kiira","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlemTuzlak%2Fkiira","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlemTuzlak%2Fkiira/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlemTuzlak%2Fkiira/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlemTuzlak%2Fkiira/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlemTuzlak","download_url":"https://codeload.github.com/AlemTuzlak/kiira/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlemTuzlak%2Fkiira/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35446929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-14T02:00:06.603Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","developer-tools","docs-as-code","documentation","javascript","linter","markdown","monorepo","type-checking","typescript","vscode-extension"],"created_at":"2026-06-25T22:00:22.180Z","updated_at":"2026-07-14T05:00:34.999Z","avatar_url":"https://github.com/AlemTuzlak.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/AlemTuzlak/kiira/main/assets/cover-light.png\" /\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/AlemTuzlak/kiira/main/assets/cover-dark.png\" /\u003e\n  \u003cimg alt=\"Kiira — type-check the code in your Markdown\" src=\"https://raw.githubusercontent.com/AlemTuzlak/kiira/main/assets/cover-dark.png\" width=\"860\" /\u003e\n\u003c/picture\u003e\n\n# Kiira\n\n**Type-check the code in your Markdown.**\n\nKiira extracts TypeScript and JavaScript code fences from your Markdown and MDX docs,\ntype-checks them against your real project API, and reports any errors right back on the\nsource line — in your editor, on the command line, and in CI.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/kiira\"\u003e\u003cimg alt=\"npm version\" src=\"https://shieldcn.dev/npm/kiira.svg?split=true\u0026labelColor=0d0e12\u0026color=16a34a\u0026size=xs\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/kiira\"\u003e\u003cimg alt=\"npm downloads\" src=\"https://shieldcn.dev/npm/dw/kiira.svg?split=true\u0026labelColor=0d0e12\u0026color=16a34a\u0026size=xs\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://marketplace.visualstudio.com/items?itemName=CodeForge.kiira-vscode\"\u003e\u003cimg alt=\"VS Code installs\" src=\"https://shieldcn.dev/vscode/installs/CodeForge/kiira-vscode.svg?split=true\u0026labelColor=0d0e12\u0026color=16a34a\u0026size=xs\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/AlemTuzlak/kiira/stargazers\"\u003e\u003cimg alt=\"GitHub stars\" src=\"https://shieldcn.dev/github/stars/AlemTuzlak/kiira.svg?split=true\u0026labelColor=0d0e12\u0026color=16a34a\u0026size=xs\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/AlemTuzlak/kiira/actions\"\u003e\u003cimg alt=\"CI status\" src=\"https://shieldcn.dev/github/ci/AlemTuzlak/kiira.svg?split=true\u0026labelColor=0d0e12\u0026color=16a34a\u0026size=xs\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/AlemTuzlak/kiira/blob/main/LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://shieldcn.dev/github/license/AlemTuzlak/kiira.svg?split=true\u0026labelColor=0d0e12\u0026color=16a34a\u0026size=xs\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/AlemTuzlak/kiira/commits/main\"\u003e\u003cimg alt=\"Last commit\" src=\"https://shieldcn.dev/github/last-commit/AlemTuzlak/kiira.svg?split=true\u0026labelColor=0d0e12\u0026color=16a34a\u0026size=xs\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n## Documentation\n\n📚 **Full documentation lives in [`/docs`](docs)** — a browsable site covering every CLI\nfeature, configuration, CI recipes, and the VS Code extension. Run it locally with\n`pnpm install \u0026\u0026 pnpm run dev` from inside `docs/`, or deploy it (Docker / Fly.io configs are\nincluded).\n\n## Using an AI agent?\n\nKiira ships [TanStack Intent](https://www.npmjs.com/package/@tanstack/intent) skills with\nthe `kiira` package — focused guidance your coding agent loads when it works with Kiira\n(setup, authoring/debugging fences, monorepos \u0026 frameworks, CI, the VS Code extension).\nRun once in your project:\n\n```bash\nnpx @tanstack/intent@latest install\n```\n\n## Why\n\nDocs are increasingly written and updated by agents, and agents hallucinate APIs. Kiira\ncatches the things that make a copy-pasted example fail:\n\n- invalid imports and missing exports\n- wrong package subpaths\n- wrong function, option, or prop names\n- invalid TypeScript / JavaScript (with `checkJs`)\n- non-copy-pasteable examples — unless explicitly marked partial or ignored\n\n## Packages\n\n| Package                                     | Description                                            |\n| ------------------------------------------- | ------------------------------------------------------ |\n| [`kiira-core`](packages/core)           | Extraction, virtual files, type-checking, diagnostics. |\n| [`kiira`](packages/cli)             | `kiira check` for local and CI validation.          |\n| [`kiira-vscode`](packages/vscode)        | Live squiggles inside Markdown code fences.            |\n| [`AlemTuzlak/kiira@v1`](action.yml)       | GitHub composite action for CI.                        |\n\n## Quick start\n\n```bash\npnpm add -D kiira\n```\n\nCreate a `tsconfig.docs.json` and (optionally) a `kiira.config.ts`, then run:\n\n```bash\nkiira check\n```\n\n### Fence format\n\n````md\n```ts\nimport { createAgent } from \"@tanstack/ai\"\n```\n````\n\nAdd metadata to control validation:\n\n````md\n```tsx fixture=react validate=type name=basic-chat\nimport { useChat } from \"@tanstack/ai/react\"\n\nexport function Chat() {\n  const chat = useChat()\n  return \u003cdiv\u003e{chat.messages.length}\u003c/div\u003e\n}\n```\n````\n\nSupported metadata: `ignore`, `validate=type|runtime|none`, `fixture=\u003cname\u003e`, `name=\u003cid\u003e`,\n`package=workspace|packed`, `group=\u003cid\u003e` (use `group=none` to detach a fence).\n\n### Grouping snippets\n\nBy default each fence is checked as an isolated module. When a walkthrough is split across\nseveral fences (a later fence uses a `const` declared in an earlier one), tag them with the\nsame `group`:\n\n````md\n```ts group=quickstart\nconst client = createClient()\n```\n\n```ts group=quickstart\nawait client.send(\"hi\")   // resolves: same group as the snippet above\n```\n````\n\nKiira also **detects** ungrouped continuations automatically — if grouping a document's\nsnippets would resolve \"cannot find name\" errors, it warns and `kiira check --fix` adds the\n`group=` tags for you.\n\nFor **literate docs** where most fences build on earlier ones, set `defaultGroup: \"file\"` in\nyour config to implicitly group every fence in a file (in document order) without tagging any\nof them. An explicit `group=` still wins, and `group=none` detaches a fence. `defaultGroup` is\nalso settable per-glob via `overrides`.\n\n## Monorepos\n\nIn `packageMode: \"workspace\"` (the default) Kiira discovers your pnpm/npm/yarn workspace,\nmaps every package name to its source, and adds each package's `node_modules` as a resolution\nfallback. So in a monorepo, docs that import `@your-scope/*` **and** third-party libs resolve\nout of the box — no hand-written `tsconfig` `paths` required.\n\n## Per-glob overrides\n\nWhen a docs set spans multiple frameworks, a single `jsx`/`jsxImportSource` can't serve all of\nthem. Use `overrides` to set compiler options for matching files:\n\n```ts\nexport default defineConfig({\n  include: [\"docs/**/*.md\"],\n  overrides: [\n    { include: [\"**/*solid*\"], jsxImportSource: \"solid-js\" },\n    { include: [\"**/*preact*\"], jsxImportSource: \"preact\" },\n  ],\n})\n```\n\nEach override's non-`include` fields are merged onto the base compiler options for matching\nfiles (Kiira runs a separate TypeScript program per distinct option set). Kiira also\n**detects** the framework from the file path: if a file's JSX fails for lack of the right\nruntime types (TS7026), it suggests a `jsxImportSource` override and `kiira check --fix`\nwrites it into a JSON config for you.\n\n## Language-tag checking\n\nKiira warns when a `ts` fence actually contains JSX (it should be `tsx`), checks it as `tsx`\nanyway so you get real type errors instead of a syntax-error cascade, and can rewrite the tag\nfor you:\n\n```bash\nkiira check --fix    # rewrites mistagged fences (ts/typescript -\u003e tsx)\n```\n\n## CLI\n\n```bash\nkiira check                     # validate everything in your include globs\nkiira check --entry docs        # check a directory (repeatable)\nkiira check --entry docs --ignore docs/api   # ...excluding a subdirectory\nkiira check \"docs/**/*.md\"      # validate specific files/globs\nkiira check --reporter json     # machine-readable output\nkiira check --reporter github   # GitHub Actions annotations\nkiira check --fix               # rewrite mistagged code fences (ts -\u003e tsx)\nkiira check --verbose           # full messages + code frames (default is compact)\nkiira init                      # scaffold kiira.config.ts + tsconfig.docs.json\n```\n\n### Flags\n\n| Flag | Description |\n| --- | --- |\n| `--entry \u003cpath\u003e` | Directory, file, or glob to check. Repeatable. Overrides `include`. |\n| `--ignore \u003cpath\u003e` | Directory, file, or glob to exclude. Repeatable (e.g. `--ignore docs/api`). |\n| `--config \u003cpath\u003e` | Path to a Kiira config file. |\n| `--reporter \u003cname\u003e` | Output format: `pretty` (default), `json`, or `github` (Actions annotations). |\n| `--fix` | Apply auto-fixes: rewrite mistagged fences (`ts`→`tsx`), add `group=` tags, write framework `jsxImportSource` overrides. |\n| `--verbose` | Full error messages and code frames (default output is compact). |\n| `--raw` | Plain text — disable colored output. |\n| `--static` | Disable the loading spinner. |\n| `-h, --help` | Show help. |\n| `-v, --version` | Show the version. |\n\nExit codes: `0` clean, `1` validation errors, `2` config/runtime failure.\n\n### Configuration\n\n`kiira.config.ts` (or `.js`/`.json`); all fields are optional except `include`:\n\n```ts\nimport { defineConfig } from \"kiira-core\"\n\nexport default defineConfig({\n  include: [\"docs/**/*.{md,mdx}\", \"README.md\"],\n  exclude: [\"**/node_modules/**\"],\n  tsconfig: \"tsconfig.docs.json\",   // defaults to tsconfig.docs.json, then tsconfig.json\n  packageMode: \"workspace\",          // \"workspace\" (default) | \"packed\"\n  defaultValidate: \"type\",           // \"type\" (default) | \"runtime\" | \"none\"\n  checkUnusedSymbols: false,          // report TS6133 unused locals/params/imports\n  checkRelativeImports: false,        // report unresolved ./ and ../ imports\n  overrides: [\n    { include: [\"**/*solid*\"], jsxImportSource: \"solid-js\" },\n  ],\n  fixtures: {\n    react: { type: \"wrap\", before: \"import React from 'react'\", after: \"\" },\n  },\n  defaultFixture: undefined,\n  languages: [\"ts\", \"tsx\", \"js\", \"jsx\"],\n})\n```\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `include` | — | Markdown/MDX globs to check (required). `.md` and `.mdx` are both checked. |\n| `exclude` | `[]` | Globs to skip. |\n| `tsconfig` | auto | tsconfig to source compiler options from. |\n| `packageMode` | `workspace` | Resolve monorepo packages (`workspace`) or rely on installed packages (`packed`). |\n| `defaultValidate` | `type` | Default validation mode for fences without a `validate=` tag. |\n| `defaultGroup` | `none` | `file` implicitly groups every fence in a file (literate docs). |\n| `checkUnusedSymbols` | `false` | Report unused locals/params/imports (TS6133). |\n| `checkRelativeImports` | `false` | Report unresolved relative imports. |\n| `overrides` | `[]` | Per-glob `compilerOptions` (e.g. `jsxImportSource`). |\n| `fixtures` | `{}` | Named code to prepend/wrap around snippets. |\n| `defaultFixture` | — | Fixture applied to fences without a `fixture=` tag. |\n| `languages` | all | Fence languages to check. |\n\n### Fence metadata\n\nAdd tokens after the language on the fence info string:\n\n````md\n```tsx fixture=react validate=type name=basic-chat group=quickstart\n````\n\n| Token | Description |\n| --- | --- |\n| `ignore` | Skip this fence entirely. |\n| `validate=type\\|runtime\\|none` | Override the validation mode for this fence. |\n| `fixture=\u003cname\u003e` | Wrap the snippet with a named fixture from config. |\n| `name=\u003cid\u003e` | A stable label for the snippet (shown in tooling). |\n| `group=\u003cid\u003e` | Type-check fences sharing an id together, in document order. |\n| `group=none` | Detach a fence from its group (e.g. under `defaultGroup: \"file\"`). |\n| `package=workspace\\|packed` | Override the package resolution mode for this fence. |\n\nUnused locals/parameters/imports (TS6133) are **ignored by default** — doc snippets\nroutinely declare things they don't use. Set `checkUnusedSymbols: true` in your config to\nenforce them.\n\nUnresolved **relative** imports (`./x`, `../x`) are also **ignored by default** — snippets\noften \"import\" from an imaginary sibling file standing in for an earlier snippet or the\nreader's project. Bare package imports (`@scope/pkg`, `react`) are always checked. Set\n`checkRelativeImports: true` to enforce relative imports too.\n\n## Editor (VS Code)\n\nInstall **Kiira** from the\n[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=CodeForge.kiira-vscode)\n(or `ext install CodeForge.kiira-vscode`). It also publishes to\n[Open VSX](https://open-vsx.org/extension/CodeForge/kiira-vscode).\n\nIt type-checks your Markdown code fences against your real project, live:\n\n- **Live diagnostics** — type errors appear as you type (debounced) and on save,\n  mapped to the exact line inside the fence.\n- **Quick fixes** (`Ctrl+.` / `Cmd+.`):\n  - TypeScript's own fixes inside fences — **auto-import a missing symbol**, fix a\n    misspelled name, add a missing `await`, implement an interface, …\n  - Kiira's fixes — change a mistagged `` ```ts `` fence to `` ```tsx `` for JSX,\n    or tag continuation snippets with `group=…`.\n- **Inspect** the generated virtual file for any snippet.\n\n### Commands\n\n| Command | Description |\n| --- | --- |\n| `Kiira: Check Current File` | Re-check the active Markdown document. |\n| `Kiira: Check Workspace` | Check every Markdown file in the workspace. |\n| `Kiira: Open Virtual File For Snippet` | Inspect the generated code for a fence. |\n| `Kiira: Restart Kiira Server` | Clear and re-check all open documents. |\n\n### Settings\n\n| Setting | Default | Description |\n| --- | --- | --- |\n| `kiira.enable` | `true` | Enable Kiira diagnostics in Markdown files. |\n| `kiira.configPath` | `kiira.config.ts` | Path to the Kiira config, relative to the workspace root. |\n| `kiira.debounceMs` | `300` | Delay before re-checking after a change. |\n| `kiira.checkOnChange` | `true` | Re-check as the document changes (debounced). |\n| `kiira.checkOnSave` | `true` | Re-check when the document is saved. |\n| `kiira.showGeneratedDiagnostics` | `false` | Show diagnostics from generated fixture code (debugging). |\n\n## CI\n\nUse the [composite action](action.yml):\n\n```yaml\n- uses: AlemTuzlak/kiira@v1\n  with:\n    command: pnpm kiira check\n    reporter: github\n```\n\n## Examples\n\n| Example                                | Shows                                              |\n| -------------------------------------- | -------------------------------------------------- |\n| [`examples/basic`](examples/basic)     | Plain TypeScript snippets against the `node` types. |\n| [`examples/react`](examples/react)     | `tsx` snippets with `react` and wrap fixtures.      |\n| [`examples/monorepo`](examples/monorepo) | One config validating docs across many packages.  |\n\n## Development\n\nThis is a pnpm + Nx monorepo.\n\n```bash\npnpm install\npnpm build:all   # build every package\npnpm test        # check + typecheck + unit tests + build\n```\n\n## License\n\nMIT © AlemTuzlak\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlemTuzlak%2Fkiira","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAlemTuzlak%2Fkiira","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlemTuzlak%2Fkiira/lists"}