What Is a Markdown Twin?
A Markdown twin is the agent-readable sibling of an HTML page.
It lives at the same URL, just with .md appended.
Example:
- Human URL: https://www.getmasset.com/software
- Markdown twin: https://www.getmasset.com/software.md
The human page has design, animation, navigation chrome, cookie banners, hero images, and roughly 200KB of JavaScript.
The twin has:
- A frontmatter block (structured metadata for AI tools).
- A clean H1.
- Short, scannable sections.
- Links written out as plain Markdown.
- Zero visual noise.
Open the URL right now in your browser. You'll see the raw Markdown. That's not a bug. That's the entire point.
Why This Matters: The AI Search Shift Nobody Is Talking About Loudly Enough
Here's where it gets real for marketers.
In 2026, your buyers are asking AI to do the research for them.
They type something like, "What does Masset do? Compare it to Bynder." (That exact question is why we wrote our own Masset vs. Bynder page.)
ChatGPT, Claude, Perplexity, Google AI Overviews, Gemini, Copilot. They all do the same thing. They read websites, extract claims, summarize, and report back.
And here's the problem:
Most websites are written for humans, not machines.
When an AI agent reads your homepage, it has to fight through:
- React or Next.js client-side rendering.
- Cookie consent banners.
- Marketing tracking scripts.
- Hero animations.
- Carousels and accordions.
- Lazy-loaded images.
- Sticky nav bars.
- CSS that hides text until JavaScript runs.
By the time the AI extracts your actual message, the signal is degraded.
It guesses. It hallucinates. It picks up your competitor's positioning instead of yours.
We call this story drift.
Story drift is what happens when your brand narrative passes through too many systems before it reaches the buyer. The original story gets fuzzy. The version that lands in front of your prospect is almost-right. And almost-right is worse than wrong, because almost-right travels.
“Almost-right is worse than wrong, because almost-right travels.”
The Cost of Story Drift (Real Story, Real Stakes)
We've watched this happen with real customers.
A VP of Marketing asks ChatGPT, "Compare Masset to Seismic." ChatGPT pulls in old positioning from a third-party blog. Masset gets miscategorized as a generic DAM. The buyer walks into the next sales meeting with a half-true version of our story already in their head. The fix is to own that comparison ourselves, which is why we publish Masset vs. Seismic directly.
Multiply that by 100 buyers.
Multiply that by 10 competitors all doing the same.
That's not a marketing problem you can solve with more content. It's a foundation problem.
You don't need more content. You need AI-readable content.
The Markdown Twin Pattern (Our 4-Step System)
Here's the exact system we rolled out across getmasset.com.
You can copy it on any modern stack.
Step 1: Add a .md Twin at the Same URL
For every public page, create a Markdown version at the same path plus .md.
This is the core move.
| Human page | Markdown twin |
|---|---|
/software | /software.md |
/training | /training.md |
/compare/masset-vs-seismic | /compare/masset-vs-seismic.md |
/resources/blog/what-is-story-drift | /resources/blog/what-is-story-drift.md |
Step 2: Strip the HTML Chrome
The hardest part is not technical. It's editorial.
When you write a Markdown twin, you have to look at every section of your page and ask, "Is this actually part of my message, or just the wrapper?"
Strip out:
- Navigation menus.
- Cookie banners.
- Carousels and tab UIs (just list the content linearly).
- Hero image descriptions like, "A circular orange icon next to a chart."
- Animation labels.
- Repeated CTAs (one is enough).
Keep:
- Your H1, written as the actual claim.
- Your headline subhead.
- The substantive paragraphs.
- Real lists of features, benefits, or proof points.
- Links to other pages.
- Frontmatter with title, canonical URL, audience, last updated.
When you strip the chrome, a strange thing happens. A few of our pages got sharper just from doing this exercise. If a section couldn't survive being written as plain Markdown, that was a signal it wasn't pulling its weight on the HTML page either.
Step 3: Wire Up 3 Discovery Signals
This is where most teams stop short.
If you only ship the .md file and don't tell AI agents it exists, you're betting on them randomly guessing the URL pattern. Most won't.
You need three signals.
Signal 1: HTML head, with a rel="alternate" link tag.
<link rel="alternate" type="text/markdown" href="/software.md" title="Markdown version for AI agents" />In Next.js metadata, this is one block:
alternates: {
canonical: "https://www.getmasset.com/software",
types: {
"text/markdown": [
{ title: "Markdown version for AI agents", url: "https://www.getmasset.com/software.md" }
]
}
}Signal 2: HTTP Link header.
Link: </software.md>; rel="alternate"; type="text/markdown"; title="Markdown version for AI agents"Add this in middleware so it covers every page automatically. We did this in one file. It applies to all 500+ pages without per-page configuration.
Signal 3: An entry in llms.txt.
Your site already has (or should have) an /llms.txt file. This is the AI-era equivalent of robots.txt plus a sitemap. List every Markdown twin URL there.
We grouped ours by category: top-level pages, product features, roles, comparisons, legal. The blog and podcast slug twins are listed alongside their HTML siblings.
Why three signals? Because different AI clients use different discovery methods. Some follow the HTTP Link header. Some scan the HTML head. Some read llms.txt. Cover all three and you cover the field.
Bonus signal: Accept-based content negotiation.
If an AI agent sends Accept: text/markdown to the HTML URL, rewrite the request to the .md URL. The agent doesn't even need to know about the .md pattern. It just asks for Markdown, and your server hands it over.
Step 4: Test It
Three quick checks:
# 1. Direct request to the .md URL
curl -i https://www.getmasset.com/software.md
# Expect: 200, content-type: text/markdown
# 2. Accept: text/markdown on the HTML URL
curl -i -H "Accept: text/markdown" https://www.getmasset.com/software
# Expect: 200, content-type: text/markdown (rewritten by middleware)
# 3. Link header on the HTML URL
curl -I https://www.getmasset.com/software
# Expect: Link: </software.md>; rel="alternate"; type="text/markdown"If all three pass, you're done.
Our Rollout: 517 Pages in One Afternoon
We didn't roll this out gradually. We did it as a single push, because a half-rolled-out state would have been more confusing than fully-on or fully-off.
The breakdown:
- 26 one-off static pages. Homepage, /training, /activation, /our-story, /demo, the legal suite, /resources hubs, the MCP guide, the story-drift tool, the DAM and sales-enablement buyer's guides. Each one hand-crafted from the live page plus our internal brain.
- 10 product feature pages. All driven by the same data file that powers the HTML version. One generator function, 10 outputs.
- 9 role pages. Same approach. One generator, nine outputs.
- 17 competitor comparison pages. A short positioning record per competitor, run through a single comparison template.
- 56 blog posts. Generated from our blog data file, with a small HTML-to-Markdown utility for the body content.
- 425 published podcast episodes. Generated from the episode data file with frontmatter capturing guest, duration, key takeaways, topics, and quotes.
The infrastructure under it is genuinely small:
- One shared library file (
markdown-shared.ts) with the frontmatter helper, the route registry, and the alternates metadata helper. - One middleware file handling Accept-based content negotiation and Link header injection.
- Five generator files (one per content type) plus a 60-line HTML-to-Markdown utility for the blog body.
Total time from "what if we did this" to shipping: one focused afternoon.
Why This Is the Cheapest, Highest-Leverage Marketing Move of 2026
Most marketing teams are reacting to AI search by writing more content.
That's the wrong play.
Your problem isn't that there's not enough of your story. Your problem is that the AI tools reading your existing story are guessing.
You don't need more content. You need to make your existing content readable by the systems that summarize it for your buyers. And when you do create new content, the format matters: AI search overwhelmingly cites list-format pages, so the rules for writing a listicle AI will actually cite are worth knowing before you publish anything new.
Markdown twins are the cheapest, fastest, highest-leverage way to do that.
You can ship the first version in a single afternoon. You don't need new content. You don't need a redesign. You don't need a vendor.
You just need to ask: "If an AI agent showed up to read my homepage right now, what would it find?"
Then make sure the answer is the version of your story you actually want told.
“You don't need more content. You need to make your existing content readable by the systems that summarize it for your buyers.”
Next Steps
Three things you can do in the next 30 minutes:
- Open
https://www.yourdomain.com/llms.txt. If you get a 404, that's your starting point. Ship a basicllms.txtfile. (Anthropic, OpenAI, Perplexity, and most AI crawlers respect it.) - Visit
https://www.yourdomain.com/index.md(or any other page plus.md). If you get a 404, that's the next move. Pick your top 5 pages by traffic and add Markdown twins. - Ask your favorite AI tool, "What does [your company] do?" Compare the answer to the version of the story you actually want told. The gap is the cost of not having Markdown twins.
The full architecture is documented internally so any team in our space can copy it. If you want to see what good looks like in production, try this:
- Designed: getmasset.com/software
- Markdown twin: getmasset.com/software.md
Same content. Different audience. One built for humans. One built for the systems your buyers are quietly trusting.
Once your pages are readable, the next layer is making them actionable for agents: the WebMCP standard for AI-ready websites lets an AI agent run real actions on your site, not just read it. And if you want the other side of the tooling story, here's OpenAI's Codex and what marketers should know about it.
The future of search isn't more content. It's making your existing content readable by the right reader.
Key Takeaways
- A Markdown twin is the agent-readable sibling of an HTML page. Same URL plus .md, same content, no visual chrome — just frontmatter, headings, paragraphs, and links written for AI tools to retrieve and summarize accurately.
- Story drift is the real cost of not having Markdown twins. When AI tools fight through your HTML and CSS to extract your story, they guess. The almost-right version that lands in your buyer's AI summary is worse than wrong, because it travels.
- The pattern is four steps: add a .md twin at the same URL, strip the HTML chrome, wire up three discovery signals (HTML link tag, HTTP Link header, llms.txt entry), and test with curl. Bonus: rewrite Accept: text/markdown requests to the .md URL.
- The infrastructure is genuinely small. One library file, one middleware file, one generator per content type. Most teams can ship a basic version in a single afternoon — no new content, no redesign, no vendor.
- This is the cheapest, highest-leverage AI search move available in 2026. You don't need more content. You need to make your existing content readable by the systems that summarize it for your buyers.
