Structure is what AI actually reads
Before getting into syntax, it's worth understanding why Markdown has become
the native language of AI tools. When you send text to an LLM — whether as a
prompt, a document, or a knowledge file — it doesn't see formatting the way
a human does. It reads the raw characters. A heading marked with #
is recognisable as a heading. A list item starting with - is
recognisable as a discrete item. A section break marked with ---
signals a topic boundary.
Plain prose gives an LLM one long stream of words to reason about. Structured Markdown gives it a map. That's why the same content, written with headings and lists instead of paragraphs, consistently produces better summaries, more accurate extractions, and cleaner generated output. More on how AI tools read Markdown →
What is Markdown, and why bother?
Markdown is a way of writing formatted text using nothing but plain characters.
A # at the start of a line becomes a heading. Two asterisks around
a word make it bold. A dash at the start of a line becomes a
list item. That's really all there is to it.
The reason it matters now is that AI tools — ChatGPT, Claude, Copilot — already speak Markdown. When an AI writes you a structured response, it's almost always using Markdown under the hood. Learning to write it yourself means you can work with that output directly, move it between tools cleanly, and create content that stays readable everywhere.
The practical upside: A Markdown file is just a .txt file
with a different extension. It opens in any editor, works in any version control system,
and never becomes unreadable because an old app version can't open it.
Basic syntax you'll actually use
You don't need to memorise all of Markdown. Here are the building blocks that cover the vast majority of real writing.
Headings
Use one or more # characters at the start of a line. The number of
hashes sets the level — one hash for the main title, two for sections, three for subsections.
# Article title ## Section heading ### Subsection heading
Article title
Section heading
Subsection heading
For AI: Headings are how an LLM chunks your document. A model asked to summarise a section will use heading boundaries to define where that section starts and ends. Without them, it guesses — and often gets it wrong.
Bold and italic
Wrap text in double asterisks for bold, single asterisks for italic. These can be combined, but use them sparingly — emphasis loses meaning when it's everywhere.
This word is **bold**. This one is *italic*. This is ***both***.
This word is bold. This one is italic. This is both.
For AI: LLMs recognise **bold** as emphasis and
weight it accordingly when extracting key terms or generating answers. It's a light
signal, but a real one — especially useful for highlighting definitions and warnings.
Lists
Unordered lists use a dash. Ordered lists use a number followed by a period. Both work the same way — just indent two spaces to nest.
- First item - Second item - A nested item 1. Step one 2. Step two 3. Step three
- First item
- Second item
- A nested item
- Step one
- Step two
- Step three
For AI: Lists are one of the highest-value structures you can give an LLM. Discrete items are far easier to extract, count, and reason about than the same content buried in a paragraph. If you want an AI to enumerate requirements, steps, or options reliably — use a list, not prose.
Links
The pattern is: display text in square brackets, URL in round brackets immediately after — no space between them.
Read more at [markdownheaven.com](https://markdownheaven.com).
Horizontal rules
Three dashes on their own line (---) produce a horizontal rule — a
visual divider that signals a clear break between topics or sections.
Last paragraph of one topic. --- First paragraph of the next topic.
Last paragraph of one topic.
First paragraph of the next topic.
For AI: A --- is one of the clearest structural
signals you can give an LLM. It says: what follows is a different topic. Models
use it to define context windows when processing long documents — particularly
useful in knowledge files and system prompts.
Code
Backticks mark inline code. Three backticks on their own line open and close a code block. You can add a language name after the opening backticks for syntax highlighting.
Use the `print()` function.
```python
def greet(name):
print(f"Hello, {name}")
```Use the print() function.
def greet(name):
print(f"Hello, {name}")
For AI: Code blocks tell an LLM: treat this literally. The model won't paraphrase, reformat, or summarise content inside backtick fences — it copies it as-is. Essential for prompts, commands, and any content that must survive the round-trip unchanged.
Build an article, step by step
The best way to learn is to write something real. Start with a completely empty file —
call it my-article.md — and build it up in stages.
Step 1 — Add the structure first
Before writing a single sentence of content, put the headings in place. Think of them as chapter titles in a book outline. They don't need to be final — you'll revise them — but having them there stops you from writing yourself into a shapeless wall of text.
# How to Make the Perfect Cup of Coffee ## What you need ## Grinding the beans ## Brewing ## Common mistakes ## Final thoughts
Step 2 — Write the content
Fill in each section as prose. Don't worry about formatting while you write — add the bold, the lists, and the links in a second pass. Writing and formatting at the same time slows you down.
Step 3 — Format and add links
Go back through the article and add formatting where it genuinely helps the reader. Bold a key term when it's introduced. Turn a long list of items into an actual list. Add a link when you reference something the reader might want to visit.
## What you need You'll need **freshly roasted beans**, a grinder, and a brewer of your choice. The single most important variable is grind size — it affects extraction more than almost anything else. Essential equipment: - A burr grinder (blade grinders produce uneven particle sizes) - A scale — eyeballing doses leads to inconsistent results - A kettle with temperature control, ideally Read more about [coffee extraction ratios](https://example.com).
Step 4 — Preview it
A Markdown file looks like plain text in your editor. To see it rendered as it was meant to look — headings as headings, bold as bold — paste it into ShowMarkdown. It renders instantly, with no sign-up required. Useful for a quick sanity check before sharing or publishing.
Common mistakes
Most Markdown problems come down to a handful of patterns that trip people up repeatedly — especially when moving from a word processor where spacing is invisible.
Blank lines matter. In Markdown, a blank line between two blocks tells the parser they're separate elements. Without it, two lines of text merge into one paragraph, a heading and a list collide, or a code block refuses to render. When something looks wrong, add a blank line before and after it.
Forgotten space after the hash
#Heading won't render as a heading. The space after the hash is required:
# Heading.
Broken links
The most common link mistake is a space between the brackets and the parentheses:
[text] (url) won't work. It needs to be [text](url) with
no gap.
Indented code blocks by accident
If you indent a paragraph by four or more spaces, some Markdown parsers treat it as a code block. If you're seeing your text rendered in monospace unexpectedly, check for accidental indentation.
Smart quotes from word processors
If you draft in Word or Pages and paste into Markdown, "curly" quotes can cause issues
in code blocks and URLs. Stick to straight quotes (" and ')
inside any technical content.
The tools that make it effortless
Writing Markdown is only half the job. Getting it into the right place — a Word document, a rendered page, a clean AI-ready file — is where most of the friction actually lives. These tools handle that part.