129 reads

The Dead Simple Markdown Guide to Lists

by TypesettingAugust 20th, 2024

Too Long; Didn't Read

In Markdown, create ordered lists by numbering items with periods, and unordered lists with dashes, asterisks, or plus signs. Indent items to nest them. Escape periods for unordered list items starting with numbers. Add paragraphs, blockquotes, code blocks, or images by indenting elements properly within lists. Avoid mixing delimiters within a single list for compatibility.

Lists

You can organize items into ordered and unordered lists.

Ordered Lists

To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.

Markdown	HTML	Rendered Output
`1. First item` `2. Second item` `3. Third item` `4. Fourth item`	`<ol>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item</li>` `<li>Fourth item</li>` `</ol>`	First itemSecond itemThird itemFourth item
`1. First item` `1. Second item` `1. Third item` `1. Fourth item`	`<ol>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item</li>` `<li>Fourth item</li>` `</ol>`	First itemSecond itemThird itemFourth item
`1. First item` `8. Second item` `3. Third item` `5. Fourth item`	`<ol>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item</li>` `<li>Fourth item</li>` `</ol>`	First itemSecond itemThird itemFourth item
`1. First item` `2. Second item` `3. Third item` `1. Indented item` `2. Indented item` `4. Fourth item`	`<ol>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item` `<ol>` `<li>Indented item</li>` `<li>Indented item</li>` `</ol>` `</li>` `<li>Fourth item</li>` `</ol>`	First itemSecond itemThird itemIndented itemIndented itemFourth item

Ordered List Best Practices

CommonMark and a few other lightweight markup languages let you use a parenthesis ()) as a delimiter (e.g., 1) First item), but not all Markdown applications support this, so it isn’t a great option from a compatibility perspective. For compatibility, use periods only.

✅ Do this	❌ Don't do this
`1. First item` `2. Second item`	`1) First item` `2) Second item`

Unordered Lists

To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or more items to create a nested list.

Markdown	HTML	Rendered Output
`- First item` `- Second item` `- Third item` `- Fourth item`	`<ul>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item</li>` `<li>Fourth item</li>` `</ul>`	First itemSecond itemThird itemFourth item
`* First item` `* Second item` `* Third item` `* Fourth item`	`<ul>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item</li>` `<li>Fourth item</li>` `</ul>`	First itemSecond itemThird itemFourth item
`+ First item` `+ Second item` `+ Third item` `+ Fourth item`	`<ul>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item</li>` `<li>Fourth item</li>` `</ul>`	First itemSecond itemThird itemFourth item
`- First item` `- Second item` `- Third item` `- Indented item` `- Indented item` `- Fourth item`	`<ul>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item` `<ul>` `<li>Indented item</li>` `<li>Indented item</li>` `</ul>` `</li>` `<li>Fourth item</li>` `</ul>`	First itemSecond itemThird itemIndented itemIndented itemFourth item

Starting Unordered List Items With Numbers

If you need to start an unordered list item with a number followed by a period, you can use a backslash (\) to escape the period.

Markdown	HTML	Rendered Output
`- 1968\. A great year!` `- I think 1969 was second best.`	`<ul>` `<li>1968. A great year!</li>` `<li>I think 1969 was second best.</li>` `</ul>`	1968. A great year!I think 1969 was second best.

Unordered List Best Practices

Markdown applications don’t agree on how to handle different delimiters in the same list. For compatibility, don’t mix and match delimiters in the same list — pick one and stick with it.

✅ Do this	❌ Don't do this
`- First item` `- Second item` `- Third item` `- Fourth item`	`+ First item` `* Second item` `- Third item` `+ Fourth item`

Adding Elements in Lists

To add another element in a list while preserving the continuity of the list, indent the element four spaces or one tab, as shown in the following examples.

Tip: If things don't appear the way you expect, double check that you've indented the elements in the list four spaces or one tab.

Paragraphs

This is the first list item.
Here's the second list item.

I need to add another paragraph below the second list item.
And here's the third list item.

The rendered output looks like this:

This is the first list item.
Here’s the second list item.

I need to add another paragraph below the second list item.

And here’s the third list item.

Blockquotes

This is the first list item.
Here's the second list item.

> A blockquote would look great below the second list item.

And here's the third list item.

The rendered output looks like this:

This is the first list item.
Here’s the second list item.

A blockquote would look great below the second list item.

And here’s the third list item.

Code Blocks

Code blocks are normally indented four spaces or one tab. When they’re in a list, indent them eight spaces or two tabs.

Open the file.

Find the following code block on line 21:

 <html>
   <head>
     <title>Test</title>
   </head>

Update the title to match the name of your website.

The rendered output looks like this:

Open the file.

Find the following code block on line 21:

 <html>
   <head>
     <title>Test</title>
   </head>

Update the title to match the name of your website.

Images

Open the file containing the Linux mascot.
Marvel at its beauty.

    ![Tux, the Linux mascot](/assets/images/tux.png

Close the file.

The rendered output looks like this:

Open the file containing the Linux mascot.
Marvel at its beauty.

Close the file.

Lists

You can nest an unordered list in an ordered list, or vice versa.

First item
Second item
Third item
- Indented item
- Indented item
Fourth item

The rendered output looks like this:

First item
Second item
Third item
- Indented item
- Indented item
Fourth item

This guide is a Matt Cone project available on Markdown Guide under the CC BY-SA 4.0 license.

L O A D I N G
. . . comments & more!

About Author

Typesetting@typesetting

Shaping readable and sustainable publications.

Read my stories Learn More

TOPICS

writing #markdown #markdown-syntax #text-formatting #markdown-guide #markdown-lists #markdown-formatting #markdown-best-practices #markdown-list-styling

THIS ARTICLE WAS FEATURED IN...

Permanent on Arweave

Terminal

Lite

Join HackerNoon

Latest technology trends. Customized Experience. Curated Stories. Publish Your Ideas

The Dead Simple Markdown Guide to Lists

Too Long; Didn't Read

Lists

Ordered Lists

Ordered List Best Practices

Unordered Lists

Starting Unordered List Items With Numbers

Unordered List Best Practices

Adding Elements in Lists

Paragraphs

Blockquotes

Code Blocks

Images

Lists

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES