Markdown Syntax -- A Quick Reference

Why Markdown?

Before we get into syntax, a quick word on why Markdown exists.

Writing in Word or Google Docs means your content is trapped in a proprietary format. Writing in HTML means you're fighting angle brackets every other word. Markdown sits in the middle: plain text you can read without rendering, that converts cleanly to HTML, PDF, or almost anything else.

It's the closest thing to a universal writing format we have. Once you know it, you'll use it everywhere — notes, documentation, blog posts, README files, GitHub comments, chat apps.

Headings

# H1 -- Page title
## H2 -- Section
### H3 -- Subsection
#### H4

Use # signs followed by a space. One # is the largest heading, six is the smallest. In practice, you'll mostly use ## and ###.

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

Renders as: italic, bold, bold and italic, strikethrough.

Lists

Unordered:

- Item one
- Item two
  - Nested item
  - Another nested
- Item three

Ordered:

1. First
2. Second
3. Third

The actual numbers don't matter — 1. 1. 1. renders as 1, 2, 3. But using real numbers makes the raw file easier to read.

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Hover text")

![Alt text](image.jpg)
![Alt text](image.jpg "Optional title")

The only difference between a link and an image is the ! at the front.

Code

Inline code uses backticks:

Use `git status` to check your working tree.

Code blocks use triple backticks, with an optional language for syntax highlighting:

```python
def hello():
    print("Hello, world")
```

Supported languages include python, javascript, bash, go, rust, json, yaml, toml, and many more.

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> Even multiple paragraphs.

This is a blockquote.

Tables

| Column A  | Column B  | Column C  |
|-----------|-----------|-----------|
| Cell 1    | Cell 2    | Cell 3    |
| Cell 4    | Cell 5    | Cell 6    |

Alignment is controlled by colons in the separator row:

| Left      | Center    | Right     |
|:----------|:---------:|----------:|
| text      | text      | text      |

Horizontal Rule

Three or more dashes, asterisks, or underscores on their own line:

---
***
___

Task Lists

Supported on GitHub, Notion, Obsidian, and most modern Markdown renderers:

- [x] Write the post
- [x] Add code examples
- [ ] Publish

• Write the post
• Add code examples
• Publish

Escaping

If you want to display a character that Markdown would normally interpret (like * or #), put a backslash before it:

\*This is not italic\*
\# This is not a heading

A Few Things to Watch

Blank lines matter. A paragraph requires an empty line between blocks. Without it, two lines of text merge into one paragraph.

Indentation matters. Nested lists require consistent indentation — usually two or four spaces.

Renderers differ. GitHub Markdown, CommonMark, and various static site generators have slightly different rules. The basics above work everywhere. Some extensions (tables, task lists, footnotes) depend on the renderer.

The Full Picture in One Place

That's it. The whole language fits on one page. That's the point.