Back to blog
·

Markdown List Formatting Guide: Bullets, Numbering & Nesting

Markdown list formatting guide: master bullets, numbering, nesting, and task lists, avoid common errors, and write Markdown that renders cleanly everywhere.

Introduction

Markdown list formatting turns plain text into structured lists that a Markdown parser can render across editors and platforms. Used well, it makes documentation easier to scan, README.md files easier to follow, and notes easier to maintain.

This markdown list formatting guide covers the list types you’ll use most: unordered lists, ordered lists, nested lists, and task lists. You’ll also see common mistakes that break rendering, plus the platform-specific differences that matter in GitHub Flavored Markdown (GFM), GitHub, GitLab, Notion, and Obsidian.

List formatting matters because readers rarely consume long documentation pages line by line. Clear bullets and numbering improve scannability, support accessibility, and help structure complex information in documentation, developer docs, blog posts, and personal notes. The same source can render differently depending on the parser, so understanding the baseline from CommonMark helps you write Markdown that stays consistent across tools.

For broader context, see the Complete Markdown guide, Markdown for documentation, and Markdown documentation best practices.

How Markdown Lists Work

Markdown recognizes list items by simple markers at the start of a line. An unordered list uses a hyphen, asterisk, or plus sign—each creates the same bullet marker:

  • Apples
  • Oranges
  • Bananas

An ordered list uses numbers followed by periods. In many Markdown parsers, the visible numbers can be renumbered automatically:

  1. Install Markdown
  2. Write the list
  3. Preview the result

A Markdown parser uses indentation and blank lines to decide where a list starts, ends, and nests. Keep related items together, and use blank lines only when you want separate blocks. Markdown formatting basics and the Markdown cheat sheet show the core patterns, while the Complete Markdown guide covers broader syntax.

Unordered and Ordered Lists

Use an unordered list for non-sequential items: feature summaries, grouped ideas, or quick takeaways in documentation. A single bullet marker style keeps the page consistent; the hyphen is usually easiest to scan, while asterisk and plus sign work the same in Markdown, CommonMark, and GitHub Flavored Markdown (GFM). Use an ordered list when sequence matters: steps, workflows, rankings, or any numbered list where order changes meaning.

Many Markdown processors renumber ordered list items automatically, so you can edit source text without fixing every number. In a README.md, this means 1., 1., 1. can still render correctly as a numbered list. Compare: “Install, configure, deploy” works as bullets; “1. Install 2. Configure 3. Deploy” reads as instructions. For more patterns, see the Markdown cheat sheet and Markdown writing tips.

Nested Lists and Mixed Hierarchies

Create a nested list by indenting a sub-list under a parent item. In Markdown, a child item can be an unordered list or an ordered list, and most flavors such as CommonMark and GitHub Flavored Markdown (GFM) accept 2 to 4 spaces of indentation. The exact number matters less than staying consistent so the Markdown parser can read the hierarchy correctly.

Correct:

1. Plan the page
   - Gather examples
   - Check links
2. Draft the section
   1. Write the heading
   2. Add the body

Broken nesting usually comes from uneven indentation or missing blank lines in some editors:

1. Plan the page
 - Gather examples
    - Check links
2. Draft the section
1. Write the heading

Keep nesting shallow for documentation and accessibility, especially on mobile views. For more structure tips, see the Markdown cheat sheet, Markdown writing tips, and Markdown documentation best practices.

List Item Content, Task Lists, and Common Pitfalls

A list item can hold more than plain text. You can include links, inline code, bold, italic, and even separate paragraphs inside the same item when you keep the indentation consistent. For deeper rules, see Markdown formatting basics.

Task list syntax uses checkboxes like - [ ] and - [x] for open and completed items. That format works well for checklists, issue tracking, and review notes in GitHub Flavored Markdown (GFM), GitHub, and GitLab, but support varies in Notion and Obsidian.

Common mistakes include inconsistent indentation, mixing bullet styles carelessly, forgetting required blank lines, and assuming every platform renders lists the same way. When a list breaks, compare it against a known-good example in the Markdown cheat sheet and review Markdown writing tips.

Markdown List Formatting Rules by Platform

CommonMark is the baseline, but each platform’s Markdown parser can extend or tweak list behavior. That matters when an ordered list renumbers automatically, a task list checkbox appears, or an indented unordered list collapses unexpectedly. For broader context, see Markdown for developer documentation and the Complete Markdown guide.

GitHub Flavored Markdown (GFM) on GitHub and GitLab both support task list syntax like - [ ] and - [x], plus nested lists and automatic numbering in ordered list blocks. GitHub is usually forgiving with indentation, but inconsistent spacing can still break hierarchy in a README.md. GitLab generally follows the same rules, though its renderer may differ in edge cases.

Notion and Obsidian can behave differently because their editors do more than render plain Markdown. A Markdown editor may accept loose indentation, while Notion or Obsidian may reformat it or interpret nesting differently. A list that looks correct in one Markdown parser can fail in another if the parser rules differ.

Preview lists in the target platform before publishing, especially for documentation and README.md files. For more platform-focused guidance, use Markdown for documentation.

Best Practices for Readable Lists

Write lists for scannability first. Short, parallel items are easier to read, compare, and act on, especially in documentation, a README, or developer docs. If one bullet starts with a verb, keep the others in the same form; if one step names a noun, keep the rest consistent.

Keep list items concise and logically grouped. Avoid excessive nesting unless the hierarchy truly adds meaning, because deep structures are harder to follow on mobile and can bury the main point. Dense walls of text inside a list also hurt accessibility, so split long explanations into separate paragraphs or move supporting detail below the list.

For content formatting, test how your Markdown renders in the platform you actually use. GitHub, GitLab, Notion, and documentation tools can differ in spacing, checkbox behavior, and nested list handling. If the output looks cramped or ambiguous, simplify the structure before publishing.

Quick Reference

  • Unordered list

    - Item one
- Item two
- Item three

  • Ordered list

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

  • Nested list

    - Parent item
  - Child item
  - Child item

  • Task list

    - [ ] Open issue
- [x] Review draft

Common Markdown List Mistakes to Avoid

  • Mixing indentation levels within the same list
  • Switching bullet markers without a reason
  • Adding blank lines that split a list unintentionally
  • Assuming ordered list numbers must stay sequential in the source
  • Nesting too deeply for the page layout
  • Forgetting that different Markdown parsers can render edge cases differently

Use this guide as a final check: keep items parallel, avoid clutter, and match the list type to the job. When you need a refresher, consult the Markdown cheat sheet, review Markdown writing tips, and revisit Markdown documentation best practices.

FAQ

How do you make a list in Markdown?

Start a line with a bullet marker for an unordered list (-, *, or +) or a number plus a period for an ordered list (1., 2., 3.). The Markdown parser turns those plain text markers into formatted list items.

What is the difference between ordered and unordered lists in Markdown?

Use an unordered list when the items do not need a sequence. Use an ordered list when the order matters, such as steps in documentation or a README.

How do you create nested lists in Markdown?

Indent the child list under the parent item. Most CommonMark and GFM implementations accept 2 to 4 spaces, but consistency matters more than the exact count.

Why is my Markdown list not indenting properly?

The most common causes are uneven indentation, mixing tabs and spaces, or placing a blank line where the parser does not expect one. Check the list in a Markdown editor and compare it with the CommonMark specification or a Markdown cheat sheet.

Do you need to number ordered list items sequentially?

Usually no. Many Markdown parsers renumber ordered list items automatically, so 1., 1., 1. can still render as a numbered list.

How do task lists work in Markdown?

Use checkbox syntax like - [ ] for an open task and - [x] for a completed task. This is the standard checklist pattern in GitHub Flavored Markdown.

Can Markdown list items contain links, code, or multiple paragraphs?

Yes. List items can contain links, inline code, formatting, and multiple paragraphs if you keep the indentation consistent.

What is the best bullet character to use in Markdown?

The hyphen is usually the easiest to read and the most common in documentation, but asterisk and plus sign are valid too. Pick one style and use it consistently.

How many spaces do you need for nested Markdown lists?

CommonMark and many GFM parsers accept 2 to 4 spaces for nested lists. Use the same indentation level throughout the document.

Does Markdown list syntax differ in GitHub Flavored Markdown?

The core syntax is the same as CommonMark, but GitHub Flavored Markdown adds or emphasizes features like task lists and can be more forgiving in some cases. Always preview in GitHub if that is your target platform.

Why does my list break when I add a blank line?

A blank line can end a list or separate blocks inside it, depending on where it appears. If the list breaks unexpectedly, check whether the blank line should be removed or whether the following line needs indentation.

How do I format a checklist in Markdown?

Use task list syntax: - [ ] for an unchecked item and - [x] for a checked item. This is the standard checklist pattern in GitHub Flavored Markdown.

Can I mix bullets and numbers in the same Markdown list?

Yes. You can nest an ordered list inside an unordered list, or the reverse, when the hierarchy makes sense. Keep the structure readable and avoid mixing styles without a clear reason.

What are common Markdown list mistakes to avoid?

The most common mistakes are inconsistent indentation, accidental blank lines, switching bullet markers mid-list, and assuming every Markdown parser behaves the same way.

How do I write readable lists for documentation?

Keep items short, parallel, and logically grouped. Use the simplest list structure that communicates the idea clearly, and test the result in the platform where the documentation will live.