Markdown and front matter have quietly become the universal standard for documentation — in static sites, developer tools, AI agent frameworks, and knowledge bases alike. This guide explains why that happened and how to write docs that work for both humans and machines.
If you've worked with any modern documentation system — a developer blog built on Hugo, a knowledge base in Obsidian, a project using Claude Code, or an AI agent framework — you've almost certainly encountered the same pattern: a plain-text file with a block of metadata at the top, followed by content written in Markdown.
This isn't a coincidence. Over the past decade, the combination of Markdown (a lightweight formatting syntax) and front matter (structured metadata embedded at the top of the file) has become the de facto standard for documentation across the entire software ecosystem. GitHub uses it. Jekyll, Hugo, Docusaurus, and Astro use it. Obsidian uses it. Claude Code's CLAUDE.md uses it. The Claude Agent SDK's SKILL.md files use it.
The convergence accelerated with AI. Large language models are trained primarily on plain text and Markdown — they understand its structure natively. When you write documentation in Markdown with structured front matter, you're writing in a format that humans can read in any text editor, Git can version-control cleanly, static site generators can render to HTML, and AI systems can parse without any pre-processing. One format, the entire toolchain.
By the end of this guide you'll understand what each part does, why the combination works so well, what front matter fields matter most for AI-readable documentation, and the conventions that make your Markdown actually useful to the tools consuming it.
Markdown is a lightweight markup language designed around one idea: a document should be readable as plain text and renderable as rich HTML without changing the source. You've almost certainly read Markdown without knowing it — every GitHub README, every developer blog post, every Stack Overflow answer is written in it.
The syntax stays out of your way. Headings use # symbols. Bold uses **double asterisks**. Links are [text](url). Code gets backticks. That's the core of it.
The decision to build documentation on plain text rather than binary formats (Word, PDF, rich text) has compounding advantages that become clear when you're working at scale:
On Windows and Mac, when you git diff two versions of a Markdown file, you see exactly which words changed. Try that with a .docx file — Git sees it as a binary blob and shows only "Binary files differ." Markdown's plain-text nature is what makes documentation version control actually useful.
Front matter is a block of structured metadata placed at the very top of a Markdown file, enclosed between two lines of triple dashes (---). Everything between those dashes is metadata about the document — its title, date, tags, author, skill level, or anything else that helps systems categorise and process it. Everything after the closing --- is the document's actual content.
Think of front matter as the label on the outside of a manila folder. Before you open the folder to read what's inside, the label tells you the title, the date it was filed, what project it belongs to, and how urgent it is. Front matter does the same thing — it tells any tool consuming the file what it's dealing with before reading the content.
--- delimiters tell parsers where the metadata ends and the content begins. The metadata is written in YAML — a simple key: value format. The content is standard Markdown.The metadata block is written in YAML (pronounced "yam-ul") — a human-readable data format designed to be as close to plain English as possible. The rules are minimal:
The basic building block. Key on the left, colon, space, value on the right. title: "My Doc"
A list of values uses a dash on a new line, indented two spaces. tags: then - item on the next line.
true / false without quotes. Used for flags like draft: false or published: true.
ISO 8601 format without quotes: date: 2026-03-11. Parsers recognise this as a date automatically.
YAML uses spaces, not tabs for indentation. A tab character will break your front matter silently — the parser will either error or ignore the field. Use two spaces for list items and nested keys. Most code editors (VS Code, etc.) can be set to insert spaces when you press Tab.
The adoption of Markdown + front matter as the standard for AI-adjacent documentation wasn't a committee decision — it emerged from the practical reality of how language models and agentic tools process information.
"An AI that has to parse a Word document, strip formatting, guess what's a heading vs. body text, and extract metadata from prose — is already behind. A Markdown file with front matter gives it structure for free."
— A pattern visible across every major AI tooling framework, 2023–2026The vast majority of public text on the internet — GitHub, developer blogs, Stack Overflow, Wikipedia — is either plain text or Markdown. LLMs learned Markdown's structure during pre-training. When an AI encounters a # heading or a ``` code fence, it understands the hierarchy without any special handling.
Natural language is ambiguous. "This document is about machine learning for beginners published in March" lives in prose and requires the AI to parse it. Front matter puts that information in a structured, machine-queryable form: topic: machine-learning, skill_level: S1, date: 2026-03. No parsing required — just key lookup.
Retrieval-Augmented Generation (RAG) systems retrieve relevant documents before asking an AI to answer a question. Front matter fields become filterable metadata: "find all S1 tutorials tagged git published after 2025." Without structured metadata, this requires the model to read every document to determine relevance.
Claude Code looks for CLAUDE.md in a project directory and reads it as context. The Claude Agent SDK's SKILL.md files use front matter to declare a skill's name, description, and trigger conditions. GitHub Copilot reads .github/copilot-instructions.md. These aren't coincidences — agent tools consistently reach for Markdown + front matter as their configuration and context format.
Markdown + front matter works simultaneously as: a human-readable file in any editor, a version-controlled document in Git, a page in a static site (Jekyll, Hugo, Docusaurus, Astro), a note in Obsidian, and context for an AI tool. No conversion needed between uses.
When you run Claude Code in a project directory, one of the first things it does is look for a CLAUDE.md file. If found, it reads that file and uses it as persistent context for the entire session — understanding your project's conventions, tech stack, and preferences. That file is plain Markdown, and its front matter (if present) can signal things like the project type, relevant tools, and what Claude should and shouldn't do. The format was chosen specifically because it requires zero pre-processing and works directly as AI input.
There's no universal standard for front matter fields — different systems define their own. But a set of fields has converged across most documentation systems, and knowing them lets you write front matter that works across multiple tools simultaneously.
These are recognised by virtually every static site generator, documentation tool, and AI framework:
2026-03-11. Essential for sorting, filtering by recency in RAG systems, and signalling AI tools about the currency of the content.version-control not Version Control.true while the document is a work in progress. Most static site generators will exclude draft files from builds. AI tools can use this to filter out unfinished content.These fields are increasingly common in documentation written primarily for AI consumption or for systems like Technoobtopia that use structured skill/length metadata:
"windows", "mac", or "windows, mac". Enables platform-targeted retrieval — useful when a user on Windows should be served Windows-specific content.description, stack, and do_not fields give it immediate, unambiguous context.Not all Markdown is equally useful to AI tools. A document that renders beautifully in a browser can still be ambiguous or poorly structured from a machine's perspective. These conventions are the difference between Markdown that works and Markdown that works everywhere.
Your document should have exactly one # H1 heading, and it should match (or closely reflect) the title in your front matter. AI tools and static site generators use the H1 as the canonical document title when the front matter title is absent. Multiple H1s signal structural ambiguity.
Go # → ## → ### in order. Never jump from # to ###. Heading hierarchy is how AI systems understand document structure and how screen readers navigate. A skipped level breaks both. Think of headings as an outline — you wouldn't jump from chapter to sub-subsection.
A code block opened with ```bash or ```python is far more useful than a bare ```. The language specifier enables syntax highlighting in renderers, signals to AI tools what kind of code this is, and often enables platform-specific handling (e.g., a Windows-aware tool might add a PowerShell note to a bash block).
[click here](https://docs.example.com) is useless to a screen reader and gives an AI tool no information about what the link points to. [front matter documentation](https://docs.example.com) tells both humans and machines exactly what they'll find. AI systems use link text to build knowledge graphs between documents.
Tags are only useful for filtering if they're consistent. Decide on a convention — lowercase hyphenated (version-control, getting-started) — and apply it everywhere. Mixed conventions (Version Control, versioncontrol, version-control) mean three tags that should be one, and a RAG filter that misses two-thirds of relevant documents.
When commands differ between Mac and Windows, label each explicitly rather than assuming a platform. A Markdown block with a clear label (Mac: / Windows:) is unambiguous to both a human reader and an AI tool trying to serve platform-appropriate responses. Many documentation systems also support custom callout syntax (::: note[Windows]) for this purpose.
If five tutorials use skill_level and one uses difficulty, the odd one out is invisible to any filter or AI query looking for skill_level. Consistency of field names across a collection is what turns a pile of Markdown files into a queryable knowledge base. Define your fields once (in a style guide!) and apply them everywhere.
Install the Prettier extension and the YAML extension in VS Code. Prettier will auto-format your Markdown on save. The YAML extension validates your front matter blocks and highlights errors before they cause problems downstream. Both work identically on Windows and Mac.
Everything in one place — copy the front matter template, then refer to the syntax and conventions as needed.
Front matter is the label on the folder. Markdown is the contents inside. The triple-dash delimiters are the folder cover itself. Together they create a document that humans can read, Git can track, websites can render, and AI can query — without any conversion step in between. Write front matter for machines. Write Markdown for humans. Both benefit from the same file.
Natural T3 continuations of this topic — not live yet, but they're coming.
What happens when you embed JSX inside your markdown. How Astro, Next.js, and Docusaurus all use MDX differently.
The spec that defines what your data is allowed to look like — powers VS Code autocomplete, API contracts, and Astro content collection schemas.
Why .env files exist, how dotenv works, what secrets managers do, and why you should never hardcode a key.