MDSN is a shared notation for interactive pages that stay readable, actionable, and continuable from the same source.
That is the shortest practical definition.
If you want the longer version, MDSN 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 machine-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.
MDSN explores a different direction: the page should not stop mattering the moment it needs interaction.
What MDSN Is
MDSN 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 machine-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 MDSN Is Not
MDSN 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 MDSN 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
MDSN exists to reduce that gap.
A Small Example
Here is a minimal guestbook page:
---
title: "Guestbook"
---
# Guestbook
Leave a short message and refresh the block to see the latest entries.
<!-- mdsn:block guestbook -->
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
MDSN starts to make sense when you are building things like:
- interactive docs
- internal tools
- CLI and web hybrids
- agent workflows
- products where humans and machine-facing clients 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:
MDSN is a way to keep one interactive page useful for both humans and agents from the same source.
That is the experiment.
If you want to explore it further: