MDAN Markdown Action Notation
Announcement Mar 23, 2026 MDSN Team

Hello, MDSN

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

One page. Two audiences. One source that still holds when interaction begins.

Today we're introducing Markdown Shared Notation (MDSN), a way to build interactive pages that stay readable for people and continuable for agents from the same source.

The Problem

We kept running into the same split:

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

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

Our Solution

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

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

GET /guestbook 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 guestbook {
  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 MDSN

Try It

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

Or open the live demo right now.

MDSN is open source. Star the project on GitHub, join the discussion, or build something cool and share it with us.