[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81413":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":13,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":16,"fork":16,"defaultBranch":17,"hasWiki":16,"hasPages":16,"topics":18,"createdAt":9,"pushedAt":9,"updatedAt":19,"readmeContent":20,"aiSummary":21,"trendingCount":14,"starSnapshotCount":14,"syncStatus":22,"lastSyncTime":23,"discoverSource":24},81413,"markdownai","TheDecipherist\u002Fmarkdownai","TheDecipherist","MarkdownAI - live documents powered by directives",null,"TypeScript",36,5,1,0,2.33,false,"main",[],"2026-06-12 02:04:15","\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002FmarkdownAI_hero.webp\" alt=\"MarkdownAI - Documentation That Cannot Lie\" width=\"100%\" \u002F>\n\u003C\u002Fp>\n\n# MarkdownAI\n\n> **documentation that cannot lie.**\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fversion-2.0.0-0891b2)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@markdownai\u002Fcore)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![Node.js >=18](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D18-brightgreen)](https:\u002F\u002Fnodejs.org)\n\n---\n\n## What is MarkdownAI\n\nA Markdown superset for AI-assisted workflows. Documents mix prose with executable directives - data sources, control flow, file ops, test runs, DB queries - and the engine renders directives at read time so docs stay synced with the underlying project. Originally built for the MDD (Manual-Driven Development) workflow, but the grammar and runtime are generic enough for any agentic-coding pipeline.\n\n---\n\n## The directive grammar in one snapshot\n\n```\n# 1. Self-closing (atomic, no body, no continuation)\n@import ~\u002Fpath\u002Fto\u002Fmacros.md \u002F\n@touch path=\"src\u002Ffoo.ts\" \u002F\n@on-complete next-phase \u002F\n\n# 2. Block with attributes (no body)\n@db\n  using=\"mdd\"\n  find=\"features\"\n  where='id == \"X\"'\n  label=feature\n@db-end\n\n# 3. Block with attributes + body\n@phase 0_branch_check\n  required=true\n>\n  @call branch-guard \u002F\n  @on-complete 0_5_repo_version_check \u002F\n@phase-end\n```\n\nFamiliar to anyone who's written HTML \u002F JSX \u002F Vue \u002F Svelte \u002F Astro - `@` instead of `\u003C` so directives don't conflict with embedded HTML in markdown.\n\n---\n\n## What's new in v2\n\n### Unified directive grammar\n\nEvery directive uses the three forms above. The v1 split between \"block\" directives (closed with bare `@end`) and \"inline\" directives (single-line only, silently dropped continuations) is gone. The close tag carries the directive name, so nested blocks read clearly:\n\n```\n@phase X\n  @if {{ ready }}\n    @foreach f in {{ files }}\n      - {{ f }}\n    @foreach-end\n  @if-end\n@phase-end\n```\n\nBare `@end`, `@endif`, `@endswitch`, and `@on complete -> X` are no longer accepted. The migration tool rewrites existing v1 files mechanically.\n\n### Synchronous MongoDB queries\n\n`@db using=\"...\"` actually hits Atlas or self-hosted Mongo now. In v1 the directive was stubbed and emitted an \"async execution required\" warning. v2 runs read-only queries through a sync worker so the result is available in the same render pass.\n\n### Struct labels\n\n`@db ... as=row label=feature` captures the row into `ctx.data[label]`, so `{{ feature.source_files }}` dot-access works on real arrays and nested objects. Same shape works for `@read` and any directive that materializes data.\n\n### New sandbox builtins\n\n`parse_brief`, `read_section`, `extract_paths`, `now_iso`, `to_json`, `truncate`, `parse_iso_ms`, `uuid_v4`, `allowed`. Available inside `@if` conditions and `{{ }}` interpolations alike.\n\n### Cross-call closure for skill flows\n\nA `skill_session_id` keys per-(session x document) state inside the MCP server. `@set` values persist across `resolve_phase` calls in multi-phase flows, so a skill can collect values in phase 1 and read them back in phase 5 without round-tripping through the host.\n\n### Plugin loader and `@markdownai-detect`\n\nFramework descriptors (`mdd.plugin.md`, others) declare project layout at render time. Documents pull layout facts from the descriptor instead of guessing - no more layout-inference hallucinations when the AI hasn't seen the project before.\n\n### Reusable partials with bound data\n\n`@template .\u002Frow.md data=\u003Cexpression> \u002F` inlines another MarkdownAI document at the call site and binds it to a data context, like a partial in Angular or Vue. `@data \u003Cname> ... @data-end` composes a single object from any in-scope values (db results, set variables, env fallbacks) using `\u003Ckey> = \u003Cexpression>` assignments, dot-notation for nested keys, and `...\u003Cexpression>` spreads. Inside the partial, the bound value is accessible as `{{ data.* }}` (or `{{ \u003Cname>.* }}` via `as=\u003Cname>`). Reads inherit from the caller's scope; writes stay local, so the same partial can be called repeatedly inside `@foreach` without name collisions.\n\n### `@touch` directive\n\nIdempotent empty-file creation for scaffolding. Safe to re-run.\n\n### Interpolation in file ops\n\n`@touch`, `@update-frontmatter`, `@render-template`, `@check`, and `@test` all expand `{{ }}` correctly in paths, commands, and arguments. v1 only honoured interpolation in a subset of attributes.\n\n### Test runners on the default allowlist\n\n`npx vitest`, `npx playwright`, `pnpm test`, `tsc`, and other common test commands work in `@check` and `@test` blocks without manual `~\u002F.markdownai\u002Fsecurity.json` edits.\n\n---\n\n## Package layout\n\n| Package | What it does | Path |\n|---|---|---|\n| `@markdownai\u002Fparser` | directive grammar + AST | [packages\u002Fparser](packages\u002Fparser\u002FREADME.md) |\n| `@markdownai\u002Fengine` | executes directives, renders documents | [packages\u002Fengine](packages\u002Fengine\u002FREADME.md) |\n| `@markdownai\u002Frenderer` | source-output formatters (table\u002Flist\u002Frow\u002Fjson\u002F...) | [packages\u002Frenderer](packages\u002Frenderer\u002FREADME.md) |\n| `@markdownai\u002Fmcp` | Model Context Protocol server (11 tools) | [packages\u002Fmcp](packages\u002Fmcp\u002FREADME.md) |\n| `@markdownai\u002Fcore` | `mai` CLI | [packages\u002Fcore](packages\u002Fcore\u002FREADME.md) |\n\nA VS Code extension (`markdownai` on the marketplace) provides syntax highlighting, snippets, and diagnostics for `.md` files that start with `@markdownai`.\n\n---\n\n## Quickstart\n\nInstall the CLI globally:\n\n```bash\nnpm install -g @markdownai\u002Fcore\n```\n\nCreate a small doc - `hello.md`:\n\n```\n@markdownai v2.0\n\n# Project status\n\nDatabase has @count using=\"local\" find=\"users\" \u002F users right now.\n\n@if {{ env.NODE_ENV == \"production\" }}\n  Running in production mode.\n@if-end\n```\n\nRender it:\n\n```bash\nmai render hello.md\n```\n\nThe same file renders through the MCP server when AI assistants use the `mcp__markdownai__render` tool - the document arrives with directives already resolved, no extra round-trips needed.\n\n---\n\n## Migration from v1\n\nv2 is a breaking syntax change. Pin to `^2.0.0` (v1 stays on `^1.x` and keeps working). Run the migration tool once over each v1 file:\n\n```bash\nnode ~\u002Fprojects\u002Fmarkdownai\u002Fpackages\u002Fparser\u002Fscripts\u002Fmigrate-v1-to-v2.mjs \u003Cfile> --in-place\n```\n\nThe script is idempotent - re-running on a v2 file is a no-op. Full grammar spec is in [`MDs\u002Fmarkdownai-spec-v2.0.md`](MDs\u002Fmarkdownai-spec-v2.0.md).\n\n---\n\n## Security model\n\nThe engine enforces shell, HTTP, DB, and filesystem allowlists at `~\u002F.markdownai\u002Fsecurity.json`. Defaults are restrictive: shell starts with read-only commands plus common test runners; HTTP is off; DB is off. Users opt in to broader access by editing the config. See the engine README for the full policy.\n\n---\n\n## Status\n\nv2.0.0. Currently in use for MDD v2.\n\n## License\n\nMIT.\n","MarkdownAI 是一个支持AI辅助工作流程的Markdown超集，允许在文档中混合使用叙述文本和可执行指令。其核心功能包括数据源接入、控制流管理、文件操作、测试运行及数据库查询等，并且这些指令会在读取时由引擎实时渲染，确保文档与底层项目保持同步。技术上，MarkdownAI采用了TypeScript编写，兼容Node.js 18及以上版本，通过类似于HTML\u002FJSX的语法结构（以`@`开头）来定义指令，易于理解和使用。此工具非常适合需要频繁更新并与实际开发紧密关联的技术文档编写场景，如采用手动驱动开发模式的团队，或是任何希望实现自动化代码生成与维护的工作流程。",2,"2026-06-11 04:04:56","CREATED_QUERY"]