Markdown is a set of plain-text conventions that a converter turns into formatting. You type **done** and the reader sees done. The whole core syntax fits on one page, which is the point of this one: keep it open while you write.
The tables below cover what a document, report or book uses. Anything marked "depends on the tool" is not part of the original syntax, and editors handle it differently.
What is the basic Markdown syntax?
| You type | You get | Notes |
|---|---|---|
# Title | A level 1 heading | One per chapter or document |
## Section | A level 2 heading | The main sections |
### Subsection | A level 3 heading | Use sparingly |
**bold** | bold | Two asterisks each side |
*italic* | *italic* | One asterisk, or underscores |
***both*** | *both* | Three asterisks |
` code ` | code | Inline, in a monospace face |
| A blank line | A new paragraph | The rule people forget |
Headings need a space after the #. #Title is a paragraph in most converters, not a heading. And keep the levels in order: a ### straight under a # confuses the outline and any table of contents built from it. Headings in Markdown explains why.
How do you write lists in Markdown?
- A bullet
- Another bullet
- A nested bullet (indent two spaces)
1. First step
1. Second step
1. Third stepNumbered lists renumber themselves in most converters, so 1. on every line is fine and saves renumbering when you insert a step. Leave a blank line before a list, or some editors will glue it onto the paragraph above.
How do you add links and images?
| You type | You get |
|---|---|
[bukpress](https://buk.press) | A link with that text |
<https://buk.press> | The address itself as a link |
 | An image, with alt text |
 | An image from a URL |
The text in square brackets of an image is the alt text: what a screen reader says and what shows if the image fails to load. Write it as a short description, not a filename. For images that have to look sharp in a PDF, images in Markdown that still look sharp has the sizes.
How do you make a table in Markdown?
| Chapter | Words | Pages |
|---|---:|---:|
| Introduction | 1,200 | 3 |
| Getting started | 4,500 | 11 |- The second line is required. Without the dashes, it is not a table.
- Colons set the alignment:
:---left,:---:centre,---:right. Right-align columns of numbers. - The pipes don't have to line up. Lining them up only makes the source easier to read.
- Tables are an extension (GitHub Flavored Markdown), but nearly every modern tool supports them.
Long tables are where PDFs go wrong. Markdown tables that survive the page break covers what happens when one crosses a page.
How do you add code, quotes and rules?
```python
print("A fenced code block, with a language name")
```
> A block quote. Start each line with >.
---The language name after the opening backticks turns on syntax highlighting where the tool supports it. Code blocks in a PDF deals with long lines running off the page.
Three hyphens on their own line are a horizontal rule in standard Markdown. Some tools give them another job, which is the next section.
Which syntax depends on the tool?
These are the parts that change between editors and converters. Check them before you write 40 pages that rely on them.
| Feature | Common syntax | What varies |
|---|---|---|
| Page break | Raw HTML or a tool-specific marker | Standard Markdown has none |
| Line break | Two spaces at line end, or a backslash | Some tools treat one Enter as a break |
| Footnotes | Text[^1] and [^1]: Note | Not in core Markdown; many tools print it as text |
| Task lists | - [ ] To do | GitHub and note apps only |
| Strikethrough | ~~gone~~ | An extension, widely supported |
| Raw HTML | <div> and friends | Some tools render it, some strip it |
Line breaks cause the most confusion. In standard Markdown a single Enter does nothing: the two lines join into one paragraph. Why Markdown eats your line breaks explains the rule and the workarounds. For page breaks, how to control page breaks in Markdown lists the syntax per tool, and footnotes and endnotes covers the alternatives when footnote syntax isn't supported.
How does bukpress read this syntax?
bukpress turns a Markdown file into a typeset PDF, and it settles the "depends on the tool" rows this way:
---on its own line is a page break, not a rule.----(four or more hyphens) is a printed divider between sections.___is a plain thin rule, useful as a fill-in line in a workbook.- Every
#heading starts a new page, so a chapter never begins at the bottom of one. - One Enter is a real line break, so poetry and addresses keep their lines.
- A table that runs past the bottom of a page repeats its header row on the next.
- Raw HTML is stripped, so stick to Markdown.
The editor has the same reference built in, with an insert button for each entry. The Free plan exports PDFs of up to 40 pages, 20 a month, with no watermark; see pricing for the rest.
What should you do next?
Keep the first table beside you for a week of writing; after that you will rarely need it. Then test the tool-dependent rows in the editor you actually use, with a page break, a long table and a two-line address, before you write the whole document around them.
Common questions
Is there one official Markdown syntax?
There are several flavours. John Gruber's original 2004 description is the base, CommonMark is a stricter specification of it, and GitHub Flavored Markdown adds tables, task lists and strikethrough. The basics in the first table work everywhere.
How do I make text bigger in Markdown?
Use a heading level. Markdown has no font-size syntax; the size of each heading level is set by the tool or its theme.
How do I add a blank line in Markdown?
A blank line between two paragraphs is already a paragraph break. Several blank lines in a row usually collapse into one, so extra space has to come from the tool's spacing settings or a page break.
Can I underline text in Markdown?
Not in standard Markdown. Underlines are usually read as links, so most writers use italic or bold for emphasis instead.