Markdown explained: the simple file format that AI speaks

Markdown is a way of writing formatted text using only plain characters. A # makes a heading, **stars** make bold, and a dash makes a bullet point. It was created in 2004 by John Gruber so that a document would be easy to read as plain text and easy to turn into a web page. Twenty years later it has become the format AI assistants read and write by default.

Why AI uses Markdown

Have you noticed that AI answers come with headings, bullet points and bold text? Behind the scenes, the AI is writing Markdown, and the app turns it into formatting.

Markdown suits AI for three reasons:

• It’s plain text. Models read and write text, so there’s nothing to convert.
• Structure is visible. A heading is marked with #, so the AI can see how a document is organised.
• It’s everywhere. A large share of the documentation, notes and README files on the internet is Markdown, so models have seen an enormous amount of it.

This works in both directions. If you write your notes and instructions in Markdown, AI understands their structure better.

The whole syntax in one table

This covers almost everything you’ll use.

You type	You get
# Title	A big heading
## Section	A smaller heading
**bold**	bold
*italic*	italic
- item	A bullet point
1. item	A numbered list
[text](https://example.com)	A link
	An image
> quote	An indented quote
`code`	code in a fixed-width font
---	A horizontal line

Blank lines separate paragraphs. That’s the core of it.

A full example

Here’s a small Markdown file as you’d type it:

# Weekend plan

## Saturday
- Buy groceries
- **Call the bank** before noon
- Finish the [tax form](https://example.com/form)

## Sunday
1. Sleep in
2. Cricket at 4

> Don't forget the charger.

Even before it’s converted to anything, you can read it. That was the original goal.

Tables and code blocks

Two more pieces are worth knowing because AI uses them constantly.

A table is drawn with pipes and dashes:

| Game     | Players |
|----------|---------|
| Keycraft | 1       |
| Kaiju    | 1 to 4  |

A code block is fenced with three backticks, which tells the reader that everything inside is code and should be left exactly as written. When an AI gives you something to copy, it’s almost always in a code block.

Where you’ll meet Markdown files

Markdown files end in .md. You’ll find them in a few common places.

• README.md. The front page of a project: what it is and how to use it. Each game in my arcade has a README, and the arcade turns that file into the game’s web page automatically.
• CLAUDE.md or AGENTS.md. A notes file for an AI coding assistant, with the rules of the project. I explain these in how to write a CLAUDE.md.
• Notes apps. Obsidian, Notion, Bear and many others store or export Markdown. My own Mac app, OneTrue, keeps every note as one Markdown file, so the notes will still open in any editor years from now.
• Blogs. This post is a Markdown file. Publishing it meant saving the file and pushing it to GitHub.
• Chat. You can type Markdown into many chat apps and AI assistants, and they’ll format it.

Why plain text beats a Word document

• It opens anywhere, on any device, in any text editor, forever. There’s no app to buy and no format to go out of date.
• It’s tiny. A long document is a few kilobytes.
• Changes are easy to track. Tools like Git and GitHub can show exactly which lines changed between versions.
• AI reads it perfectly. There’s no hidden formatting to confuse it.

Word documents and PDFs are better when the exact page layout matters, such as a printed form or a designed brochure. For notes, drafts, instructions and anything you’ll hand to an AI, Markdown is easier.

Try it in two minutes

1. Open any plain text editor. Notepad on Windows or TextEdit on a Mac will do (in TextEdit, choose Format, then Make Plain Text).
2. Type a heading with #, a few bullets with -, and one bold phrase.
3. Save it as notes.md.
4. Paste the contents into an AI assistant and ask it to tidy the structure. Notice that it answers in the same format.

To see it rendered, paste it into a free online Markdown viewer, or create a file on GitHub, which displays .md files formatted.

Small habits that help with AI

• Ask for Markdown output when you want to paste an answer into your notes: “Reply in Markdown with H2 headings.”
• Write your prompts with structure. A few headings like “Background”, “Task” and “Format” make long requests much clearer.
• Keep reusable instructions in a .md file. Paste it in at the start of a chat, or let your tools load it for you.

Markdown is one of the basic terms and file types worth knowing if you use AI. It takes ten minutes to learn, and you’ll use it every day after that.