What Is Markdown? A 2026 Guide (Plus Why Every AI Speaks It)

Twenty years after John Gruber sketched it on a napkin and published it on his blog, markdown has quietly become the format that every writing surface speaks. Here’s what it is, the full cheat sheet, and why every large language model on earth defaults to outputting it.

TL;DR

• Markdown is a plain-text format for writing structured documents. It was created by John Gruber in 2004.
• It uses a handful of punctuation marks (#, *, -, []()) to indicate headings, emphasis, lists, and links.
• The file extension is .md. The whole spec fits on one page.
• Every modern LLM — ChatGPT, Claude, Gemini, Llama — outputs markdown by default because it’s the lowest common denominator that preserves structure.
• The five places markdown is now infrastructure: ChatGPT, Notion, GitHub, Slack, Discord.
• The next layer on top of markdown is turning it into a designed PDF — which is what mdclaudy does.

What is markdown, in 200 words

Markdown is a lightweight markup language for formatting plain-text documents. It was created by John Gruber in 2004, with technical input from Aaron Swartz, and published as a specification on daringfireball.net. The goal was a syntax so unobtrusive that an unrendered markdown file still reads as a clean text document.

A markdown file uses ordinary punctuation to indicate structure. A pound sign at the start of a line is a heading. An asterisk pair is italic. A dash and a space is a bullet. Square brackets followed by parentheses is a link. The file extension is .md or .markdown. Any text editor can open it.

A markdown renderer — a parser like markdown-it, CommonMark, or Pandoc — converts the plain text into rendered output: HTML for the web, PDF for print, DOCX for Word, EPUB for e-readers. The same .md file can produce all of them. That portability is the entire reason markdown won.

The complete markdown cheat sheet

Below is every syntax mark you need to write 99% of markdown documents. Copy any of them into a markdown-aware editor — GitHub, Obsidian, mdclaudy, VS Code — and you’ll see the rendered output.

That’s effectively the whole language. You can learn markdown in an afternoon, and the same file you write today will render in a tool that hasn’t been invented yet — because the format is plain text underneath.

Why every LLM outputs markdown by default

Open ChatGPT, Claude, Gemini, or any open-weight model. Ask it anything substantive. The response will come back with headings, bullets, bold terms, and code blocks. That output is markdown. The reason isn’t aesthetic — it’s structural, and it has three causes.

1. The training data is mostly markdown

Large language models are trained on enormous corpora scraped from the web. The structured-text portion of that corpus — the part where the text has hierarchy, lists, code, links — is overwhelmingly markdown. GitHub README files. Stack Overflow answers. Reddit posts. Hacker News comments. Technical blogs. Documentation sites. Notion exports. Discord messages. When a model learns “a good answer to a technical question looks like this,” the shape it’s absorbing is markdown.

2. Markdown preserves structure cheaply

A model generating text needs to convey hierarchy without burning tokens on syntax. ## Heading is two characters of scaffolding for a heading. <h2>...</h2>is nine. Bullets in markdown are one dash; in HTML they’re seven characters of opening and closing tags. Across a long answer, markdown is dramatically cheaper to emit, which means it’s what post-training optimization converges toward.

3. Markdown renders nearly everywhere

The surface displaying the model’s output isn’t the model’s problem — but the choice of format determines whether the output looks right. Markdown renders correctly in ChatGPT’s web UI, Claude.ai, Cursor, Slack, terminals via glow, IDEs, mobile apps, and dozens of third-party wrappers. HTML renders correctly in browsers and nowhere else. The safe default is markdown, and that’s what models learn to emit.

The five places markdown is now infrastructure

Markdown stopped being a developer convenience in the late 2010s. By 2026 it’s the substrate underneath every major writing surface. Here are the five most consequential.

1. ChatGPT (and every AI assistant)

ChatGPT, Claude, Gemini, Perplexity, Cursor, and every wrapped product on top of them speaks markdown both ways: it accepts markdown as input and emits markdown as output. The model never sees rendered text — it sees the tokens. That’s why a markdown table you paste into a chat is understood semantically, not just visually.

2. Notion

Notion presents itself as a block editor, but underneath every page is markdown-equivalent structure: headings, lists, code blocks, callouts. Notion accepts markdown shortcuts (##, **, -) as you type, and exports to .md from any page menu. The whole product is a designer wrapped around a markdown editor.

3. GitHub

Every README, issue, pull request, comment, and wiki page on GitHub is markdown. GitHub Flavored Markdown(GFM) — markdown plus tables, task lists, strikethrough, and autolinks — is now the de-facto standard the rest of the ecosystem references. If you’ve written software in the last decade, you’ve written markdown.

4. Slack

Slack supports a subset of markdown — bold, italic, code, links, blockquotes, lists — though it parses them through its own mrkdwn-flavored renderer, not pure CommonMark. The end result is the same: typing *bold*in Slack produces bold text. Discord’s syntax is nearly identical.

5. Discord

Discord supports a more complete markdown subset than Slack — including spoilers (||spoiler||) and underline (__under__). A generation of writers learned to italicize on Discord before they ever opened a Word document.

How to write markdown (a 60-second tutorial)

If you’ve never written markdown before, here’s the shortest possible path to a working document. Open any text editor and save a new file as hello.md. Then type:

# My first markdown document

This is a paragraph. It can have *italic* or **bold** words.

## A list of things

- The first thing
- The second thing
- The third thing

## A link and an image

Read more at [the markdown spec](https://daringfireball.net/projects/markdown/).

![A cat](cat.jpg)

> A blockquote at the end, because every essay deserves one.

Open the file in GitHub (drag it into a gist) or paste it into mdclaudy or Obsidian and you’ll see it rendered. That’s the entire workflow: type, save, render.

Markdown as input vs. output for AI

There are two distinct cases for markdown in an AI context, and confusing them is the most common mistake newcomers make.

Markdown as input. When you paste markdown into ChatGPT or Claude, the model parses it semantically. A heading is treated as a section break. A list is treated as items in a collection. A code block is treated as code. This is how well-structured prompts get well-structured answers.

Markdown as output.When the model writes back to you, it’s emitting markdown — but the surface you’re reading on may or may not render it. ChatGPT’s web UI does. Copy-paste into a Word document does not. Copy-paste into a Slack DM does partially. If you want the model’s output to land as a finished document, you need a renderer in the loop.

The next layer: markdown as a designed document

Markdown is excellent for capturing structure. It is, by design, indifferent to presentation. That’s the bargain: the format is portable because it doesn’t prescribe how anything looks. Headings are headings; the renderer decides what a heading is rendered as.

For most uses this is a feature. For one specific case — when you need to hand someone a finished document — it’s a problem. A markdown file isn’t a deliverable. A rendered PDF is. Bridging the gap usually means one of three things: learning Pandoc and LaTeX, accepting an ugly browser-print export, or copy-pasting into Word.

mdclaudy is our attempt at a fourth path: a markdown editor that ships your writing through fifteen hand-designed PDF templates — proposal, whitepaper, research paper, manuscript, résumé, editorial, more. You write markdown, you pick a template, you get a PDF that looks like it came out of a design studio. AI sits in the margins for ask, rewrite, and continue, if you want it.

A short history of markdown

John Gruber wrote markdown in 2004 to scratch his own itch: publishing essays on his blog without typing HTML by hand. He collaborated with Aaron Swartz on syntax decisions. The original Markdown.pl Perl script and the spec were published together. Both are still available on daringfireball.net.

The format spread through programmer culture first — Stack Overflow adopted it in 2008, GitHub in 2009 — and then leaked outward. Daring Fireball didn’t update the spec to handle the edge cases the wider ecosystem ran into, so two stabilization efforts emerged. CommonMark (2014) is a precise, testable specification. GitHub Flavored Markdown is CommonMark plus useful extensions. The Markdown Guide and Wikipedia document the resulting ecosystem in detail.

When to use markdown (and when not to)

Use markdown when:you’re writing prose, documentation, notes, READMEs, blog posts, technical specs, essays, academic drafts, or anything you want to render to multiple formats later. Use it when you want the file to outlive the tool. Use it when an AI assistant is somewhere in your loop.

Don’t use markdown when:you need precise visual layout (Figma, InDesign), real-time multi-cursor collaboration on prose (Google Docs), or formats markdown can’t express natively — bibliographic citations, complex tables of contents, multi-column layouts, signed PDFs. For most of those there’s a markdown plus a rendereranswer (Pandoc, mdclaudy, Quarto), but the bare markdown spec doesn’t cover them.

Frequently asked questions

Keep reading

• Markdown to PDF: the complete guide — the hub post that links to every export route.
• Markdown vs HTML — the full side-by-side comparison.
• Markdown tables: the complete syntax guide — the one bit of syntax most writers get wrong.
• 15 markdown PDF templates — what a designed document looks like on top of a .md file.
• AI markdown editors compared — the editors that lean into the markdown-plus-LLM pattern.