# MD Files Explained: The Complete Markdown Guide

> Canonical: https://auxfirst.com/news/md-file-markdown-guide.html
> Markdown representation of this article, for agents and LLM crawlers.

What a .md file is, how to open and write one, the syntax that works everywhere, and why AI agents now read Markdown.

## 01 / Definition — What 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.

| Property | Value |
|---|---|
| Extensions | `.md` (dominant), `.markdown`, and in the wild `.mdown`, `.mkd`, `.mdx` (MDX), `.qmd` (Quarto), `.rmd` (R Markdown) |
| Media type | `text/markdown`, registered by [RFC 7763](https://www.rfc-editor.org/rfc/rfc7763.html) in March 2016, with an optional `variant` parameter to declare the dialect |
| Encoding | UTF-8 text. No magic number, no header, no binary section |
| Uniform Type Identifier | `net.daringfireball.markdown`, conforming to `public.plain-text` |
| Created | March 2004 by John Gruber, with input from Aaron Swartz. Version 1.0.1 of the Perl converter shipped 17 December 2004 and was the last release |
| Reference spec | [CommonMark 0.31.2](https://spec.commonmark.org/) (28 January 2024) — the closest thing to a normative definition, with 500+ worked examples doubling as conformance tests |
| Licence | The original implementation is BSD-style; the syntax itself is not owned by anyone |

Careful — .md is an overloaded extension

Markdown is not the only thing that claims `.md`. The same three characters are used by Sega Mega Drive / Genesis ROM images, GCC machine-description files, Moneydance personal finance data, MuseData music notation, and MDCD archives from the MS-DOS era. If a `.md` file opens as binary gibberish in a text editor, it is one of those — not broken Markdown. Check the first bytes before you go looking for a Markdown viewer.

### Why anyone bothers

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

##### It diffs

Line-based plain text means `git diff` shows exactly what changed in a sentence. A `.docx` shows that a zip archive changed. Review, blame, and merge all work.

##### It survives

No renderer, no problem. A twenty-year-old Markdown file is still fully legible today in any text editor on any operating system. That is not true of most formats from 2004.

##### It is writable at speed

Hands never leave the keyboard, no formatting toolbar, no cursor hunting. Structure is expressed while you write rather than applied afterwards.

##### Machines parse it cheaply

Headings, lists and code fences give a document real structure with almost no syntactic overhead — which is exactly why language models, RAG pipelines and coding agents converged on it.

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 / Utility — Open 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.

Markdown viewer · local only
 Load sample
 Clear
 Choose .md file

Rendered output appears here.

Runs entirely in your browser — no upload, no account, works offline once the page is loaded. Raw HTML inside the file is displayed as escaped text rather than executed, on purpose.

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](https://gist.github.com/) and GitHub renders it in full GitHub Flavored Markdown.

## 03 / History — How 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 2004**John 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 2004**Version 1.0.1 — and then nothing**

[Markdown.pl 1.0.1](https://daringfireball.net/projects/markdown/) 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–2014**The 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](https://babelmark.github.io/) comparison tool exists purely to document the divergence.

2014**CommonMark**

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](https://github.com/commonmark/cmark)) and JavaScript, defined by hundreds of input/output test cases rather than prose alone.

March 2016**IETF registration**

[RFC 7763](https://www.rfc-editor.org/rfc/rfc7763.html) registers `text/markdown` as a media type; [RFC 7764](https://www.rfc-editor.org/rfc/rfc7764.html) documents the design philosophies and variant strategy, and an [IANA registry of Markdown variants](https://www.iana.org/assignments/markdown-variants/markdown-variants.xhtml) is created so a document can declare which dialect it is written in.

April 2019**GitHub Flavored Markdown gets a formal spec**

[GFM 0.29-gfm](https://github.github.com/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 2024**llms.txt**

Jeremy Howard of Answer.AI proposes [/llms.txt](https://llmstxt.org/): 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–2026**Markdown becomes agent infrastructure**

[AGENTS.md](https://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.

The pattern worth noticing

Markdown was standardised the first time because humans needed consistent rendering across websites. It is being standardised a second time because machines need consistent *instructions* across tools. Both waves converged on the same answer: keep it plain text, keep the structure shallow, keep it readable to whoever opens it — carbon or silicon.

## 04 / Reference — The 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

| You want | You type | Where it works |
|---|---|---|
| Heading | `# H1` … `###### H6` | Everywhere |
| Bold | `**bold**` or `__bold__` | Everywhere |
| Italic | `*italic*` or `_italic_` | Everywhere |
| Bold italic | `***both***` | Everywhere |
| Strikethrough | `~~gone~~` | GFM extension |
| Bulleted list | `- item` (also `*` or `+`) | Everywhere |
| Numbered list | `1. item` | Everywhere |
| Checkbox | `- [ ] todo` / `- [x] done` | GFM extension |
| Link | `[text](https://url)` | Everywhere |
| Image | `![alt](path.png)` | Everywhere |
| Inline code | `` `code` `` | Everywhere |
| Code block | three backticks, optional language | CommonMark |
| Quote | `> quoted` | Everywhere |
| Callout | `> [!NOTE]` | GitHub renderer |
| Table | pipes and dashes | GFM extension |
| Divider | `---` on its own line | Everywhere |
| Hard line break | two trailing spaces, or `\` | CommonMark |
| Escape a character | `\*not italic\*` | Everywhere |
| Metadata | YAML front matter between `---` lines | Tool-specific |

### 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.

**headings** — sourcerendered →

```
# 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.

**emphasis** — sourcerendered →

```
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.

**breaks** — sourcerendered →

```
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.

**lists** — sourcerendered →

```
- 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.

**links** — sourcerendered →

```
[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.

**code** — sourcerendered →

```
Run `npm install` first.

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

```json
{ "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.

**quotes** — sourcerendered →

```
> 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.

**tables** — sourcerendered →

```
| 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.

**misc** — sourcerendered →

```
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.

**metadata** — sourcerendered →

```
---
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.
```

## 05 / Dialects — Flavours: 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.

| Flavour | What it is | Adds | You meet it in |
|---|---|---|---|
| Original | Gruber's 2004 syntax + Perl script, frozen at 1.0.1 | Nothing since 2004 | Historical documents, legacy blog engines |
| CommonMark | The unambiguous community spec, v0.31.2 | Fenced code, precise edge-case rules | Reddit, Discourse, Stack Overflow, most libraries |
| GFM | Strict superset of CommonMark, spec v0.29-gfm | Tables, task lists, strikethrough, autolinks, tag filter | GitHub, GitLab, and nearly every developer tool |
| GitHub renderer | GFM plus proprietary rendering that is *not* in the spec | Alerts, footnotes, Mermaid, GeoJSON, maths, emoji, @mentions | github.com only |
| Pandoc Markdown | The most feature-complete dialect, aimed at publishing | Citations, definition lists, divs and spans, maths, cross-references | Academic writing, book pipelines, `pandoc` |
| MultiMarkdown | Early academic-leaning extension of the original | Metadata, footnotes, tables, cross-references | Long-form and print workflows |
| PHP Markdown Extra | The first widely used extension set | Tables, definition lists, footnotes, attribute blocks | Older PHP CMSs, kramdown lineage |
| MDX | Markdown with JSX — components inside prose | Import and render UI components in a document | Docusaurus, Next.js docs, Astro, design systems |
| MyST | Markdown for scientific and technical publishing | Directives, roles, executable content, Sphinx compatibility | Jupyter Book, Python documentation |
| R Markdown / Quarto | Literate computing — code chunks that execute | Executable blocks, figure and table numbering, multi-format output | Data science reporting, `.rmd` and `.qmd` files |
| Obsidian flavour | CommonMark plus knowledge-base conventions | `[[wiki links]]`, embeds, callouts, block references | Obsidian vaults and the many tools copying them |

The portability rule

Write to CommonMark plus GFM tables and you will render correctly essentially everywhere. Every feature beyond that is a deliberate trade: you are buying expressiveness in one renderer and paying for it the day the file moves. If a document has to survive a move — to a package registry, a mirror, a docs build, or a model's context window — keep it boring.

## 06 / How-to — Opening 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](https://code.visualstudio.com/), 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](https://www.barebones.com/products/bbedit/), which has handled Markdown since roughly the beginning.
- **Dedicated writing apps:** [iA Writer](https://ia.net/writer), [Typora](https://typora.io/), [Obsidian](https://obsidian.md/), [Zettlr](https://www.zettlr.com/) — 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](https://stackedit.io/), [Dillinger](https://dillinger.io/), [HackMD](https://hackmd.io/) — 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

##### VS Code

Built-in preview, outline view, and a large extension ecosystem: markdownlint for rules, Markdown All in One for tables and shortcuts, Mermaid preview for diagrams.

##### JetBrains IDEs

Native split preview with diagram and PlantUML support. Markdown files are first-class citizens in the project tree.

##### Vim / Neovim

`markdown-preview.nvim` for live browser preview; `render-markdown.nvim` for in-buffer rendering. Or just read it raw, which is the point.

## 07 / Conversion — Converting 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](https://pandoc.org/), 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.

```
# Markdown → PDF (needs a LaTeX engine, or use --pdf-engine=weasyprint)
pandoc notes.md -o notes.pdf

# Markdown → Word
pandoc notes.md -o notes.docx

# Markdown → Word, using your company template for styles
pandoc notes.md --reference-doc=house-style.docx -o notes.docx

# Markdown → standalone HTML with a table of contents
pandoc notes.md -s --toc -o notes.html

# Markdown → PowerPoint (each H2 becomes a slide)
pandoc deck.md -o deck.pptx

# Word → Markdown, extracting images to a folder
pandoc report.docx -t gfm --extract-media=./img -o report.md

# HTML → Markdown
pandoc page.html -f html -t gfm -o page.md

# Batch: every .md in a folder → PDF
for f in *.md; do pandoc "$f" -o "${f%.md}.pdf"; done
```

### Without installing anything

| Conversion | Fastest no-install route | Watch out for |
|---|---|---|
| MD → PDF | Render it (VS Code preview, browser viewer, gist) then print to PDF | Page breaks and margins are whatever the renderer's CSS says |
| MD → Word | Google Docs: File → Open → Upload the `.md`, then File → Download → `.docx` | Code blocks and tables usually survive; footnotes and maths often do not |
| MD → Google Doc | Upload to Drive, right-click → Open with Google Docs. Import and export of Markdown are on by default | Enable Tools → Preferences → Markdown for paste-as-Markdown behaviour |
| MD → HTML | `npx marked -i in.md -o out.html`, or any web renderer's export | You get a fragment, not a styled page — add your own CSS |
| MD → slides | Paste into Marp, Slidev or reveal.js — all read Markdown natively | Slide breaks are convention-based; check the tool's separator |
| Word → MD | Google Docs: File → Download → Markdown (.md) | Tracked changes and comments are dropped entirely |
| HTML → MD | Turndown (JS) or any browser-based converter | Nested layout tables and inline styles convert badly — expect cleanup |
| PDF → MD | A document-extraction tool; there is no clean answer, PDFs discard structure | Reading order, columns and tables are frequently wrong. Always check |

Direction matters

Converting *from* Markdown is lossless in spirit — you are adding presentation to structure. Converting *to* Markdown is lossy by definition — you are throwing presentation away to recover structure, and anything that was only ever visual formatting will not come back. Decide which format is your source of truth and convert one way, always. Round-tripping a document between Word and Markdown will slowly destroy it.

## 08 / Tooling — Editors, 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](https://obsidian.md/) — local-first knowledge base built directly on a folder of `.md` files. No lock-in: the vault is just files on disk.
- [Typora](https://typora.io/) — seamless live preview; the syntax transforms as you type rather than sitting in a second pane.
- [iA Writer](https://ia.net/writer) — minimal, focus-oriented editing across macOS, iOS, Windows and Android.
- [Zettlr](https://www.zettlr.com/) — open source, academic bent, with citation support via Zotero and Pandoc export built in.
- [MarkText](https://marktext.app/) — open source, cross-platform, real-time preview.
- [Logseq](https://logseq.com/) — outliner-style note-taking on plain Markdown files.

#### Browser-based editors and viewers

- [StackEdit](https://stackedit.io/) — full-featured in-browser editor with sync and export.
- [Dillinger](https://dillinger.io/) — clean live-preview editor with one-click export to HTML and PDF.
- [HackMD](https://hackmd.io/) — real-time collaborative Markdown, useful for meeting notes and RFCs.
- [CommonMark Dingus](https://spec.commonmark.org/dingus/) — the reference implementation's playground; shows the AST alongside the HTML. The best debugging tool there is.
- [Babelmark 3](https://babelmark.github.io/) — runs one snippet through dozens of implementations at once so you can see exactly where they disagree.

#### Parsers and libraries

| Library | Language | Notes |
|---|---|---|
| [cmark](https://github.com/commonmark/cmark) | C | CommonMark reference implementation; [cmark-gfm](https://github.com/github/cmark-gfm) is GitHub's fork with the GFM extensions |
| [markdown-it](https://github.com/markdown-it/markdown-it) | JavaScript | CommonMark-compliant, plugin-driven, the default choice for custom pipelines |
| [marked](https://marked.js.org/) | JavaScript | Fast and tiny; has a CLI, which makes it handy for one-off conversion |
| [remark](https://remark.js.org/) / [unified](https://unifiedjs.com/) | JavaScript | Turns Markdown into a syntax tree you can transform programmatically — the right tool for large-scale content migrations |
| [goldmark](https://github.com/yuin/goldmark) | Go | CommonMark-compliant and extensible; powers Hugo |
| [Python-Markdown](https://python-markdown.github.io/) / [markdown-it-py](https://github.com/executablebooks/markdown-it-py) | Python | The two mainstream Python options; the latter is a port of markdown-it and is CommonMark-compliant |
| [pulldown-cmark](https://github.com/raphlinus/pulldown-cmark) | Rust | Pull-parser design, very fast, used widely in Rust tooling |
| [Turndown](https://github.com/mixmark-io/turndown) | JavaScript | The other direction: HTML into Markdown |

#### Linting and quality

- [markdownlint](https://github.com/DavidAnson/markdownlint) — the standard rule set for structural consistency; available as a CLI, a VS Code extension and a CI action.
- [Vale](https://vale.sh/) — prose linting against a style guide. Enforces terminology and tone, not just syntax.
- [Prettier](https://prettier.io/) — formats Markdown as well as code; ends arguments about list markers and table alignment permanently.
- [lychee](https://github.com/lycheeverse/lychee) — fast link checker for Markdown; run it in CI so your documentation's links stay honest.

#### Publishing from Markdown

- [Hugo](https://gohugo.io/), [Jekyll](https://jekyllrb.com/), [Eleventy](https://www.11ty.dev/), [Astro](https://astro.build/) — static site generators that read a folder of `.md` and emit a website.
- [Docusaurus](https://docusaurus.io/), [MkDocs](https://www.mkdocs.org/), [VitePress](https://vitepress.dev/), [Starlight](https://starlight.astro.build/) — documentation sites with search, versioning and navigation out of the box.
- [Quarto](https://quarto.org/), [Jupyter Book](https://jupyterbook.org/) — executable documents for analysis and scientific publishing.
- [Marp](https://marp.app/), [Slidev](https://sli.dev/), [reveal.js](https://revealjs.com/) — slide decks written as Markdown files.
- [Pandoc](https://pandoc.org/) — everything else: books, papers, print, ebooks, Word, LaTeX.

## 09 / The turn — Markdown 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*.

| File | Read by | Loaded | Job |
|---|---|---|---|
| README.md | Humans | When someone opens the repo | Orientation: what this is, how to start, how to contribute |
| [AGENTS.md](https://agents.md/) | Coding agents, cross-vendor | Every session | Operating instructions: build, test, conventions, boundaries |
| [CLAUDE.md](https://code.claude.com/docs/en/memory) | Claude Code | Every session | Same job, Claude's native filename, with scoping and imports |
| [SKILL.md](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) | Claude | Only when relevant | A packaged procedure the agent loads on demand |
| [llms.txt](https://llmstxt.org/) | Models reading your website | At retrieval time | A curated map of what matters on the site, in Markdown |

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.

Read next

Each of those formats, why agents converged on plain text at all, what Cloudflare's *Markdown for Agents* changed in February 2026, and how to build a context layer for a business: [**Markdown for AI: why .md files became the context layer for agents**](https://auxfirst.com/news/markdown-for-ai.html).

### 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 / Craft — House 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.

##### One H1 per file

The document title. Every other heading is H2 or below, and levels are never skipped. Skipping H2 to reach H3 breaks outlines, anchors and screen readers.

##### Hyphens for bullets

Pick `-` and never mix. Same for emphasis: asterisks, always. Consistency here is worth more than any individual choice.

##### Lazy numbering

Write `1.` for every ordered item. Renderers count for you and reordering never leaves you with 1, 2, 2, 3.

##### One sentence per line

Optional but transformative for review: diffs then show the sentence that changed rather than a reflowed paragraph. Renderers join the lines anyway.

##### Reference links for heavy linking

Keeps prose readable in source form and gives you one place to update a URL that appears six times.

##### Always tag code fences

```` ```bash ````, not bare backticks. Highlighting, copy buttons and doc tooling all depend on it.

##### Alt text, every image

If the image carries meaning, describe it. If it is decorative, say so with empty alt text deliberately.

##### Blank lines around blocks

Before and after every heading, list, table and fence. Most "why won't this render" bugs are a missing blank line.

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 / Debugging — Why your Markdown isn't rendering

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

My heading shows up as text with a hash in front

There is no space after the hashes. `#Heading` is literal text; `# Heading` is a heading. CommonMark requires the space. Original Markdown did not, which is why old files sometimes render differently in modern tools.

My list is rendering as one paragraph

Missing blank line before the list. A list that starts immediately after a line of prose gets absorbed into that paragraph by most renderers. Add a blank line above it.

My line breaks disappeared

Single newlines are ignored inside a paragraph — that is by design. Use two trailing spaces, a trailing backslash, or a blank line for a new paragraph. Some tools (GitHub comments, chat apps) break on single newlines, which is why the same text behaves differently in an issue than in a `.md` file in the same repository.

My table isn't a table

Tables are a GFM extension, so first check the renderer supports them. Then check the separator row exists directly under the header (`| --- | --- |`) and that the cell count matches the header row. And put a blank line above the table.

My nested list flattened out

Indentation is wrong or mixes tabs with spaces. Use two or four spaces consistently. Under an ordered list, nested content typically needs to align with the text of the parent item, not the number.

Underscores in my filenames turned into italics

Wrap the identifier in backticks as inline code — which you should have done anyway — or escape with backslashes. This is why asterisks are the safer emphasis marker: underscores mid-word are ambiguous.

My HTML was stripped

The renderer is sanitising. GitHub filters dangerous tags after conversion; many CMSs strip HTML entirely. Assume raw HTML is a local optimisation, not a portable feature.

It renders on GitHub but not on our docs site

You are using a GitHub-renderer feature that isn't in the GFM spec: alerts, Mermaid diagrams, footnotes, maths, emoji shortcodes, issue references. All of those are proprietary rendering, not specification. See flavours.

My front matter is printing at the top of the page

The tool rendering the file does not know about front matter — it is not part of any Markdown spec, only a convention that generators implement. Either the delimiters are wrong (it must be `---` on the very first line, no blank line above) or the renderer simply doesn't strip it.

The universal debugging move

Paste the snippet into the [CommonMark Dingus](https://spec.commonmark.org/dingus/) and then into [Babelmark](https://babelmark.github.io/). The first tells you what the specification says should happen. The second tells you what twenty implementations actually do. If they agree and your tool disagrees, the bug is in your tool's configuration — not in your Markdown.

## 12 / Glossary — The vocabulary

| Term | Meaning |
|---|---|
| ATX heading | The `#` style of heading, named after Aaron Swartz's atx format |
| Setext heading | The underlined style, using `===` or `---` beneath the text. Two levels only |
| Fenced code block | Code delimited by three backticks or tildes, optionally with a language identifier |
| Front matter | A YAML, TOML or JSON metadata block at the top of a file, fenced by `---`. Not part of Markdown itself |
| Flavour / dialect | A specific implementation's version of Markdown, including whichever extensions it supports |
| Extension | Syntax beyond the core spec — tables, footnotes, task lists, callouts |
| Renderer / parser | The software that turns Markdown source into HTML or another output format |
| AST | The abstract syntax tree a parser builds before rendering. Tools like remark let you transform it directly |
| Round-trip | Converting out of Markdown and back again. Lossy; avoid as a workflow |
| Wiki link | `[[Double bracket]]` internal links — an Obsidian-family convention, not standard Markdown |
| Progressive disclosure | Loading only the part of a document that the current task needs — the organising principle of the SKILL.md format |

## 13 / Library — Every link worth keeping

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

#### Specifications and standards

- [Markdown — Daring Fireball](https://daringfireball.net/projects/markdown/) — the original project page, still online, still version 1.0.1.
- [Markdown Syntax Documentation](https://daringfireball.net/projects/markdown/syntax) — Gruber's original syntax description, including the philosophy section that explains every subsequent decision.
- [Markdown Basics](https://daringfireball.net/projects/markdown/basics) — the short before/after tour.
- [Introducing Markdown (March 2004)](https://daringfireball.net/2004/03/introducing_markdown) — the original announcement post.
- [CommonMark Spec](https://spec.commonmark.org/) — all versions; 0.31.2 is current as of this writing.
- [CommonMark quick reference](https://commonmark.org/help/) — a ten-minute interactive tutorial, the best thing to send a colleague.
- [CommonMark Dingus](https://spec.commonmark.org/dingus/) — live parser with AST view.
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) — version 0.29-gfm, the five official extensions.
- [RFC 7763 — The text/markdown Media Type](https://www.rfc-editor.org/rfc/rfc7763.html) — the formal registration.
- [RFC 7764 — Guidance on Markdown](https://www.rfc-editor.org/rfc/rfc7764.html) — design philosophies, stability strategies, variant registrations.
- [IANA Markdown Variants registry](https://www.iana.org/assignments/markdown-variants/markdown-variants.xhtml) — the official list of declared dialects.
- [CommonMark discussion forum](https://talk.commonmark.org/) — where edge cases get argued out.

#### Platform documentation

- [GitHub — Basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) — the canonical reference for alerts, footnotes and task lists.
- [GitHub — Creating diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) — Mermaid, GeoJSON, TopoJSON and ASCII STL inside fenced blocks.
- [GitHub — Tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables) — alignment and escaping rules.
- [GitLab Flavored Markdown](https://docs.gitlab.com/ee/user/markdown.html) — GitLab's extension set, including its own diagram support.
- [Google Docs — Use Markdown](https://support.google.com/docs/answer/12014036?hl=en) — import, export, and paste-as-Markdown.
- [The Markdown Guide](https://www.markdownguide.org/) — the best general-purpose tutorial site, with per-tool compatibility notes.
- [Markdown cheat sheet](https://www.markdownguide.org/cheat-sheet/) — one page, print it.

#### Agent and AI formats

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

#### Tools worth bookmarking

- [Pandoc](https://pandoc.org/) and its [manual](https://pandoc.org/MANUAL.html) — the single most useful page in this entire list.
- [Babelmark 3](https://babelmark.github.io/) — compare implementations side by side.
- [Mermaid](https://mermaid.js.org/) and the [live editor](https://mermaid.live/) — diagrams as text inside Markdown.
- [markdownlint](https://github.com/DavidAnson/markdownlint) — rules and CI integration.
- [Vale](https://vale.sh/) — prose style enforcement.
- [MDX](https://mdxjs.com/) — components inside Markdown.
- [MyST](https://mystmd.org/) — structured technical and scientific authoring.
- [Quarto](https://quarto.org/) — executable documents, multi-format output.
- [Marp](https://marp.app/) — slide decks from a `.md` file.
- [Obsidian](https://obsidian.md/) — the most popular way to live inside a folder of Markdown files.

## 14 / FAQ — Short answers

What is an MD file?

A plain text document written in Markdown, a lightweight markup syntax created in 2004. Punctuation characters express structure — `#` for headings, `**` for bold, `-` for bullets — and a renderer converts them to HTML or another format. It opens in any text editor on any operating system.

How do I open an MD file?

Any text editor opens it as-is. To see it formatted, use VS Code's preview (`Ctrl`/`Cmd`+`Shift`+`V`), a Markdown app such as Obsidian or Typora, a browser extension, or the viewer on this page. On iPhone, the Files app shows it as text; a Markdown app renders it.

Is .md the same as .markdown?

Yes — identical content, different extension. `.md` won on brevity. You will also meet `.mdown`, `.mkd`, and specialised variants like `.mdx`, `.qmd` and `.rmd` that add capabilities on top.

Can I open an MD file in Word?

Word will open it as plain text, showing the syntax characters. For a properly formatted document, convert first — `pandoc notes.md -o notes.docx`, or upload to Google Docs and download as `.docx`.

Is Markdown a programming language?

No. It is a markup syntax — it describes structure, not behaviour. There are no variables, conditions or loops. It is closer to formatting conventions in email than to code.

What's the difference between Markdown and CommonMark?

CommonMark is Markdown, specified precisely. The 2004 original left many cases ambiguous, so implementations diverged. CommonMark defines the behaviour exactly, with hundreds of test cases. Most modern tools follow it.

Why do AI tools output Markdown?

Because it carries structure at almost no syntactic cost, it renders in most chat interfaces, and it is legible if it isn't rendered. The same properties make it the format of choice for instructing agents — see section 09.

Is Markdown good for SEO?

Markdown is a source format; search engines see the HTML it produces. What helps is the discipline it encourages: a clean heading hierarchy, real lists, descriptive link text and alt attributes. Those matter for both search crawlers and for models retrieving your content.

Do I need to learn all of it?

Headings, bold, italic, lists, links and code fences cover about 95% of real usage. That is roughly six characters of syntax and takes ten minutes. Everything else in this page is reference material for when you meet it.

## Sources — Where the specifics come from

- [Daring Fireball — Markdown](https://daringfireball.net/projects/markdown/) and [the syntax page](https://daringfireball.net/projects/markdown/syntax), for the original design, release dates and philosophy.
- [CommonMark Spec](https://spec.commonmark.org/), for version 0.31.2 and its publication date of 28 January 2024.
- [GitHub Flavored Markdown Spec 0.29-gfm](https://github.github.com/gfm/), for the five extensions and the CommonMark superset relationship.
- [GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax), for the alert types, footnote behaviour and diagram syntaxes.
- [RFC 7763](https://www.rfc-editor.org/rfc/rfc7763.html) and [RFC 7764](https://www.rfc-editor.org/rfc/rfc7764.html) (March 2016), for the media type and variant registry.
- [agents.md](https://agents.md/), for adoption figures, monorepo precedence, Linux Foundation stewardship and the sample file.
- [Claude Code documentation](https://code.claude.com/docs/en/memory), for CLAUDE.md scopes, imports, rules and size guidance.
- [Anthropic Agent Skills documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview), for the SKILL.md structure and the three loading levels.
- [llmstxt.org](https://llmstxt.org/) and [Answer.AI](https://www.answer.ai/posts/2024-09-03-llmstxt.html), for the llms.txt proposal and its date.
- [Google Docs Editors Help](https://support.google.com/docs/answer/12014036?hl=en), for Markdown import and export behaviour.
- [FileInfo](https://fileinfo.com/extension/md), 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.

---

Written by Emil Krzemiński, founder of auxfirst — https://auxfirst.com/about.html
More: https://auxfirst.com/llms.txt

© 2026 auxfirst agency · Agentic Experience Design