Markdown Lists

How to create bullet, numbered, nested, and task lists in Markdown. Covers spacing, resuming numbers, and platform quirks for GitHub, Notion, Discord, and Slack.

Jump to Section

Unordered Lists Ordered Lists Nested Lists Task Lists Resume Numbering Platform Variations Common Mistakes Quick Reference Platform Support FAQ

Unordered Lists

Start each line with a hyphen, asterisk, or plus sign followed by a space. All three markers produce the same bullet output.

Hyphen bullets

- First item
- Second item
- Third item

Preview

First item
Second item
Third item

Mixed markers

* First item
+ Second item
- Third item

Preview

First item

Second item

Third item

Mixing markers inside one list is legal but harder to read. Pick one marker per document or section.

Ordered Lists

Use a number followed by a period and a space. The actual numbers are mostly advisory: CommonMark will renumber sequential items, but using the correct values avoids surprises in strict parsers.

Numbered list

1. First step
2. Second step
3. Third step

Preview

First step
Second step
Third step

Lazy numbering: 1. First\n1. Second\n1. Third renders as 1, 2, 3 in CommonMark. It is convenient for diffs, but explicit numbers are clearer for readers.

Nested Lists

Indent child items by two spaces under the parent item. Four spaces is also common, but 2 spaces is the most portable minimum.

Nested unordered list

- Fruits
  - Apple
  - Banana
- Vegetables
  - Carrot
  - Broccoli

Preview

Fruits
- Apple
- Banana
Vegetables
- Carrot
- Broccoli

Keep sibling items at the same indent. A one-space difference can cause a child item to be swallowed into the previous item or treated as plain text.

Task Lists

Task lists add a checkbox character inside an unordered list item. They are a GitHub Flavored Markdown extension. Use [x] for checked and [ ] for unchecked.

GFM task list

- [x] Write documentation
- [ ] Update screenshots
- [ ] Deploy to production
- [ ] Celebrate

Preview

Write documentation
Update screenshots
Deploy to production
Celebrate

Resuming Numbering

Markdown does not have a single-list continuation mode across a paragraph break. Exit the first list with a blank line, add your paragraph, then start a new numbered list at the next value.

Resume after a break

1. First item
2. Second item

Paragraph or callout in between.

3. Third item
4. Fourth item

Preview

First item
Second item

Paragraph or callout in between.

Third item
Fourth item

Platform Variations

Lists are one of the most consistent Markdown features, but Slack and Discord still have their own rules.

GitHub / GitLab / GFMPlatform-specific

- [x] Write documentation
- [ ] Update screenshots
- [ ] Deploy to production
- [ ] Celebrate

How it looks in GitHub

Write documentation
Update screenshots
Deploy to production
Celebrate

Task lists render clickable checkboxes in issues and PRs. They also re-order nested task indentation correctly.

SlackPlatform-specific

* first
* second

How it looks in Slack

first
second

Slack mrkdwn uses an asterisk (not a hyphen) for bullets. Numbered lists are not supported in mrkdwn.

DiscordPlatform-specific

- first
- second

How it looks in Discord

first
second

Discord supports hyphen bullets and 1. numbered lists. Task checkboxes render as plain text boxes.

NotionPlatform-specific

- first
- second

How it looks in Notion

first
second

Notion parses pasted hyphen/numbered lists into its native list blocks, including nested indents.

Common Mistakes

Lists break when spacing or indentation is inconsistent. Each row shows the broken version and the corrected one side by side.

Broken

- First
-Second

Fixed

- First
- Second

A space is required after the list marker. Without it, the line renders as plain text.

Broken

- Fruits
  - Apple
 - Banana

Fixed

- Fruits
  - Apple
  - Banana

Siblings at the same nesting level must use the same indent. Most parsers treat 2 spaces as the standard indent.

Broken

1. First
2. Second
1. Third

Fixed

1. First
2. Second
3. Third

Ordered lists can use lazy numbering (1. for every item), but using mixed numbers can confuse readers. Choose one style consistently.

Broken

- [x ] Task
- [ x ] Task

Fixed

- [x] Task
- [ ] Task

Task list syntax requires exactly one space inside the brackets. Extra spaces break the checkbox.

Broken

- item
~~strikethrough~~

Fixed

- item

~~strikethrough~~

A paragraph directly under a list item becomes part of that list item (loose list). Add a blank line to end the list first.

Quick Reference

Syntax	Result	Notes
- item	Bullet	Use -, *, or + followed by a space
1. item	Numbered	Use number + period + space
- child	Nested bullet	Indent 2+ spaces under parent
- [ ] task	Unchecked checkbox	GFM extension
- [x] task	Checked checkbox	GFM extension

Platform Support

Lists are widely supported, but task lists and nested rendering vary. This table tells you what to expect on the most common platforms.

Platform	Supported?	Notes
GitHub	Yes	Full: unordered, ordered, nested, and task lists (GFM).
GitLab	Yes	Same as GitHub Flavored Markdown.
CommonMark	Yes	Standard lists; task lists are an extension.
VS Code preview	Yes	Built-in preview renders standard and task lists.
Obsidian	Yes	Live Preview supports bullets, numbers, nesting, and tasks.
Notion	Yes	Paste parses lists into native blocks; supports nesting and tasks.
Discord	Partial	Bullets and numbers OK; nested lists can collapse visually.
Slack	Partial	Bullets via * only. Ordered lists and task lists not supported in mrkdwn.
Reddit (new)	Yes	Unordered, ordered, and nested lists render.
Reddit (old)	Partial	Basic lists OK; task lists not rendered.
Docusaurus / VitePress / Astro	Yes	Remark plugins handle lists and tasks.

Frequently Asked Questions

How do you make a list in Markdown?

Start a line with a list marker followed by a space. Hyphens (-), asterisks (*), and plus signs (+) create unordered bullets. Numbers followed by a period create ordered lists.

How do you create a numbered list in Markdown?

Use `1. First item`, `2. Second item`, and so on. You can also use lazy numbering (`1.` for every item) and the renderer will still order them sequentially.

How do you make a nested list in Markdown?

Indent the child list by two spaces under its parent item. Keep sibling items at the same indent so the parser treats them as the same level.

How do you make a task list in Markdown?

Use `- [ ] Unchecked task` and `- [x] Checked task`. This is a GitHub Flavored Markdown extension that renders as clickable checkboxes on GitHub.

Why is my Markdown list not rendering correctly?

The most common causes are missing spaces after markers, mixed indentation between sibling items, or missing blank lines before/after adjacent paragraphs.

Can you resume numbering in Markdown?

Yes, but not automatically. Add a blank line, place a paragraph or other block, then start a new list at the number you want. Some renderers may restart styling, so test where it counts.

Why does my list number restart after a paragraph?

Markdown sees a blank line as a list terminator unless the paragraph is indented to stay inside a list item. To keep a single ordered list with a break, start a new list at the desired number after the break.

Do Discord and Slack support Markdown lists?

Discord supports hyphen bullets and 1.-style numbers. Slack mrkdwn only supports asterisk bullets; numbered lists and task checkboxes are not supported.

Related Markdown Guides

Lists are a core Markdown structure. For related formatting and platform guides:

Full Markdown Cheat Sheet →Table Syntax →Bold Syntax →Strikethrough Syntax →Code Block Syntax →GitHub Markdown →Notion Markdown →