Markdown in Five Minutes

Seven symbols. That's the whole language.

← All posts

What markdown is

Markdown is a way to add formatting — headings, bold, lists, links — to a plain text file. You type a few symbols. The symbols mean something. That's it.

You don't need special software. You can write markdown in Notepad, TextEdit, the Notes app on your phone, a Google Doc, or the terminal. Any place you can type text, you can write markdown. It was designed in 2004 by John Gruber specifically to be readable even if you never convert it to anything — the formatting symbols are so simple they don't get in the way of reading.

Every site on this page, every disposable software artifact, every AI skill, and every scene of the memoir was written in markdown. It's the default language of working with AI because both humans and AIs can read it without a translator.

The seven things you need

This is the complete list. There are more features, but you don't need them. These seven cover 95% of everything you'll write.

That's the language. # for headings, ** for bold, * for italic, - for bullets, 1. for numbered lists, []() for links, ` for code. Seven symbols.

A real example

Here's a complete markdown document — a weekly status update. This is the kind of thing you'd write instead of a meeting:

# Status Update — Week of April 7

## Done
- Finished the data migration for account KAS_US
- Fixed the broken query in the morning report
- Reviewed Alireza's PR on the segment loader

## In Progress
- QA on the new crosswalk load (80% done)
- Writing the runbook for the Infobase refresh

## Blocked
- **Staging environment is down** — can't test the load
  until infra restarts it. Ticket filed: DO-9821.

## Next Week
1. Ship the crosswalk if staging comes back
2. Start the Q2 Infobase evaluation
3. Meet with Sylvia about the warehouse resize

That's it. Readable as-is. Readable by an AI. Readable by any program that understands markdown. Readable in 50 years. No Word, no Google Docs, no formatting toolbar. Just text with seven symbols.

Where to write it

Anywhere. Literally anywhere you can type.

• The simplest option: open Notepad (Windows) or TextEdit (Mac, switch to plain text mode first: Format → Make Plain Text). Type your markdown. Save as whatever.md.
• A nicer option: VS Code (free, from Microsoft) understands markdown natively. It shows you a live preview of what your formatting looks like as you type. Open any .md file and press Ctrl+Shift+V (or Cmd+Shift+V on Mac) to see the preview.
• The AI option: tell Claude "write me a status update template in markdown." It will. Copy it into a file. Done.

The file extension is .md. That's all it takes to signal "this file contains markdown." But remember — the extension is a label, not a lock. A .md file is a .txt file with a different name. The bytes are the same.

Why AI loves markdown

When you give an AI a markdown file, it reads the structure instantly. The # signs tell it which lines are headings. The - signs tell it which lines are list items. The **bold** tells it what you emphasized. It doesn't have to guess at the structure — you declared it explicitly, in characters it can read directly.

Compare that to a Word document, where the structure is encoded in binary XML inside a zip archive. The AI has to unpack the archive, parse the XML, interpret the style definitions, and reconstruct what the document means. Every step is a place where meaning can be lost.

Markdown is the shortest path between what you mean and what the AI reads.

What about tables?

You'll run into tables eventually. They're the one slightly awkward thing in markdown, but they work:

| Name    | Role       | Status    |
|---------|------------|-----------|
| Alice   | Engineer   | On track  |
| Bob     | Designer   | Blocked   |
| Carol   | PM         | On track  |

Pipes (|) separate columns. Dashes (---) separate the header from the rows. It doesn't have to be perfectly aligned — most editors will clean it up for you, and AI will generate them perfectly aligned every time.

The conversion trick

Markdown converts to anything. One source file, many outputs:

• Markdown → HTML — that's what web pages are. This site was built this way.
• Markdown → PDF — for printing, sharing, and "please send me a document."
• Markdown → Word — for people who insist on .docx.
• Markdown → slides — yes, really. Tools like Marp turn markdown into presentations.

The command-line tool that does most of these conversions is called Pandoc. But you don't need to learn Pandoc. You can tell Claude "convert this markdown file to a PDF" and it will figure out the command for you.

The point is: write once in markdown, export to whatever format the recipient needs. You keep the source. They get the output. If they want changes, you edit the markdown and re-export. You never open Word.

The minimum viable knowledge

If you remember nothing else from this page, remember this:

Markdown isn't a skill you study. It's a habit you pick up. The first time you type # Status Update instead of opening Word and clicking the heading dropdown, you've already learned it. The rest fills in as you go.

← Back to posts