MDAN (Markdown Action Notation) is a shared notation for interactive pages that keeps the same page readable and actionable for humans and agents.
That is the shortest practical definition.
If you want the longer version, MDAN is an attempt to keep the page itself useful even after interaction begins.
In many systems, the readable page is treated as the surface for people, while the real agent-facing interface lives somewhere else as an API, schema, or secondary contract. Once that split happens, the page often stops being the real interface. It becomes a presentation layer.
MDAN explores a different direction: the page should not stop mattering the moment it needs interaction.
What MDAN Is
MDAN is:
- a page-oriented notation
- a way to describe interactive surfaces in readable source
- a way to keep content and actions close together
- a way to serve useful representations of the same page across different interfaces
In practice, that means the same route can continue to serve:
- HTML for people in the browser
- Markdown for agents and other agent-facing clients
- the same page context
- the same available actions
The goal is not to make pages less readable. The goal is to let them remain useful for longer.
What MDAN Is Not
MDAN is not:
- a replacement for every API
- a generic UI framework
- a Markdown-to-HTML theming trick
- an HTML page converted into Markdown after the fact
It is also not just "Markdown for agents."
The more important idea is that one interactive page can stay central across humans and agents from the same source.
Why It Exists
The problem behind MDAN is not that APIs are bad.
The problem is that many interactive systems split too early:
page for people
+ API for machines
+ extra docs to explain the API
That model is familiar, and often necessary, but it also introduces drift:
- people understand the workflow from the page
- machines continue from a different surface
- the real contract moves away from the place where humans understand the system
MDAN exists to reduce that gap.
A Small Example
Here is a minimal demo page:
---
title: "Demo"
---
# Demo
Leave a short message and refresh the block to see the latest entries.
<!-- mdan:block demo -->
For a person, that can become a normal interactive page.
For an agent requesting Accept: text/markdown, the same page can still expose:
- what the page is for
- which block is active
- which inputs are available
- which actions can be continued
The page stays readable, but it also stays operational.
Where It Fits
MDAN starts to make sense when you are building things like:
- interactive docs
- internal tools
- CLI and web hybrids
- agent workflows
- products where humans and agents both need to continue from the same working surface
In those cases, keeping one page source useful across interfaces can be more valuable than splitting into separate surfaces immediately.
The Core Idea
If you only remember one thing, it should be this:
One page for humans and agents. Same page. Same actions. Same experience.
That is the experiment.
Related Reading
If you want the clearest comparison with backend API-first thinking, read MDAN vs REST APIs.
If you want to explore it further: