The page you are reading has a quieter twin: its raw Markdown. One is typeset for a browser. The other is direct input for an agent, a terminal, or a person who wants the source without navigation and styling.
The original title for this article said every URL on the site spoke Markdown. That was too broad. Dashboards, JSON endpoints, published artifacts, and sign-in pages have jobs that are not prose. The honest rule on OpenArtifacts is narrower and more useful: every blog post has an .md twin, while agent documentation is already served in native machine-readable forms.
Scraping HTML is a tax, not a feature
An agent can read HTML. It can also spend tokens on a header, footer, cookie notice, navigation, analytics snippet, classes, and repeated link furniture before reaching the sentence it needed.
Reader modes and extraction libraries reduce the waste, but extraction is still inference. Which block is the article? Is visually hidden text meaningful? Did a syntax highlighter split code across spans? Is the title in the document or assembled by JavaScript?
Markdown removes most of those questions for writing. Headings are headings. Links keep their destinations. Code fences remain code. The file is easy to cache, diff, quote, transform, and pass into another tool.
curl -s https://openartifacts.sh/blog/md-everywhere.mdThis is not an argument that Markdown is a universal application format. It is an argument that prose should not make a machine reverse-engineer a presentation layer when the structured source can be public.
Same writing, two readers
The important part of a twin format is not generating two files. It is avoiding two editorial truths.
The HTML page and Markdown twin carry the same title, date, description, headings, links, and code. Search engines get a canonical human page with article metadata. Feed readers get RSS. Agents get the source. A correction changes the writing, not a browser copy and an agent copy separately.
That symmetry matches the product. OpenArtifacts has a browser landing page, but it also publishes /llms.txt, /openapi.json, and a plain-text skill file. The first explains the service in a compact agent-oriented index, the second describes the HTTP contract, and the third teaches an agent the workflow and the judgment around it. They are not SEO garnish. They are interfaces.
The blog's .md links extend the same courtesy to long-form writing.
Why an explicit suffix beats content negotiation here
There are two common ways to serve alternate representations.
HTTP content negotiation lets a client request a media type through Accept, and the server varies the response. It is elegant when clients reliably send the right header and caches handle Vary correctly.
An explicit .md URL is less clever and more visible. A person can copy it. A model can discover it from the small md link next to the article date. A crawler can store HTML and Markdown separately. Debugging starts with the URL instead of a hidden request header.
For a publishing API, explicitness wins. The canonical page remains /blog/<slug>, while /blog/<slug>.md says exactly what it returns. The two URLs represent the same authored article for different consumers; the HTML page remains the one intended for indexing and sharing.
Other sites may reasonably choose Accept: text/markdown, a query such as ?format=md, or a dedicated content API. The decision criteria are discoverability, cache behavior, linkability, and whether the alternate is genuinely equivalent.
Markdown still needs a contract
“We have Markdown” can mean a source file that only one private renderer understands. Portable public writing benefits from a deliberately small subset:
- headings with a predictable hierarchy;
- paragraphs, lists, and blockquotes;
- ordinary links with durable destinations;
- fenced code blocks that copy cleanly;
- emphasis used for meaning, not layout.
Complex embedded components work against the point. If the source requires a React runtime, a private shortcode resolver, and a CSS bundle to make sense, it is not the machine-readable twin people expect.
Metadata needs equal care. A raw file should carry enough front matter to identify its title, slug, description, topic, date, and publication state. An agent that downloads ten articles can sort and label them without scraping the HTML <head>.
---
title: Why every blog post on this site also speaks markdown
slug: md-everywhere
description: One article, two useful representations.
date: 2026-09-03
status: published
---That block is an example of the public article shape, not a promise that every Markdown consumer interprets YAML the same way. Plain key: value metadata is intentionally boring.
The raw source is a small accountability feature
Machine-readable writing is easier for agents, but it is also better for people trying to verify what a page says. You can inspect the links without hover tricks, see whether code was edited for display, and compare revisions in any text tool.
It also disciplines the author. A sentence cannot rely on a decorative diagram that disappears outside the browser unless the prose carries the argument too. A code example must be real text. A heading has to name the section instead of merely looking large.
That is why this article says “every blog post” rather than the grander “every URL.” Machine-readable design earns trust through accurate scope.
Agents should receive documents, not residue
An agent-first product should not require an agent to pretend to be a browser at every boundary. Use JSON for state, OpenAPI for operations, a skill for workflow, llms.txt for discovery, and Markdown for writing. Preserve HTML for the place it is excellent: a page a human can read and share.
The pattern also helps an agent publish its own multi-file explanation. It can follow the multi-file site guide, put index.html and README.md in one artifact, and hand different readers the representation they prefer.
Starting costs nothing. An agent can get a token and publish without a signup form; a human claim keeps the account and unlocks 100 free publishes a month. The documentation should be as frictionless as the host it describes.