The .md file,
explained properly

01 / DefinitionWhat an .md file actually is

An .md file is a plain text file that uses punctuation as formatting. Open it in Notepad and you see everything there is to see. There is no hidden layer, no XML zip container, no version of the file that only Word can read. A hash makes a heading. Two asterisks make bold. A hyphen makes a bullet.

That is the whole idea, and it is why the format has outlived nearly everything it competed with. Markdown was designed so that the marked-up source is itself readable — a document should be publishable as-is, as plain text, without looking like it has been marked up at all. Every design decision in the syntax follows from that one rule.

Two things share the name. Markdown is the syntax — the conventions for turning punctuation into structure. Markdown is also the original 2004 Perl script that converts that syntax into HTML. Today you almost always mean the first thing, and the converter is whatever your editor, static site generator, or CI pipeline happens to use.

Why anyone bothers

The argument for Markdown is not aesthetic. It is operational.

The tradeoff is real and worth stating: Markdown has no page layout, no fonts, no footers, no columns, no change tracking, and no native comments. It is a writing format, not a publishing format. When you need typeset output you convert it — see converting to and from Markdown.

02 / UtilityOpen an .md file right now

If you landed here because something handed you a .md file and your machine had no idea what to do with it — drop it below. Nothing is uploaded; the file is read and rendered locally in your browser.

Three other one-second answers, before the long ones in section 06:

• Just read it: rename the file to .txt and open it. Markdown was designed to be legible unrendered. Nothing is lost.
• Read it formatted: drag the file into a browser tab with a Markdown viewer extension installed, or paste it into any online renderer.
• Read it on GitHub: drop the file into a gist and GitHub renders it in full GitHub Flavored Markdown.

03 / HistoryHow Markdown happened — and how it got standardised twice

Markdown's history has a distinct shape: one designer's tool, then a decade of chaotic forks, then a community specification, then a second wave of standardisation driven by machines rather than people.

• March 2004John Gruber releases Markdown

  Announced on Daring Fireball as a text-to-HTML tool for web writers, built as a Movable Type plug-in and standalone Perl script. Aaron Swartz contributed to the design. The stated influences are Setext, atx, Textile, reStructuredText, Grutatext and EtText — but the biggest one is the informal conventions of plain-text email.

• December 2004Version 1.0.1 — and then nothing

  Markdown.pl 1.0.1 ships on 17 December 2004. It is still the last official release. The syntax page and the Perl script are the entire specification, and both leave a great deal ambiguous.

• 2004–2014The fork decade

  Ambiguity plus popularity produces dialects: PHP Markdown Extra, MultiMarkdown, Pandoc's Markdown, Maruku, kramdown, and eventually GitHub's own. Identical input produces different HTML in different tools. The Babelmark comparison tool exists purely to document the divergence.

• 2014CommonMark

  John MacFarlane — author of Pandoc — leads a standardisation effort with contributors from GitHub, Stack Overflow, Reddit and Discourse. The result is an unambiguous spec plus reference implementations in C (cmark) and JavaScript, defined by hundreds of input/output test cases rather than prose alone.

• March 2016IETF registration

  RFC 7763 registers text/markdown as a media type; RFC 7764 documents the design philosophies and variant strategy, and an IANA registry of Markdown variants is created so a document can declare which dialect it is written in.

• April 2019GitHub Flavored Markdown gets a formal spec

  GFM 0.29-gfm is published as a strict superset of CommonMark, adding exactly five extensions: tables, task lists, strikethrough, extended autolinks and an HTML tag filter. It has not been revised since — while GitHub's actual renderer has kept growing.

• September 2024llms.txt

  Jeremy Howard of Answer.AI proposes /llms.txt: a Markdown file at the root of a site that gives language models a curated map of what matters, plus the convention of serving a clean .md version of any page at the same URL with .md appended.

• 2025–2026Markdown becomes agent infrastructure

  AGENTS.md emerges as a cross-vendor instruction file and is adopted by 60,000+ open-source projects before being placed under the Linux Foundation's Agentic AI Foundation. Anthropic ships CLAUDE.md and the SKILL.md format for packaging agent skills. The most important new file formats of the decade are all, structurally, just Markdown. See section 09.

04 / ReferenceThe complete Markdown syntax reference

Everything below is CommonMark unless marked as an extension. Each block shows the source on the left and what a renderer produces on the right — the split view that Markdown editors have used since the beginning, and the fastest way to learn the format.

At a glance

Headings

One to six hash characters, a space, then the text. The space is not optional in CommonMark — #Heading renders as literal text, which is the single most common beginner mistake. Setext headings, made by underlining with = or -, still work but only reach two levels and are rare in modern documents.

# Document title
## A major section
### A subsection
###### The smallest heading

Setext style
===========

Second level
-----------

Use exactly one # per document and never skip levels. Most renderers generate anchor IDs from heading text, so ## Set up the CLI becomes #set-up-the-cli — that is how you deep-link into a README.

Emphasis

Asterisks and underscores both work for emphasis, but they are not interchangeable in practice. Underscores do not apply inside words in CommonMark, which protects snake_case_names from being mangled. Asterisks do apply mid-word. Pick asterisks as your house default and the problem disappears.

Plain, *italic*, **bold**,
***bold italic***, ~~struck out~~.

Underscores work too: _italic_,
__bold__ — but snake_case_stays
intact, which asterisks do not guarantee.

Escape with a backslash: \*literal asterisks\*

Paragraphs and line breaks

A blank line starts a new paragraph. A single newline inside a paragraph is ignored — the lines are joined. This surprises everyone once. To force a break without starting a paragraph, end the line with two spaces or a backslash.

These two lines
become one paragraph.

This line ends with two spaces··
so this one starts below it.

This one uses a backslash\
which does the same job visibly.

Lists

Bullets take -, * or +; ordered lists take a number and a dot. The numbers you type are ignored beyond the first — write 1. all the way down and the renderer counts for you, which makes reordering painless. Indent by two spaces (or four, consistently) to nest. Task lists with - [ ] are a GFM extension and are what drives the checkboxes in GitHub issues.

- Discovery
- Design
  - Trust architecture
  - Action heat ladder
- Delivery

1. Audit the surface
1. Map the touchpoints
1. Ship the change

- [x] Write the brief
- [ ] Get it signed off

Links and images

Four link forms matter. Inline links are the default. Reference links keep long URLs out of the prose and are worth using in documents that link heavily. Autolinks wrap a bare URL in angle brackets. Relative links resolve against the file's location, which is how a README links to docs/CONTRIBUTING.md and still works after the repository is cloned.

[inline link](https://commonmark.org)
[with a title](https://spec.commonmark.org "The spec")
[reference link][spec]
<https://agents.md>
[a local file](docs/CONTRIBUTING.md)
[jump to a heading](#lists)

![alt text describing the image](diagram.png)

[spec]: https://spec.commonmark.org

Alt text is not optional in a document anyone else will read. It is the only description a screen reader — or a language model ingesting your repo — will ever get of that image.

Code

Backticks for inline code; three backticks for a fenced block. Add a language identifier after the opening fence and every serious renderer will syntax-highlight it. If the code you are showing contains backticks, open the fence with four. Indenting four spaces also produces a code block, but fences are clearer and carry the language hint.

Run `npm install` first.

```bash
pandoc notes.md -o notes.pdf
```

```json
{ "variant": "GFM" }
```

pandoc notes.md -o notes.pdf

{ "variant": "GFM" }

Quotes and callouts

A > prefix quotes a block, and quotes nest. GitHub's alert syntax rides on top of the same mechanism: a blockquote whose first line is [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] renders as a coloured callout. Those five are the complete set, they cannot be nested inside other elements, and outside GitHub's renderer they degrade to an ordinary quote.

> Markdown is intended to be as
> easy-to-read as is feasible.

> [!NOTE]
> Useful context a reader should
> have, even when skimming.

> [!WARNING]
> Something that will bite you.

Tables

Tables are a GFM extension, not base Markdown — original 2004 Markdown had none, and told you to write raw HTML instead. Pipes separate cells; the second row sets alignment with colons. The columns do not need to line up in the source, though aligning them makes the file readable, which is rather the point of the format.

| File | Audience | Loaded |
| :--- | :---: | ---: |
| README.md | humans | always |
| AGENTS.md | agents | always |
| SKILL.md | agents | on demand |

Dividers, escapes and raw HTML

Three or more hyphens, asterisks or underscores on their own line produce a horizontal rule. A backslash escapes any punctuation character that would otherwise be syntax. And because Markdown was designed as a front end for HTML, raw HTML is legal inside it — though sanitising renderers (GitHub among them) filter dangerous tags, and pure-Markdown pipelines may strip it entirely.

Above the line.

---

Below it. Escape syntax with
a backslash: \# not a heading,
2 \* 3 \* 4 is arithmetic.

<details>
<summary>Click to expand</summary>

Hidden until opened.

</details>

The <details> trick above is the standard way to fold long sections inside a README. Leave a blank line after the <summary> tag or the Markdown inside will not be processed.

Footnotes and front matter

Footnotes are an extension — supported by GitHub, Pandoc and most static site generators, but not by CommonMark and not inside GitHub wikis. Front matter is not part of any Markdown spec at all: it is a YAML (occasionally TOML or JSON) block fenced by --- at the very top of the file, which the tool reading the file strips off and parses as metadata. Every static site generator, and now every agent skill format, relies on it.

---
title: The .md file, explained
date: 2026-08-09
tags: [markdown, agents, docs]
draft: false
---

The body starts here.[^1]

[^1]: And this is the footnote.

title: The .md file, explained
date: 2026-08-09
tags: [markdown, agents, docs]
draft: false

05 / DialectsFlavours: why the same file looks different in two tools

There is no single Markdown. There is a small core everyone agrees on, and a ring of extensions that vary by renderer. Knowing which ring you are standing in is most of the debugging.

The practical model has three layers. Core CommonMark — headings, emphasis, lists, links, code, quotes — behaves identically everywhere. Common extensions — tables, strikethrough, task lists, footnotes — are supported by most tools but not all, and not always the same way. Platform features — GitHub's alerts, Mermaid diagrams, wiki-links, LaTeX maths — are renderer-specific and degrade to plain text or raw source elsewhere.

06 / How-toOpening and editing .md files on every platform

Nothing needs installing to read a Markdown file — every operating system already ships a text editor. What people actually want is to read it formatted. Here is the shortest route on each platform.

Windows

• Read as-is: right-click → Open with → Notepad. Works on every Windows machine ever made.
• Read formatted, no install: use a browser-based viewer, or paste into a gist.
• Read formatted, properly: install Visual Studio Code, open the file, press Ctrl+Shift+V for a rendered preview or Ctrl+K then V for a side-by-side one. VS Code ships Markdown preview with no extension required.
• Open in Word: Word will open a .md file as text. For a properly formatted document, convert it first — see section 07.
• Set the default: right-click → Open with → Choose another app → tick "always use this app". Windows has no built-in Markdown association, so whatever you choose here is the one that sticks.

macOS

• Quick Look: select the file in Finder and press space. macOS previews it as plain text; add a Quick Look plugin if you want it rendered.
• TextEdit opens any .md file directly. So does BBEdit, which has handled Markdown since roughly the beginning.
• Dedicated writing apps: iA Writer, Typora, Obsidian, Zettlr — all treat .md as their native format rather than an import.
• Terminal: glow file.md or bat file.md renders Markdown with styling straight in the shell.

iPhone and iPad

iOS has no system-level Markdown viewer, which is why "how to open md on iPhone" is a genuinely common search. Options, cheapest first:

• Files app: tap the file — iOS shows it as plain text. Perfectly readable, just unformatted.
• Apple Notes / Pages: paste the text in. Notes converts common Markdown as you type.
• A Markdown app: Obsidian, iA Writer, Taio, Runestone and others open .md from the Files app and render it. Once installed, iOS offers them in the share sheet.
• Shortcuts: a two-step shortcut ("Get file → Make rich text from Markdown → Quick Look") gives you a native renderer with no app at all.

Android

• Most file managers open .md in a text viewer by default. Choose "Open with → Text editor" if prompted.
• Markor, Obsidian, and other Markdown editors register the .md type and appear in the "open with" list once installed.
• Google Drive will preview an uploaded .md as text, and Google Docs can import it as a formatted document.

In the browser

• Browser extensions such as Markdown Viewer render local .md files when you drag them into a tab — you must grant access to local file URLs for this to work.
• Web editors — StackEdit, Dillinger, HackMD — give you live preview and export without installing anything.
• The viewer in section 02 of this page does the same thing without sending the file anywhere.

In your editor or IDE

07 / ConversionConverting Markdown to and from everything else

Markdown is a source format. Sooner or later something wants a PDF, a Word file, a deck, or clean HTML. There is one tool that does nearly all of it, and a set of second-best options for when you cannot install anything.

Pandoc — the universal converter

Pandoc, written by the same John MacFarlane who led CommonMark, converts between dozens of document formats through a common internal representation. It is the correct default answer to almost every "convert md to X" question.

Without installing anything

08 / ToolingEditors, viewers, libraries and linters

A working Markdown setup usually has four parts: something to write in, something to render with, something to enforce consistency, and something to publish. Here is the landscape, grouped by the job you are hiring the tool for.

Writing apps

• Obsidian — local-first knowledge base built directly on a folder of .md files. No lock-in: the vault is just files on disk.
• Typora — seamless live preview; the syntax transforms as you type rather than sitting in a second pane.
• iA Writer — minimal, focus-oriented editing across macOS, iOS, Windows and Android.
• Zettlr — open source, academic bent, with citation support via Zotero and Pandoc export built in.
• MarkText — open source, cross-platform, real-time preview.
• Logseq — outliner-style note-taking on plain Markdown files.

Browser-based editors and viewers

• StackEdit — full-featured in-browser editor with sync and export.
• Dillinger — clean live-preview editor with one-click export to HTML and PDF.
• HackMD — real-time collaborative Markdown, useful for meeting notes and RFCs.
• CommonMark Dingus — the reference implementation's playground; shows the AST alongside the HTML. The best debugging tool there is.
• Babelmark 3 — runs one snippet through dozens of implementations at once so you can see exactly where they disagree.

Parsers and libraries

Linting and quality

• markdownlint — the standard rule set for structural consistency; available as a CLI, a VS Code extension and a CI action.
• Vale — prose linting against a style guide. Enforces terminology and tone, not just syntax.
• Prettier — formats Markdown as well as code; ends arguments about list markers and table alignment permanently.
• lychee — fast link checker for Markdown; run it in CI so your documentation's links stay honest.

Publishing from Markdown

• Hugo, Jekyll, Eleventy, Astro — static site generators that read a folder of .md and emit a website.
• Docusaurus, MkDocs, VitePress, Starlight — documentation sites with search, versioning and navigation out of the box.
• Quarto, Jupyter Book — executable documents for analysis and scientific publishing.
• Marp, Slidev, reveal.js — slide decks written as Markdown files.
• Pandoc — everything else: books, papers, print, ebooks, Word, LaTeX.

09 / The turnMarkdown became the interface between humans and agents

Something changed between 2024 and 2026. Markdown stopped being only a way to write documents for people and became the default way to write instructions for machines that read like documents. Every significant agent-configuration format that has emerged is, structurally, a Markdown file.

The reason is not sentimental. A Markdown file is simultaneously the cheapest format for a model to parse and the only format a human maintainer will reliably keep up to date. JSON and YAML are machine-friendly but nobody writes prose in them. A wiki is human-friendly but nothing can load it deterministically. Markdown sits on the seam: headings give a model structure, prose gives it nuance, and a person can review the diff in a pull request.

Four families of file matter right now, and they are complementary rather than competing. The distinction between them is who reads it and when it loads.

Underneath all four is the same bet: that the readable artefact and the machine-readable artefact should be the same file. When the instructions an agent follows are a document a person can review in a pull request, you get auditability, versioning and shared understanding for free. When they are a config blob or a vector store, you get none of that. That is an interface design decision that happens to be stored in a repo — and it is where trust in agentic systems is built or lost.

Writing Markdown that a model reads well

Whoever the reader is, the same craft applies — these are habits worth having in any document, not agent-specific tricks.

• Front-load the answer. A section's first sentence should stand alone when retrieved out of context. Retrieval chunks rarely carry the paragraph above them.
• Use headings as an index, not decoration. Nested, meaningful headings give a chunker natural boundaries. A 4,000-word document with two headings will be split badly.
• Keep one idea per section. Mixed-topic sections retrieve poorly and get quoted out of context.
• Prefer tables for parameters and comparisons. A Markdown table survives extraction; a paragraph describing six options does not.
• Label code fences and expand acronyms once. Both readers benefit; neither has your context.

10 / CraftHouse rules for Markdown that stays readable

Markdown's tolerance is its weakness. Four ways of writing the same list all render identically, so a repository with five contributors accumulates five dialects. Pick rules, write them down, and let a formatter enforce them.

Then automate it: markdownlint for structure, prettier for formatting, lychee for dead links, all in CI. Style arguments in review are a waste of two people's attention.

11 / DebuggingWhy your Markdown isn't rendering

Nearly every rendering bug comes from one of nine causes. In rough order of frequency:

12 / GlossaryThe vocabulary

13 / LibraryEvery link worth keeping

Specifications first, because most disagreements about Markdown are settled by reading one.

Specifications and standards

• Markdown — Daring Fireball — the original project page, still online, still version 1.0.1.
• Markdown Syntax Documentation — Gruber's original syntax description, including the philosophy section that explains every subsequent decision.
• Markdown Basics — the short before/after tour.
• Introducing Markdown (March 2004) — the original announcement post.
• CommonMark Spec — all versions; 0.31.2 is current as of this writing.
• CommonMark quick reference — a ten-minute interactive tutorial, the best thing to send a colleague.
• CommonMark Dingus — live parser with AST view.
• GitHub Flavored Markdown Spec — version 0.29-gfm, the five official extensions.
• RFC 7763 — The text/markdown Media Type — the formal registration.
• RFC 7764 — Guidance on Markdown — design philosophies, stability strategies, variant registrations.
• IANA Markdown Variants registry — the official list of declared dialects.
• CommonMark discussion forum — where edge cases get argued out.

Platform documentation

• GitHub — Basic writing and formatting syntax — the canonical reference for alerts, footnotes and task lists.
• GitHub — Creating diagrams — Mermaid, GeoJSON, TopoJSON and ASCII STL inside fenced blocks.
• GitHub — Tables — alignment and escaping rules.
• GitLab Flavored Markdown — GitLab's extension set, including its own diagram support.
• Google Docs — Use Markdown — import, export, and paste-as-Markdown.
• The Markdown Guide — the best general-purpose tutorial site, with per-tool compatibility notes.
• Markdown cheat sheet — one page, print it.

Agent and AI formats

• AGENTS.md — the open format, the FAQ, and 60k+ real examples on GitHub.
• agentsmd/agents.md on GitHub — the repository behind the format.
• Claude Code — How Claude remembers your project — CLAUDE.md scopes, imports, path-scoped rules, auto memory.
• Anthropic — Agent Skills overview — the SKILL.md format and the three levels of progressive disclosure.
• Anthropic — Skill authoring best practices — how to write a description that actually triggers.
• anthropics/skills — open-source example skills to read before writing your own.
• llmstxt.org — the /llms.txt proposal, with examples and tooling.
• Answer.AI — the original llms.txt post — Jeremy Howard's reasoning, September 2024.
• Model Context Protocol — the adjacent standard for letting models act, not just read.
• Cloudflare — Introducing Markdown for Agents — HTTP content negotiation for agents, and the token maths behind it.
• Markdown for AI (auxfirst) — our companion piece: why agents converged on Markdown, and how to build a business context layer.

Tools worth bookmarking

• Pandoc and its manual — the single most useful page in this entire list.
• Babelmark 3 — compare implementations side by side.
• Mermaid and the live editor — diagrams as text inside Markdown.
• markdownlint — rules and CI integration.
• Vale — prose style enforcement.
• MDX — components inside Markdown.
• MyST — structured technical and scientific authoring.
• Quarto — executable documents, multi-format output.
• Marp — slide decks from a .md file.
• Obsidian — the most popular way to live inside a folder of Markdown files.

14 / FAQShort answers

SourcesWhere the specifics come from

• Daring Fireball — Markdown and the syntax page, for the original design, release dates and philosophy.
• CommonMark Spec, for version 0.31.2 and its publication date of 28 January 2024.
• GitHub Flavored Markdown Spec 0.29-gfm, for the five extensions and the CommonMark superset relationship.
• GitHub Docs, for the alert types, footnote behaviour and diagram syntaxes.
• RFC 7763 and RFC 7764 (March 2016), for the media type and variant registry.
• agents.md, for adoption figures, monorepo precedence, Linux Foundation stewardship and the sample file.
• Claude Code documentation, for CLAUDE.md scopes, imports, rules and size guidance.
• Anthropic Agent Skills documentation, for the SKILL.md structure and the three loading levels.
• llmstxt.org and Answer.AI, for the llms.txt proposal and its date.
• Google Docs Editors Help, for Markdown import and export behaviour.
• FileInfo, for the non-Markdown uses of the .md extension.

Verified against these sources on 9 August 2026. Specifications and product documentation change; check the primary source before quoting a version number.