Markdown syntax: a quick guide

Markdown is a plain-text syntax that turns readable source into formatted output. You write with a few punctuation conventions, and a converter renders headings, emphasis, links, and lists. The appeal is that the source stays legible even before rendering, which is why README files, issue trackers, chat apps, and static site generators all speak it. This guide covers the syntax you will use daily, with the raw markdown shown for each case so you can copy and adapt.

Headings

Headings use # characters at the start of a line. One # is the top level, and each additional # drops one level, down to six.

# Page title
## Section
### Subsection

Put a space after the # characters and a blank line before the heading. Skipping the space is the most common reason a heading fails to render.

Bold and italic

Wrap text in one marker for italic and two for bold. Both * and _ work.

*italic* or _italic_
**bold** or __bold__
***bold italic***

Prefer * for emphasis inside words, because _inside_words_ does not always render as emphasis in every parser.

Links

A link is bracketed text followed by a parenthesized URL. You can add an optional title in quotes.

[Glunty tools](https://glunty.com "Small tools, no nonsense")

Bare URLs are not automatically clickable in strict parsers, so wrap them in angle brackets like <https://glunty.com> when you want the raw address to render as a link. Once you have a document full of markdown links, the Markdown to HTML converter turns the whole thing into ready-to-paste HTML.

Images

Images use the same syntax as links with a leading !. The bracketed text becomes the alt attribute, which matters for accessibility and for readers whose images fail to load.

![A red fox in snow](/images/fox.jpg "Winter fox")

Write real alt text. “image” or an empty string tells a screen reader nothing.

Lists

Unordered lists start each item with -, *, or +. Ordered lists use a number followed by a period. Indent by two spaces to nest.

- First item
- Second item
  - Nested item
- Third item

1. Step one
2. Step two
3. Step three

The actual numbers you type for ordered lists do not matter to the parser. Writing 1. on every line still renders as 1, 2, 3, which makes reordering painless.

Blockquotes

Prefix a line with > to quote it. Stack the marker to nest quotes, and keep the marker on blank lines to continue a single quote across paragraphs.

> This is a quote.
>
> Still the same quote, second paragraph.
>> A nested quote.

Inline code and fenced code blocks

Wrap short snippets in single backticks for inline code, like git status. For multi-line code, fence the block with three backticks. Add a language name after the opening fence to hint at syntax highlighting.

```python
def greet(name):
    return f"Hello, {name}"
```

If your code itself contains three backticks, open the outer fence with four backticks instead, as shown above. Indented code blocks (four spaces) also work but are easy to break by accident, so fences are the safer choice.

Tables (GitHub Flavored)

Tables are not part of the original markdown spec. They come from GitHub Flavored Markdown (GFM). Separate columns with pipes and put a divider row of dashes under the header. Colons in the divider set alignment.

| Tool | Input | Output |
| :--- | :---: | ---: |
| Converter | Markdown | HTML |
| Generator | Rows | Table |

Left colon aligns left, colons on both sides center, and a right colon aligns right. Hand-aligning pipes is tedious for anything past a couple of rows, so the Markdown table generator builds the grid for you and emits clean GFM.

Flavors differ: CommonMark vs GFM

There is no single markdown. The original 2004 syntax left many edge cases undefined, so parsers diverged. CommonMark is a strict, unambiguous specification that most modern tools follow for the core syntax. GFM extends CommonMark with tables, task lists (- [ ] and - [x]), strikethrough (~~text~~), and automatic linking of bare URLs.

The practical result is that a document can render one way on GitHub and another way in a different tool. Tables, task lists, and strikethrough are GFM extensions and may not appear at all under a strict CommonMark parser. When you move content between systems, expect the extensions to be the first things to break. Some destinations do not use markdown internally at all: to move a formatted document into an issue tracker, the Markdown to JIRA tool rewrites your markdown into JIRA wiki markup so the formatting survives the trip.

Closing

Most of markdown fits on one page, and the syntax above covers the large majority of what you will ever write. Learn the core first: headings, emphasis, links, lists, and fenced code. Reach for GFM tables and task lists when a destination supports them, and remember that flavors differ when output looks wrong somewhere new. When hand-editing gets tedious, a converter beats fiddling with pipes and angle brackets by hand.