Written and tested by the MD Converter editorial team
How to Fix Markdown List Indentation and Numbering
Fix Markdown list nesting, numbering, continuation paragraphs, task items, and fenced code with reliable indentation and blank-line examples.
Check indentation and blank lines
Lists usually break because tabs and spaces are mixed, nested markers are not indented far enough, or a paragraph or code block is no longer inside its parent item.
Re-enter suspicious indentation with spaces and enable visible whitespace in the editor. Indent child items beyond the parent marker. A second paragraph inside an item needs a blank line plus matching indentation. Fenced code in a numbered step also needs appropriate indentation and surrounding blank lines.
Many processors can render every ordered item written as 1. with automatic numbering, which makes rearrangement easier. Use actual source numbers if your workflow requires them, and keep the convention consistent. Avoid switching among -, *, and + without a reason.
If HTML structure is correct but a PDF list wraps poorly, inspect print CSS margins, padding, and marker position. Do not apply no-break rules to every long list, as that can create large page gaps.
Start from a minimal nested list
When a complex list breaks, copy one parent and one child into a small test document. Re-enter indentation with spaces, then add the paragraph, code block, task item, or second nesting level one at a time. The first addition that ends the list identifies the structural problem.
Align child content with the beginning of the parent's text rather than guessing with many spaces. Ordered markers take additional width, and two-digit numbers can reveal inconsistent indentation. Use one indentation convention throughout a repository and configure editors to display whitespace.
Keep paragraphs and code inside an item
A second paragraph needs a blank line and indentation that keeps it under the item. Fenced code should have blank lines around it and remain aligned as child content. If numbering restarts after the code block, the fence or following paragraph probably escaped the list.
1. Run the command.
```text
npm run build
```
2. Review the result.
Some renderers accept every ordered item written as 1. and calculate display numbers automatically. This reduces renumbering during edits. If reviewers need meaningful source numbers, write the real sequence instead; the important part is team consistency.
Avoid unnecessary depth
More than three levels can be technically valid and still be hard to follow. Promote a major branch to an H3 heading and restart a shallow list below it. Use ordered lists only when sequence matters. Use bullets for categories, alternatives, and unordered requirements.
Task lists such as - [ ] follow the same nesting rules. Copying from Word can introduce full-width spaces, typographic bullets, and automatic numbering that Markdown does not recognize. Convert pasted material to plain text and rebuild markers with - or 1..
List troubleshooting checklist
- Replace tabs with spaces.
- Align children beneath parent text.
- Indent continuation paragraphs.
- Put blank lines around fenced code.
- Keep bullet markers consistent.
- Check whether numbering restarts after a block.
- Reduce nesting deeper than three levels.
- Inspect both rendered HTML and the saved PDF.
Frequently asked questions
Why does a number restart at one after a paragraph?
The paragraph or code block probably ended the list. Indent it as content of the preceding item, or remove the unintended block boundary.
Why does the source look aligned but render incorrectly?
Tabs and spaces can occupy similar visual widths while producing different parse structure. Turn on visible whitespace and replace the indentation explicitly.
How should a long list behave across PDF pages?
Let ordinary lists split naturally. Add an intentional page break before an important group when necessary. Keeping every item together can push a large list forward and create excessive empty space.
Do task lists use different indentation?
No. - [ ] and - [x] are list markers with checkbox syntax added. Nest them like ordinary bullets and keep a space between the closing bracket and label. Confirm GFM support in the target renderer.
Can I continue numbering after a heading?
Markdown support varies. A heading normally creates a new block, so restarting at one is often clearer. If the sequence must remain continuous, keep it in one list or use platform-specific HTML only after testing portability.
For related pagination problems, see how to control Markdown PDF page breaks.