Basic Markdown syntax adds structure, clarity, and emphasis to a document.

The basics include:

  • Headings and subheadings.
  • Text decorations, like boldface, italic, and monospaced (code) fonts.
  • Ordered and unordered lists.
  • Hyperlinks.

This page describes how to add each of these basic Markdown syntax elements.

Headings

Headings and subheadings add structure and organization to your document.

Use hashes (#) to create headings and subheadings.

Heading level Markdown syntax Example
Level 1 # # Level 1 heading
Level 2 ## ## Level 2 heading
Level 3 ### ### Level 3 heading
Level 4 #### #### Level 4 heading
Level 5 ##### ##### Level 5 heading
Level 6 ###### ###### Level 6 heading

The following image shows what these headings render to in the browser:

A screenshot of the six Markdown heading levels
Figure 1: Six Markdown heading levels.

Text formats

Markdown lets you format your text with plain text decorators.

Use boldface font

Surround a word or phrase with two asterisks (**) to make it boldface.

For example, the following Markdown text:

This phrase uses **boldface** font.

renders to:

This phrase uses boldface font.

Use italic font

Surround a word or phrase with an underscore (_) to make it italic.

For example, the following Markdown text:

This phrase uses _italics_.

renders to:

This phrase uses italics.

Use monospaced (code) font

Use monospaced font for code snippets and code blocks

Surround a word with backticks (`) to make it monospaced.

For example, the following Markdown text:

This phrase uses `monospaced` font.

renders to:

This phrase uses monospaced font.

To make multi-line code blocks, surround a text block with three backticks (```). For the code block to use syntax highlights, add the code language to the end of the first backtick triplet.

For example, the following Markdown text:

```python
import pandas

df = pandas.from_csv("mydata.csv")
```

renders to:

import pandas

df = pandas.from_csv("mydata.csv")

Ordered and unordered lists

Lists make sequential instructions or related collections of items easier to read. They break up long portions of text and add helpful white space to your document.

Use an ordered list

Use ordered lists to make sequential instructions easy to read.

Start a line with the number one and a period (1.) to make an ordered list, whether your list has one or 100 items. Most Markdown flavors, including GitHub-flavored Markdown, will render your list in increasing, sequential order.

For example, the following Markdown:

1. Do this step first
1. Do this step next
1. Do this step last

renders to:

  1. Do this step first
  2. Do this step next
  3. Do this step last

Use an unordered list

Use unordered list to organize related ideas that don’t follow from one to the next.

Start a line with an asterisk (*) to make an unordered list.

For example, the following Markdown:

* Item one
* Item two
* Item three

renders to:

  • Item one
  • Item two
  • Item three

Add hyperlinks to your document with brackets ([]) and parentheses (()).

Hyperlinks can link any other site on the internet.

For example, the following Markdown text:

[This sentence links to https://google.com](https://google.com).

renders to:

This sentence links to https://google.com.

Use the link Liquid tag to link to another page in your site.

For example, the following Markdown:

[This sentence links to my About page]({% link _pages/about.md %}).

renders to:

This sentence links to my About page.

Link to specific sections on the same page

Add a hyperlink to any section of the current page with the heading name.

For example, the following Markdown:

[This sentence links to this page's **Headings** section](#headings).

renders to:

This sentence links to this page’s Headings section.

Updated: