Markdown basics

How it works

A Markdown document is just a text file (usually .md or .markdown). You format it with ordinary punctuation; a processor turns it into HTML. Most formatting is block level (paragraphs, headings, lists) or inline (bold, links, code). Blank lines separate blocks — that single rule explains most of Markdown.

Tip: any literal HTML you write is passed straight through, so Markdown is a superset of HTML when you need something it can't express.

Headings & paragraphs

Start a line with one to six # characters for headings level 1–6. Separate paragraphs with a blank line. A single newline inside a paragraph is collapsed into a space; end a line with two spaces (or a backslash) to force a hard line break.

# Title
## Section
### Sub-section

A paragraph of text. This
line joins the one above.

A second paragraph.

Emphasis: bold & italic

Wrap text in one marker for italic and two for bold. Both * and _ work; combine them for bold‑italic.

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

~~strikethrough~~ is technically a popular extension, but it is so widely supported it is worth learning here.

Lists

Begin lines 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 don't matter — the renderer counts for you.

- Fruit
  - Apple
  - Pear
- Vegetables

1. First
2. Second
3. Third

Links & images

Put the link text in square brackets and the URL in parentheses. An image is the same with a leading !, where the bracketed text becomes the alt text. You can also define a link once by reference and reuse the label.

[Visit the site](https://markdown.org)

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

A [reference link][docs].

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

A bare URL in angle brackets — <https://markdown.org> — becomes an automatic link.

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, optionally naming the language for syntax highlighting.

Use the `print()` function.

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

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

Blockquotes

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

> 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.

---
***
___

Escaping & special characters

To show a character that Markdown would otherwise interpret, put a backslash before it. The following can all be escaped:

\  ` * _ { } [ ] ( ) # + - . ! |

So \*literal asterisks\* renders as *literal asterisks* rather than italic text.

Quick reference

Ready for more? See what the extensions add, or pick an editor from the tools directory.