Markdown as the medium

If a refined concept is the product, that concept has to live somewhere. Markdown is the backbone medium. What makes it right is what it leaves out:

• No parser tax. The model reads it as text.
• Structure light enough to skim, heavy enough to navigate.
• Human-readable raw or rendered.
• Diffable, version-controllable, greppable.
• Expressive enough for prose, structured enough for data.

JSON and YAML force the model (and you) to spend tokens and attention on syntax instead of meaning. Markdown stays out of the way.

Plain text beats structured data for most things

LLMs are trained on text. Markdown is text with a thin convention layer. When Claude reads a .md file, there’s no parser between the file and the model: the tokens it sees and the tokens you see are the same tokens.

JSON and YAML, by contrast, burn attention on delimiters, escaping, and strict structure. You can tell by the failure modes: models produce invalid JSON when they’re stressed, because the formal requirements compete with the content. Markdown has almost no failure modes. A misplaced asterisk doesn’t corrupt a file.

There are still cases where you do want structured data: machine-to-machine exchange, schema-strict outputs, config files consumed by deterministic tools. Use JSON/YAML when something downstream requires it. Use markdown when the reader is either a human or a language model.

The right amount of structure

Markdown’s minimal vocabulary carries most of what you need:

• Headings (#, ##, ###) create navigable sections. Both humans and Claude use them to orient.
• Lists (-, *, 1.) group parallel items without ceremony.
• Fenced code blocks keep code and prose separate, so Claude never confuses an example for an instruction.
• Links ([text](url)) are how you wire files together, whether to the web, to other files in the repo, or to external docs.

Don’t go further than this. Tables are fine when the data is tabular; avoid them when a list works. Avoid inline HTML in markdown unless you’re intentionally escaping markdown’s limits.

Where markdown stops

Markdown is the backbone, not the whole spectrum. When the thing you’re specifying is visual or interactive, words are the wrong fidelity, and the specification medium continues upward:

• Mermaid diagrams inside markdown, for flows and data models.
• Standalone HTML mockups of parts of the product, in your styling, when you need to see a direction to judge it.
• Clickable prototypes on realistic mock data, when the interaction itself is the question.

Most of these higher-fidelity artifacts are temporary. React to them, decide, and fold the decision back into the markdown backbone and the invariants that must hold. The durable record stays in text; the visuals exist to drive the creative process.

Cross-linking and wikilinks

A single file is a document. A folder of cross-linked .md files is a knowledge base. Cross-references turn the folder into a graph, and Claude can traverse that graph the same way a human would: clicking through, building understanding over multiple files.

Some projects use Obsidian-style wikilinks ([[filename]]) for tight local linking. Others use plain markdown links ([text](./filename.md)). Either works. What matters is that the links are consistent, discoverable, and actually followed.

The file is the artifact

One nuance that trips people up: the rendered view (the pretty HTML you see in Obsidian, or the preview in VS Code) is presentation, not the artifact. The artifact is the .md file. You can read it raw. You can diff it. You can grep across it. You’re never locked into a specific renderer.

That means the file is also what you hand to Claude. Not a PDF export of it. Not a Confluence URL. The file itself, as text.

Resources

• Simon Willison: Markdown tagged posts
• CommonMark: the standard reference for markdown syntax
• Obsidian: Format your notes for wikilink conventions