HTML is for browsers; Markdown is for brains.
LLMs are trained heavily on GitHub repositories, StackOverflow, and technical documentation. This makes Markdown their “native” format. They “think” in Markdown.
Token Efficiency
Markdown is less verbose than HTML.
- HTML:
<h1>Title</h1> (9 characters, ~3 tokens). - Markdown:
# Title (7 characters, ~2 tokens). - HTML List:
<ul><li>Item</li></ul> (21 characters). - Markdown List:
- Item (6 characters).
Across a 2,000 document, this saves thousands of tokens. A clean Markdown file consumes fewer tokens than its HTML equivalent, allowing more content to fit into the context window.
The metadata block at the top of a Markdown file, known as Frontmatter, is the most valuable real estate for MCP-SEO. It is structured data that sits before the content, framing the model’s understanding.
Beyond Title and Date
Most Hugo or Jekyll sites just use title and date. To optimize for retrieval, you should inject semantic richness here.
Recommended Fields
summary: A dense 50-word abstract. Agents often read this first to decide if the full document is worth processing.keywords: Explicit vector keywords. “Neuroscience, synaptic, plasticity.”entities: A list of named entities. ["Elon Musk", "Tesla", "SpaceX"].complexity: “Beginner” | “Advanced”. Helps the agent match the user’s expertise level.
Example Frontmatter
---
title: "The Physics of Black Holes"
summary: "A technical overview of event horizons and Hawking radiation."
complexity: "PhD"
entities:
- Stephen Hawking
- Albert Einstein
tags: ["Astrophysics", "Gravity"]
---
The Retriever’s Shortcut
Many RAG systems index the Frontmatter separately or weight it heaver. By putting your core concepts in key-value pairs, you are essentially hand-feeding the indexer. You are saying, “This is exactly what this file is about.”