Markdown basics

The core Markdown rules with a worked example of each. This is the original syntax that every flavour and tool understands, and each rule below shows what you type and what it renders to. For a shorter overview see the syntax page; anything not covered here is an extension.

How it works

A Markdown document is a plain text file, usually .md or .markdown. You format it with ordinary punctuation and a processor turns it into HTML. Most formatting is either block level, like paragraphs, headings and lists, or inline, like bold, links and code. A blank line separates one block from the next. That single rule explains most of Markdown.

Headings

Start a line with one to six # characters for headings level 1 to 6.

You write

# Title
## Section
### Sub-section

You get

Title

Section

Sub-section

Paragraphs

Write a paragraph as one or more lines of text. A single newline inside a paragraph is treated as a space, so you can break the source into short lines and it still renders as one paragraph that wraps naturally to the width of the page.

You write

Markdown joins these lines
into a single paragraph.
You can break the source
wherever it is convenient
and the text still flows
together when it is shown.

You get

Markdown joins these lines into a single paragraph. You can break the source wherever it is convenient and the text still flows together when it is shown.

If you want a break between paragraphs, there are several ways to do it. The simplest is to leave at least one blank line between them.

You write

The first paragraph is written
across a few short lines with no
blank line, so it stays one block.

The second paragraph.

You get

The first paragraph is written across a few short lines with no blank line, so it stays one block.

The second paragraph.

Line breaks

To break a line inside a paragraph without starting a new one, end the line with two trailing spaces or with a backslash. This is handy for things like addresses or verse, where each line should sit on its own but the lines still belong to one paragraph.

You write

First line.··
Second line.

First line.\
Second line.

You get

First line.
Second line.

The two dots stand for two trailing spaces. Trailing spaces are easy to miss in an editor, so many writers prefer the backslash.

Formatting

To format text in Markdown, wrap words in markers: two asterisks for bold, one for italic, two tildes for strikethrough. Underline, colour and comments have no marker of their own, so they use HTML. See HTML markup for more of what HTML adds.

Bold

Any text which has ** or __ on either side represents bold text.

You write

**bold** or __bold__

You get

bold or bold

Italic

Any text which has * or _ on either side represents italic text. Three markers together give bold italic.

You write

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

You get

italic or italic
bold italic

Strikethrough

Compatibility: GitHub, Obsidian, VS Code, Reddit, Pandoc

Any text which has ~~ on either side is struck through.

You write

~~strikethrough~~

You get

~~strikethrough~~

Underline

Compatibility: CommonMark, GitHub, Obsidian, VS Code, Pandoc

Markdown leaves underline out because an underline reads as a link on the web. When you need one, use the HTML <u> tag.

You write

<u>underlined</u>

You get

underlined

Colour

Compatibility: CommonMark, Obsidian, VS Code, Pandoc

Markdown has no syntax for colour. Use an HTML <span> with an inline style where the processor allows it.

You write

<span style="color:#c0392b">red text</span>

You get

red text

Many sites strip style attributes for safety, so this shows as plain text on GitHub, Reddit and others. On GitHub you can colour text through a math expression instead, such as $\color{red}{text}$ .

Comments

Compatibility: CommonMark, GitHub, Obsidian, VS Code, Pandoc

To leave a note in the source that stays out of the page, use an HTML comment. It renders as nothing.

You write

Visible text.
<!-- a note to yourself -->
More visible text.

You get

Visible text.

More visible text.

The comment still sits in the HTML source, so treat it as hidden from readers rather than secret.

Lists

To create a list in Markdown, begin each line with -, * or + for a bullet list, or 1. style numbers for an ordered list. Indent by two to four spaces to nest a sub-list. The actual numbers you type are counted for you by the renderer.

You write

- Fruit
  - Apple
  - Pear
- Vegetables

1. First
2. Second
3. Third

You get

Fruit
- Apple
- Pear
Vegetables

First
Second
Third

Images

Compatibility: CommonMark, GitHub, Obsidian, VS Code, Pandoc

To add an image in Markdown, write an exclamation mark, the alt text in square brackets, then the path or URL in parentheses. The alt text describes the image for screen readers and for when it fails to load. An optional title in quotes becomes a tooltip.

You write

![A kitten](kitten.jpg)
![A kitten](kitten.jpg "Hover title")

You get

🐱 A kitten (image)

Markdown always places an image at its natural width. You can control the width using HTML.

Links

To add a link in Markdown, put the link text in square brackets and the URL in parentheses. The simplest link of all is a bare URL wrapped in angle brackets, which most processors turn into a clickable link even without them.

You write

<https://markdown.org>

You get

https://markdown.org

To show some words on the link instead of the URL, put the link text in square brackets and the URL in parentheses. Add an optional title in quotes for a tooltip.

You write

[Visit the site](https://markdown.org)
[With a tooltip](https://markdown.org "Markdown")

You get

Visit the site

With a tooltip

Reference links allow you to reuse the same URL by defining it once and then using it many times on the page. This keeps long paragraphs readable and gathers your links in one place.

You write

A [reference link][docs] and another [link][docs].

[docs]: https://markdown.org/basics/

You get

A reference link and another link.

A linked image is an image that is itself a link. Wrap the whole image in the link brackets so the image becomes clickable.

You write

[![A kitten](kitten.jpg)](https://example.com)

You get

🐱 A kitten (image)

Code

Wrap inline snippets in single backticks. For a block of code, indent every line by four spaces or, far more common, fence it between triple backticks and optionally name the language for syntax highlighting.

You write

Use the `print()` function.

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

You get

Use the print() function.

def greet(name):
    return f"Hi {name}"

Blockquotes

Prefix lines with > to quote them. Quotes can be nested and can contain other Markdown.

You write

> Markdown is intended to be
> as easy-to-read as possible.
>
> > Even nested quotes work.

You get

Markdown is intended to be as easy-to-read as possible.
Even nested quotes work.

Horizontal rules

Three or more dashes, asterisks or underscores alone on a line draw a thematic break.

You write

A first paragraph.

---

A second paragraph.

***

A third paragraph.

___

A fourth paragraph.

You get

A first paragraph.

A second paragraph.

A third paragraph.

A fourth paragraph.

Escaping

Markdown treats some characters as commands. If you actually want to show one of those characters, you escape it, which simply means putting a backslash \ before that character.

Character	Escaped
`\` backslash	`\\`
` backtick	\`
`*` asterisk	`\*`
`_` underscore	`\_`
`{` left brace	`\{`
`}` right brace	`\}`
`[` left bracket	`\[`
`]` right bracket	`\]`
`(` left parenthesis	`\(`
`)` right parenthesis	`\)`
`#` hash	`\#`
`+` plus	`\+`
`-` minus	`\-`
`.` dot	`\.`
`!` exclamation mark	`\!`
`\|` pipe	`\\|`

Keep going

That is the core syntax. From here you can put raw HTML to work on the HTML markup page, keep the cheat sheet handy for the syntax and escaping rules, or check the compatibility table for what works where. When you are ready for tables, task lists, footnotes and diagrams, see the extensions, or pick an editor from the tools directory.