Markdown is 20 years old. It was never meant for AI. Until now.
MarkdownAI adds one line to the top of any .md file and makes it live.
MarkdownAI Directives
All directives available in MarkdownAI, organized by category.
Document Structure
| Directive | Purpose |
|---|---|
| u/markdownai | Document header - activates the MarkdownAI runtime |
| u/include | Inline file content at the directive site |
| u/import | Import definitions (macros, connections) without rendering content |
| u/define / u/end | Declare a named macro |
| u/call | Invoke a macro |
| u/phase / u/end | Declare a workflow phase |
| u/if / u/end | Conditional block |
| u/section | Named section boundary |
| u/chunk-boundary | Explicit chunk split point for rendering |
Variables & Environment
| Directive | Purpose |
|---|---|
| u/env | Resolve an environment variable |
Data Sources
| Directive | Purpose |
|---|---|
| u/connect | Register a named data source connection |
| u/db | Execute a database query |
| u/http | Fetch from an HTTP endpoint |
| u/query | Query a registered data source |
| u/read | Read raw file content |
| u/list | List directory contents |
| u/tree | Directory tree output |
| u/date | Current date/time |
| u/count | Count items in a source |
Processing & Output
| Directive | Purpose |
|---|---|
| u/pipe | Chain output through transformations |
| u/render | Render output in a specific format |
| u/graph | Generate a visualization |
| u/header | Document-level metadata header |
Annotations & Constraints
| Directive | Purpose |
|---|---|
| u/constraint | Machine-readable rule or constraint |
| u/define-concept | Vocabulary alignment - bind a term to a precise definition |
| u/prompt | Embedded instruction for the AI reading the document |
| u/note | Human-readable annotation (not rendered in AI format) |
Caching
| Directive | Purpose |
|---|---|
| u/cache | Cache directive output (option on data source directives) |
Phase Events
| Directive | Purpose |
|---|---|
u/on complete -> |
Declare what executes when a phase finishes (only valid inside u/phase blocks) |
What is MarkdownAI? There seems to be a lot of confusion.
Most people assume MarkdownAI works like this:
Claude reads a rendered MarkdownAI file and acts on it.
That's not what happens.
Yes, MarkdownAI can parse and render a .md file into a result - and that's perfectly useful if you're using it as a CLI tool. But that's not why it's called MarkdownAI.
The reason it's called MarkdownAI - and where the real power comes from - is the MCP server, the hooks, and the phase design.
Here's what actually happens:
Claude requests a .md file. The MarkdownAI MCP server intercepts that request. Instead of dumping the whole rendered file into context, it reads the document, identifies the current phase, and hands Claude only what it needs for that phase - exactly like a human would prompt it.
Claude never sees the whole document. It only gets the current phase plus its constraints. This means Claude is always aligned - it only knows what it should know, and it's always working within the boundaries defined for that phase.
This means:
- Massive token savings - Claude isn't processing 890 pages of documentation on every request
- No stale context - each phase is executed fresh with live data
- No hallucination about what exists - the runtime tells Claude exactly what's there
- Always aligned - constraints are delivered with every phase, not assumed
The power isn't the markdown format. The power is the MCP server turning a document into a live, phase-aware, always-aligned conversation between Claude and your codebase.
That's MarkdownAI.
GitHub: https://github.com/TheDecipherist/markdownai