MarkdownAI

Inline Interpolation

Embed live values directly in prose. Works in paragraphs, headings, and table cells. Use {{ env.VAR }}, {{ @query git branch --show-current }}, or {{ @date format="YYYY-MM-DD" }} anywhere in your document. Unset variables evaluate to empty string rather than an error.

Environment Variables

Declare the variables your document depends on. required causes mai validate to fail if the variable is unset. masked prevents the value from appearing in rendered output. fallback=value provides a default when the variable is absent.

Macros

Define reusable blocks once with @define and call them anywhere with @call. Macros can accept named parameters, contain any directives, and be shared across documents by importing them from a shared file.

Includes and Imports

Pull in file content with @include - supports a line range for embedding source code in docs. Use @import to import only definitions (macros, connections, env defaults) from a shared file without rendering its content.

Conditionals

Full conditional system. Check env vars, file existence, string comparisons, and compound logic with && and ||. The same expression operators work in @if conditions, data query where filters, and {{ }} interpolations.

Pipe and Render

Chain transforms before rendering: sort, grep, head, tail, uniq, wc -l. All built-in transforms are cross-platform pure Node.js. Feed the result into any of 11 output formats via @render.

@list

List filesystem entries, or pull structured data from JSON, YAML, and CSV files. Filter with glob patterns, where clauses, and depth limits. Specify columns, sort order, and output format inline.

@list ./src/ match="**/*.ts"
@list ./config.yaml path=$.services
@list ./data.csv where="status == active"

@read

Extract a specific value from a structured file using dot-notation paths. Supports JSON, YAML, TOML, and CSV. Useful for pulling a single config value, a version number, or a record field into prose.

@read ./package.json path=$.version
@read ./config.yaml path=$.server.port
@read ./data.csv column=email where="active == true"

@query

Run a shell command and use its output. Supports a label= option to store the result for reuse in conditions and interpolations. Disabled by default - requires an explicit allowlist in your security config.

@query git branch --show-current
@query bash -c "find src -name '*.ts' | wc -l"
@query bash -c "git status --porcelain" label=dirty

@http

Make HTTP requests and embed the response. Assert status codes with expected=, pass headers and bodies, and cache responses to avoid hammering external APIs. All @http calls are blocked by default until you add domains to the allowlist.

@http GET https://api.example.com/status
@http GET {{ env.API_ENDPOINT }}/health expected=200
@http GET https://api.example.com/data @cache persist ttl=3600

@db and @connect

Register a database connection with @connect, then query it using MarkdownAI's database-agnostic query language. A document querying Postgres looks identical to one querying MongoDB. Supports SQLite, PostgreSQL, MySQL, MSSQL, and MongoDB.

@connect primary type="postgres" uri=env.POSTGRES_URI
@db using="primary" find="users" where="active==true"
@db using="primary" aggregate="sales" group="region" sum="revenue" | @render type="bar"

@phase and @graph

Structure a document as a sequential workflow with named phases and @on complete transitions. The MCP server exposes list_phases, resolve_phase, and next_phase tools so AI tools can navigate the workflow programmatically. Use @graph to build a dependency graph from document relationships.

Live Preview

Open any MarkdownAI file and click the preview icon in the editor title bar, or run MarkdownAI: Open MarkdownAI Preview from the Command Palette. The panel opens to the side, runs the engine on the saved file, and shows rendered output. It refreshes automatically every time you save.

Language Detection

Any .md file whose first line is @markdownai is automatically re-tagged as the markdownai language type, activating all extension features. Files with YAML frontmatter before @markdownai are also detected.

Syntax Highlighting

TextMate grammar covers all MarkdownAI directives: @markdownai, @define, @phase, @if, @include, @import, @env, @call, @list, @read, @db, @http, @query, @render, @prompt, @constraint, @cache, and {{ }} interpolations.

Snippets and Completion

15+ tab-triggered snippets for all directives. Type @def and expand to a complete @define/@end block, @if to a full conditional, @phase to a phase skeleton. As you type @, completions show all valid directives with descriptions.

Navigation

Hover over any @define name or @call to see the macro definition inline. Press F12 on any @call name to jump to the @define that declares it, even across files linked by @import. Right-click any @define name for Find All References.

Diagnostics

The extension checks documents as you type and reports: @call to undefined macros (error), @include/@import pointing to missing files (error), @env variables without a fallback (warning, configurable), and undefined macros in @call positions (warning, configurable).