What if one interactive page could stay usable for both humans and agents from the same source?
That is the question behind MDAN.
Most interactive systems split too early.
The page is treated as the surface for humans. The API becomes the surface for agents and software. Then more documentation is added to explain that separate contract. Over time, the readable page becomes less like the interface itself and more like a presentation layer sitting on top of the real contract.
MDAN starts from a different idea: the page should not stop mattering the moment interaction begins.
The Split We Keep Accepting
The common pattern looks something like this:
page for people
+ API for machines
+ docs to explain the API
That model is familiar, and often necessary, but it also creates a sharp divide:
- Humans continue from the page.
- Agents continue from a different surface.
- The original page loses authority.
When that happens, the readable page is no longer the place where the real interaction model lives. It becomes a human-facing shell.
Keeping the Page Primary
MDAN is an experiment in keeping the page itself more central.
With the same route and the same source:
- Humans can receive rendered UI.
- Agents and other clients can request readable Markdown.
- Both can continue from the same page model.
That does not mean every API disappears. It means the page can stay useful for longer instead of immediately splitting into separate surfaces.
A Small Example
Here is the current demo example:
---
title: "Demo"
---
# Demo
Leave a short message and refresh the block to see the latest entries.
<!-- mdan:block demo -->
For a person, that becomes a normal interactive page.
For an agent requesting Accept: text/markdown, the same page still exposes:
- the page context
- the available inputs
- the available actions
- the continuation surface
In other words, the page remains readable and actionable instead of being reduced to a rendered artifact.
Why This Matters
We think this starts to matter 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 situations, the cost of splitting too early is not just implementation overhead. It is conceptual drift. The readable page says one thing. The agent-facing system says another. The real interface moves away from the place where people actually understand the workflow.
MDAN is our attempt to reduce that gap.
What We're Exploring
The direction is not "Markdown replaces everything."
The direction is:
- keep the page primary for longer
- keep actions close to readable context
- let one source remain useful across interfaces
That is the experiment.
If that direction sounds interesting, you can explore the project here: