MDAN Markdown Action Notation
Announcement Mar 23, 2026 MDAN Team

Hello, MDAN

Introducing Markdown Action Notation, a new way to build interactive pages for both humans and agents.

One page for humans and agents.

Today we're introducing Markdown Action Notation (MDAN), a shared notation for interactive pages that stay readable and actionable for both humans and agents from the same source.

The Problem

We kept running into the same split:

  • Humans need readable, interactive interfaces.
  • Agents need structured, agent-usable surfaces.

In most stacks, serving both means building twice: once for the browser, once for agent-facing use. Or worse, building for people and asking agents to scrape the rendered result.

Our Solution

MDAN keeps the page primary through content negotiation. The same route, the same page source, different useful representations:

GET /demo HTTP/1.1
Accept: text/html
-> interactive form

GET /demo HTTP/1.1
Accept: text/markdown
-> structured markdown with execution semantics

How It Works

Write the page in Markdown with a block that declares the interaction surface:

BLOCK demo {
  INPUT text -> nickname
  INPUT text required -> message
  GET "/list" -> refresh label:"Refresh"
  POST "/post" (nickname, message) -> submit label:"Submit"
}
  • Humans get an HTML interface they can use in the browser.
  • Agents get the same page in Markdown with enough structure to continue the flow.

Key Principles

  1. Markdown native: the page starts as readable source, not as framework output.
  2. Explicit operations: reads, writes, and continuation stay close to the content.
  3. Protocol first: representations are negotiated over HTTP instead of hidden behind framework glue.
  4. Shared surface: the same page remains useful across interfaces.

What's Next

This is only the beginning. From here, the work is about making the notation easier to author, easier to host, and easier to adopt:

  • More examples and tutorials
  • Better authoring tools
  • More hosted patterns
  • A public showcase of projects using MDAN

Try It

npx mdan init my-app
cd my-app
npm install
npm start

Or open the live demo right now.

Same page. Same actions. Same experience. Star the project on GitHub, join the discussion, or build something cool and share it with us.