Why Markdown is the New Gold

What happens to your notes when the app you wrote them in changes its mind?

I used to keep my notes in Microsoft OneNote, and I liked its canvas design: you can drop text anywhere on the page. What I didn’t like was the vendor login between me and my own writing. I tried Notion and Evernote as well. I ended up in Obsidian, and what I like about it is the format underneath. Every note is a plain Markdown file in a folder, with a syntax that stays out of the way and no account standing between me and the text.

That choice is also a bet on the one format that people, software and now AI agents all read the same way.

What makes gold, gold

Two properties make gold valuable. It doesn’t corrode, so a coin minted two thousand years ago is still a coin. And it’s accepted everywhere, so its worth doesn’t depend on who issued it.

Markdown has the same two properties. It doesn’t corrode: a file written in 2004 opens today in any text editor on any operating system, with nothing to convert. And it’s accepted everywhere: note apps, code hosts, static site generators, Windows Notepad and, most recently, language models all treat it as a native format. It isn’t scarce, which is where the metaphor stops: Markdown is free and open, and that helps it last.

A format for reading, not rendering

John Gruber released Markdown in March 2004, with Aaron Swartz as his sounding board. Swartz had built a similar lightweight syntax, atx, two years earlier. Gruber’s stated goal was modest and specific: make the formatting syntax “as readable as possible.”

That goal sets Markdown apart from almost every document format before it. HTML, Word files and the rest are built to be rendered: the raw file is an implementation detail, and you’re not expected to read it. Markdown is built so that the raw file already is the document. A heading looks like a heading because it starts with #. A list looks like a list because it’s a list of lines starting with -. Emphasis is marked the way people marked it in plain email for decades.

Because the source is readable without any software, no piece of software can take it away from you. Most of what follows comes from that one decision.

Twenty years without corrosion

Markdown’s history isn’t perfectly smooth. Gruber’s original description left edge cases open, and for a decade different tools filled those gaps in different ways. A group including John MacFarlane (the author of Pandoc) and Jeff Atwood spent two years writing an unambiguous specification. They announced it in September 2014 as “Standard Markdown”; Gruber objected to the name, and within days the project became CommonMark. GitHub published its own superset, GitHub Flavored Markdown, in 2017, adding tables, task lists and strikethrough on top of CommonMark. The IETF registered text/markdown as an official media type in 2016.

The arguments were about how to parse edge cases, and the core stayed put. A heading, a list, a link and a code block have meant the same thing since 2004. Meanwhile the format kept spreading: in 2025 Microsoft added Markdown formatting to Windows Notepad, one of the most conservative text editors in existence.

This site is an example too. Every article here, including this one, is a Markdown file that Hugo turns into a web page with Goldmark, a CommonMark-compliant renderer. The name is a coincidence, but a fitting one.

File over app

Obsidian’s documentation says notes are stored as “Markdown-formatted plain text files in a vault,” and a vault is just a folder on your disk. Steph Ango, Obsidian’s CEO, put the philosophy in a 2023 essay called File over app: “If you want your writing readable in 2160, it must work on computers from 1960.”

In daily practice, “no vendor login” means very ordinary things:

• Any editor works. The same note opens in Obsidian, VS Code, a terminal or a phone’s text editor. If one tool disappears, the notes don’t.
• Sync and backup are yours to choose. A folder can go into iCloud, Syncthing, a NAS or a Git repository. Git also gives you a complete history of every change, for free.
• Search is universal. grep and every desktop search index can read plain text. You’re never limited to the search box of one app.
• Moving is trivial. Changing tools means pointing a new app at the same folder. There is nothing to export, because nothing was ever locked in.

What you give up is real. OneNote’s canvas lets you place things anywhere; Markdown is linear text. Some layout freedom is the price of a file that will outlive every app that opens it, and for me that trade is worth it.

Why agents speak Markdown

The part of this story that has changed fastest is the newest reader of your files: AI models and the agents built on them.

Markdown is already how a large share of technical writing is published: READMEs, documentation and forum answers. More importantly, it’s efficient for models to read. A model pays for its input in tokens, and every tag, attribute and wrapper in a richer format costs tokens without adding meaning.

Take one small note: a twenty-line homelab backup plan with a heading, a checklist, two commands, a table and a link. Written in five formats and counted with the tokenizer OpenAI uses for GPT-4o, the words alone come to 125 tokens. Markdown needs 149 in total. The same note as Word’s internal XML needs 1,688.

Gold is graded in karats, where 24 means pure. Grade a format the same way, by the share of its tokens that are the words themselves, and Markdown comes out at 20 karat. Word’s XML comes out below 2.

It’s one sample, and other tokenizers count differently, but the direction matches a much larger real-world test. When Cloudflare launched Markdown for Agents in February 2026, it measured one of its own blog posts: 16,180 tokens as HTML and 3,150 as Markdown, an 80 percent reduction. Its service now converts pages on the fly for any agent that asks for text/markdown.

Fewer tokens also cost less, leave more of a model’s context window for the content that matters, and remove noise the model would otherwise have to see past.

Within about eighteen months, the plumbing of the agent world settled on Markdown:

• llms.txt (September 2024) proposes a Markdown file at the root of a website that tells language models what the site contains and where to find it.
• AGENTS.md (August 2025) is a Markdown file of instructions for coding agents, a README for machines. More than 60,000 open-source projects use it, and since December 2025 it has been stewarded by the Linux Foundation’s Agentic AI Foundation.
• Agent Skills (October 2025, an open standard since December) package a capability for an agent as a folder with a SKILL.md file: Markdown with a short metadata header.
• MarkItDown, an open-source tool from Microsoft, converts PDFs, Word documents, spreadsheets and slide decks into Markdown, precisely so that language models can work with them.

When the builders of these systems needed a format that both humans and models could write, read and review, they chose the one Gruber designed for email-style readability twenty years earlier.

What this unlocks

Put those two threads together, files you own and a format agents read natively, and a few practical things become possible that are awkward or impossible with a closed format:

1. Your notes become a knowledge base an assistant can use. Point an agent at a folder of Markdown notes, and it can search, summarize and cross-link them without an export step, an API key for your note app or a conversion pipeline. Whether you do this is up to you, and so is which agent and which folder, because the files are yours.
2. Documentation and instructions live next to the work. A README.md for people and an AGENTS.md for agents sit in the same repository, are versioned together and are reviewed in the same way.
3. Everything else can be turned into Markdown. A PDF manual or a slide deck can be converted once and then read by both you and your tools.
4. You write once and publish anywhere. The same file can be a note, a page on a website like this one, a slide or a PDF, with no rewrite in between.

Where the gold is impure

Markdown has real limits.

• There are many flavors. CommonMark fixed the core, but tools still add their own extensions: footnotes, callouts, math and diagrams all vary.
• Some of the best features aren’t portable. Obsidian’s [[wikilinks]] and embedded notes are a big part of why it’s pleasant to use, but GitHub or a static site generator will show them as plain text unless configured to understand them.
• Structure is shallow. Markdown has headings, lists and emphasis, but no rich semantics. Large technical documentation sets sometimes outgrow it, and complex tables are painful.

None of this changes the core property. Even when an extension doesn’t render, the text is still there and still readable. A broken wikilink is still a visible word in brackets, while a proprietary file whose app is gone won’t open at all.

In practice, keep the important content in plain CommonMark, use extensions where they help, and treat them as a convenience rather than the foundation.

Start with one folder

You don’t need to move your whole life to try this. Create a folder, write one note in Markdown and open it in three different apps. Then ask an assistant to read it. The note will look the same everywhere, and nothing asks you to sign in.

Formats come and go, and so do the apps built on them. A plain text file with a few # and - characters has already outlasted most of them, and it’s now the language the next generation of software reads best. Like gold, it keeps its value no matter who holds it.

Sources

• John Gruber, Markdown, Daring Fireball (release notes, design goal, credit to Aaron Swartz).
• Markdown, Wikipedia (release date 9 March 2004; CommonMark naming, September 2014; GFM specification, 2017; RFC 7763, March 2016).
• CommonMark.
• Microsoft, Text formatting in Notepad begins rolling out to Windows Insiders, 30 May 2025.
• Hugo, Configure markup (Goldmark, CommonMark-compliant default renderer).
• Obsidian, How Obsidian stores data.
• Steph Ango, File over app, 1 July 2023.
• Jeremy Howard, /llms.txt — a proposal to provide information to help LLMs use websites, Answer.AI, 3 September 2024.
• AGENTS.md (adoption figure, supported tools).
• Linux Foundation, Formation of the Agentic AI Foundation, 9 December 2025.
• Agent Skills specification; The Decoder, Anthropic publishes Agent Skills as an open standard.
• Celso Martinho and Will Allen, Markdown for Agents, Cloudflare, 12 February 2026.
• Microsoft, MarkItDown, GitHub.
• Eric Holscher, Why you shouldn’t use Markdown for documentation, 2016 (the case against).
• Token counts: measured for this article with OpenAI’s o200k_base tokenizer (via tiktoken) on one sample note, 25 September 2026.