1/5 Markdown Is the Interface Between You and AI
You’ve used Markdown before. GitHub README files. Slack messages. Maybe a Notion page. You probably think of it as “that formatting thing with the hashtags and asterisks.”
That undersells it by a factor of ten.
Markdown is the native language of AI. Every major LLM — ChatGPT, Claude, Gemini, Copilot — was trained on massive amounts of Markdown. When you write in Markdown, you’re speaking the language AI already thinks in. When you write in Word or Google Docs, the AI has to translate first.
That translation costs you tokens, context, and quality.
The Token Tax
Every AI model has a context window — a limit on how much text it can process at once. The format you use determines how much of that window your actual content occupies versus formatting overhead.
The same content in different formats:
| Format | Tokens | Overhead |
|---|---|---|
| Markdown | 11,612 | baseline |
| YAML | 12,333 | +6% |
| TOML | 12,503 | +8% |
| JSON | 13,869 | +19% |
| HTML | ~30,000 | +158% |
Markdown is 15% more efficient than JSON and up to 60% more efficient than HTML. That’s not a rounding error — it’s the difference between fitting your entire document in one prompt or having to split it across two.
When Bun’s documentation switched from HTML to Markdown, they saw a 10x token reduction. More content in the same window. Better answers. Lower cost.
Why AI Understands Markdown Better
It’s not just about size. Markdown’s structure maps directly to how LLMs process meaning:
# The Kingdom of Sorted Scrolls
## Characters
- **Lady Binary** — a clever librarian
- **The Scrolls** — a row of numbered parchments
## The Challenge
Find one scroll among a million.Those # headings aren’t just visual — they tell the AI “this is a hierarchy.” The **bold** isn’t decoration — it signals “this is important.” The - lists aren’t formatting — they’re structured data.
HTML conveys the same information but buries it in tags:
<h1>The Kingdom of Sorted Scrolls</h1>
<h2>Characters</h2>
<ul>
<li><strong>Lady Binary</strong> — a clever librarian</li>
<li><strong>The Scrolls</strong> — a row of numbered parchments</li>
</ul>More tokens. Same meaning. The AI has to parse through <ul>, <li>, <strong> before it gets to the content. Markdown skips that entirely.
Markdown Renders Everywhere
Write it once, read it anywhere:
- GitHub renders it as formatted pages
- VSCode shows live preview side-by-side
- Notion, Slack, Discord understand Markdown natively
- Blogs (like this one) are built from Markdown files
- Mermaid turns Markdown into diagrams
- Marp turns Markdown into presentations
A .docx file is locked in Word. A .md file is readable by every tool that matters.
For the full syntax reference, see Markdown Essentials: Write Once, Render Everywhere.
Hands-On: Your First AI-Ready Document
Let’s start a project we’ll build across this entire series. We’re going to create Algorithm Fairy Tales — stories that teach computer science concepts through fantasy narratives.
Here’s the outline for our first tale. Create a file called lady-binary.md:
# Lady Binary and the Sorted Scrolls
> An Algorithm Fairy Tale about Binary Search
## Characters
- **Lady Binary** — a clever librarian who always starts in the middle
- **The Sorted Scrolls** — a row of numbered parchments, always in order
- **The Apprentice** — a young villager who searches shelf by shelf
## The Kingdom
A vast library where every scroll is numbered and sorted.
The Apprentice searches from the beginning, one scroll at a time.
Lady Binary has a better method.
## The Challenge
Find scroll #42 among a million scrolls.
## Lady Binary's Method
1. Open the middle scroll
2. Too high? Ignore the upper half
3. Too low? Ignore the lower half
4. Repeat with what remains
5. Each peek halves the search
## The Moral
The Apprentice checks a million scrolls.
Lady Binary checks twenty.
Because log2(1,000,000) is roughly 20.That’s it. Plain text. No special software needed. You could write it in Notepad.
But notice: it’s structured. Headings establish hierarchy. Bold marks characters. The numbered list shows a sequence. Any AI model can read this and understand the relationships instantly.
What Just Happened
You wrote a document that:
- Any AI can process efficiently (minimal token overhead)
- Any tool can render (GitHub, VSCode, Slack, a blog)
- Any human can read without special software
- Has clear structure that AI uses to understand relationships
You didn’t install anything. You didn’t learn a framework. You wrote plain text with a few symbols.
Next post, we’ll open this file in VSCode and turn it into a proper project — with live preview, version control, and the beginning of an AI-augmented workflow.