Markdown List Guide (2026) – Bullets, Numbering, Nesting, and Task Lists

Markdown lists look easy until you need them to stay stable across GitHub, editors, and Word/PDF export. The high-value questions are not “how do I write - item,” but:

• why do blank lines change spacing and structure?
• why can ordered list numbers be ignored after the first item?
• why do nested lists break when code blocks or extra paragraphs are added?
• when is a task list really supported, and when is it not?

Use this guide when you want lists that remain readable and predictable in real documentation workflows.

Bullet Lists and Ordered Lists

An unordered list uses markers such as -, *, or +:

- Setup
- Draft
- Review

An ordered list uses a number plus a delimiter:

1. Draft
2. Review
3. Publish

For simple content, both are straightforward. The problems start when you mix markers, add blank lines, or nest more complex blocks inside a list item.

Why Ordered List Numbers Are Often Ignored

This is one of the most useful Markdown facts for long documents.

In CommonMark, the start number of an ordered list is determined by the first list item. The numbers on later items are generally disregarded by the parser.

That means these two lists are often treated the same structurally:

1. Draft
2. Review
3. Publish

1. Draft
1. Review
1. Publish

Why this matters:

1. using 1. repeatedly can reduce renumbering work during editing
2. it makes AI-generated or frequently edited docs easier to maintain
3. it prevents fragile manual renumbering in long checklists

But there is an important caveat: the first item still matters. If your list should start at 3, the first marker must reflect that.

Tight Lists vs Loose Lists

This is where spacing and export behavior start to diverge.

A list is generally tight when items are directly adjacent:

- Draft
- Review
- Publish

A list becomes loose when items are separated by blank lines, or when an item contains multiple block-level elements with blank lines between them:

- Draft

- Review

- Publish

Why this matters:

1. HTML output changes because loose lists wrap paragraphs differently
2. visual spacing becomes larger
3. Word/PDF export often makes the difference more obvious than browser preview does

If a list suddenly looks too airy or inconsistent after export, unintended blank lines are a common cause.

Mixing Markers Can Start a New List

Many authors assume these are just stylistic variations:

- Draft
- Review
+ Publish

or

1. Draft
2. Review
3) Publish

But CommonMark treats a change of bullet marker or ordered-list delimiter as the start of a new list, not a cosmetic continuation.

If you expect one continuous list, keep the marker style consistent.

Nested Lists: The Real Problem Is Indentation

Basic nesting looks easy:

1. Release work
   - Write notes
   - Prepare assets

In real documents, nested lists become unstable when:

1. indentation is inconsistent
2. the parent item uses a long or wide number like 100.
3. you add code blocks, multiple paragraphs, or blockquotes inside the item

GitHub's practical guidance is useful here: align the nested item so its marker sits under the content area of the parent item. For larger ordered markers, that often means you need more spaces than you first expect.

If you only remember one rule, remember this:

nested Markdown content should align with the content of the parent item, not just visually “look close enough.”

Task Lists Are Not Standard Markdown

Task lists are widely used, but they are not part of core CommonMark syntax.

The common GitHub-flavored pattern is:

- [ ] Draft the guide
- [x] Review screenshots
- [ ] Export to PDF

This works well in GFM-compatible environments and is also supported by Pandoc through its task-list extension.

But you should not write documentation that assumes every Markdown parser will render interactive checkboxes. In some tools, task lists degrade to plain text or plain list items.

In md2word, that distinction matters twice: preview can show checkbox-style formatting, but exported Word/PDF should still be treated as a formatted checklist, not as a universal interactive task-list contract. If the list also contains commands or setup steps, read the Markdown Code Block Guide before you trust the final hierarchy.

Advanced Ordered Lists in Pandoc

If your workflow is Pandoc-based, ordered lists can go beyond simple Arabic numerals.

Pandoc's fancy_lists extension supports markers such as:

• lowercase letters
• uppercase letters
• roman numerals
• markers wrapped in parentheses
• the #. placeholder marker

Example:

#. Draft
#. Review
#. Publish

That can be useful in advanced publishing workflows, but it is not a safe assumption for generic Markdown environments. Treat it as a Pandoc feature, not a cross-platform default.

Lists with Code Blocks or Multiple Paragraphs

This is where many “simple list” guides stop being useful.

A list item can contain more than one paragraph or a fenced code block, but the continuation content must be indented correctly.

Example:

1. Install dependencies

   Use the project root before running the command.

   ```bash
   pnpm install
   pnpm test
   ```

If the indentation is wrong, you may get one of these failure modes:

1. the code block falls out of the list
2. the second paragraph becomes a separate paragraph outside the list
3. the exported document shows broken hierarchy or unexpected spacing

This is not just a web preview issue. It becomes much more visible in Word/PDF output.

If a procedure keeps growing more nested instead of becoming clearer, it is often a sign that the document wants stronger headings, not more indentation.

Practical md2word Advice

This section is based on the current md2word workflow rather than generic Markdown advice.

1. Use simple list structure unless you really need nested blocks

If the document is heading toward export, keep most list items short and single-purpose. Complex items with multiple paragraphs, code, images, and sublists are much harder to keep stable.

2. If you add code blocks inside lists, be strict about indentation

This is one of the easiest ways to break structure in export. If the nested code block matters, verify it in preview and test one real export.

If the same section also uses footnotes or blockquotes, keep those definitions outside the list item and re-check the final structure.

3. Use task lists only when the target workflow supports them

The md2word preview layer enables GFM behavior, so task lists are fine in the editor preview. But for shareable documents, do not assume every downstream consumer will preserve the same checkbox treatment.

4. Avoid accidental loose lists

Many export complaints that “the spacing looks wrong” are really blank-line problems. If a list looks too spread out, inspect the source before changing styles.

5. Keep numbering intent explicit when the first number matters

If a procedure must visibly begin with step 3 or step 7, make the first marker reflect that. Do not assume later renumbering will rescue the structure you meant.

Common Mistakes

1. Mixing -, *, and + within what is supposed to be one list

That can create separate lists.

2. Thinking blank lines are only cosmetic

They are structural.

3. Assuming task lists are universal Markdown

They are not.

4. Nesting by “eyeballing” indentation

This works until the parent marker width changes.

5. Putting code blocks in lists without checking the final export

This is a frequent source of broken formatting.

FAQ

Can I write 1. for every ordered list item?

Usually yes. In CommonMark-style parsing, later item numbers are often ignored and the list is renumbered structurally from the first item. This is a practical editing technique, not a guarantee that every authoring tool will display source text the same way.

Why did my list spacing suddenly change?

You probably turned a tight list into a loose list by adding blank lines between items or between block-level elements inside an item.

Why did my nested list stop nesting?

The most common reason is indentation drift, especially after adding a code block, another paragraph, or a parent item with a wider marker like 100..

Are task lists safe for exported documents?

They are safe only if your rendering/export workflow supports them the way you expect. Treat them as a GFM/Pandoc-friendly feature, not a universal Markdown guarantee.

What is the safest list style for Word/PDF export?

Short, consistently indented lists with stable markers are the safest. If a list item needs code, images, or multiple paragraphs, test the final export rather than trusting preview alone.

Further Reading

• CommonMark Spec: Lists
• GitHub Docs: Basic writing and formatting syntax
• GitHub Docs: About task lists
• Pandoc Manual: Lists

Changelog

• 2026-03-18: Initial high-value release with verified rules for numbering, loose vs tight lists, nested list indentation, task-list scope, and export-focused advice.
• 2026-03-19: Added stronger guidance on preview-vs-export task-list expectations and when deep nesting should become headings instead.

Next steps: Explore Markdown Heading Guide, Markdown Code Block Guide, Markdown Export Tips, Markdown Images Guide, Markdown Quote Guide, and Markdown Footnote Guide.