Context: Ask ChatGPT or Claude for a summary and you get asterisks and hashes back. That is markdown, and it is worth ten minutes of your attention, because it is the format every AI tool reads and writes most reliably.
Markdown is plain text with a few punctuation marks that mean something. A hash makes a heading. Two asterisks make bold. That is most of it.
Why it matters to you
- AI reads structure better than prose. A brief with real headings and lists gets a more accurate answer than the same information in three long paragraphs, because the shape tells the model what belongs with what.
- It costs less to feed to an AI. A PDF or a Word file has to be converted before a model can read it, and what comes out carries page furniture, layout scaffolding and stray line breaks. Markdown is the words plus a few punctuation marks, so the same document costs fewer tokens and the model spends its attention on your content rather than on wading through the wrapper.
- It exports to whatever you need. One markdown file becomes a PDF, a web page, a Word document or a set of slides. You write once and choose the format at the end, rather than maintaining the same content in three places.
- It survives the journey. Text copied out of a chat keeps its structure in Notion, Obsidian, GitHub, Slack and most note apps. Formatted Word text usually arrives as a mess.
- It will still open in a hundred years. A markdown file is a text file. No licence, no viewer, no version that stops being supported. Every proprietary format on your machine today is a bet that its owner is still around and still cares; plain text is not.
- You do not have to write it. Ask for the answer in markdown and you get it in markdown. Knowing the syntax is mostly so you can read what comes back, spot when the structure is wrong, and edit it with confidence.
The cheat sheet
What you type on the left, what it produces on the right. That is the whole language.
Headings
Syntax
# A heading
## A smaller heading
### Smaller stillResult
A heading
A smaller heading
Smaller still
Bold and italic
Syntax
**bold text**
*italic text*Result
bold text
italic text
Bulleted list
Syntax
- First item
- Second item
- Third itemResult
- First item
- Second item
- Third item
Numbered list
Syntax
1. First item
2. Second item
3. Third itemResult
- First item
- Second item
- Third item
Links
Syntax
[the Guild portal](https://ai-momentum.ai/portal/)Result
Quotes
Syntax
> Nothing in this file is wrong. It simply is not true any more.Result
Nothing in this file is wrong. It simply is not true any more.
Code
Syntax
Use the `summarise` prompt.
```
Name: Aurora Seltzer
Audience: trade buyers
```Result
Use the summarise prompt.
Name: Aurora Seltzer
Audience: trade buyersTables
Syntax
| Task | Owner |
| --- | --- |
| Draft the brief | Bella |
| Approve it | Simon |Result
| Task | Owner |
|---|---|
| Draft the brief | Bella |
| Approve it | Simon |
Checklists
Syntax
- [ ] Write the press release
- [x] Update the websiteResult
- ☐ Write the press release
- ☑ Update the website
Images
Syntax
Result
The image appears here. The words in the square brackets are the alt text: what a screen reader announces, and what shows if the image fails to load.
A dividing line
Syntax
---Result
Put together, it looks like this
A real note uses several of these at once. This is what a short meeting note looks like as you type it, and as it renders.
Syntax
## Supplier review, 14 August
Prices held for another quarter, so the packaging switch can wait.
- Cartons: no change until January
- Labels: 4% rise from October
- Pallets: still on backorder
- [x] Ask for the October price list
- [ ] Get a second quote on labels
- [ ] Decide on cartons by 30 SeptemberResult
Supplier review, 14 August
Prices held for another quarter, so the packaging switch can wait.
- Cartons: no change until January
- Labels: 4% rise from October
- Pallets: still on backorder
- ☑ Ask for the October price list
- ☐ Get a second quote on labels
- ☐ Decide on cartons by 30 September
Worth knowing, rarely needed
Markdown has extras that some tools support and others ignore: footnotes, strikethrough (~~like this~~), and definition lists. If something does not render where you paste it, that is why. The eleven above work almost everywhere.
What to read and write it in
A markdown file opens in anything, but these three make it pleasant on a Mac.
- Typora shows the formatting as you type rather than showing you the punctuation, so it feels like a normal word processor. It exports to PDF, Word and HTML from the File menu. A one-off licence, around 15 US dollars.
- Marked 3 watches a file you are editing elsewhere and shows a live preview alongside, with export and word-count tools. Useful if you write in one app and want to see the finished shape in another.
- TextEdit is already on your Mac and will do. Set Format to Make Plain Text first, or it saves rich text and the markdown stops being markdown.
Whatever you use, save the file with a .md ending. That is what tells everything else how to read it.