Lists in MDX

Lists are everywhere in technical documentation — feature descriptions, step-by-step instructions, comparison points, requirements, and checklists. In MDX, lists work exactly like standard Markdown lists with no additional syntax to learn. But understanding the nuances of nesting, mixed lists, and multi-line items will help you write cleaner, more readable content.

Numbered Lists (Ordered Lists)

Use any number followed by a period and a space. The actual numbers you write do not matter — MDX will number them sequentially in the output.

  1. Write the content
  2. Add components
  3. Run the build
  4. Deploy the site

Interesting behavior: You could write 1. 1. 1. 1. for all items and the output would still be 1. 2. 3. 4. — Markdown auto-numbers them. However, writing correct numbers makes your source file easier to read when editing.

Starting from a different number: In some parsers, the first number determines the starting point. So 3. First item would start numbering from 3. This behavior varies between Markdown implementations.

When to use numbered lists: Use them for step-by-step instructions, procedures, rankings, or anything where the order matters. If someone could reasonably follow the items in a different order, bullet points are more appropriate.

Nested Lists

Indent with 2 or 4 spaces (depending on your parser configuration) to create sub-items:

  • Frontend Technologies
    • React
    • Vue
    • Svelte
    • Angular
  • Backend Technologies
    • Node.js
    • Python
    • Go
    • Rust
  • Databases
    • PostgreSQL
    • MongoDB
    • Redis

You can nest as deep as you want, but 3 levels is the practical maximum before content becomes hard to read, especially on mobile devices. If you need deeper nesting, consider restructuring your content with headings and separate lists.

Indentation consistency matters. Use the same number of spaces for all nested items. Mixing 2-space and 4-space indentation in the same document causes unpredictable parsing behavior.

Mixed Lists (Ordered + Unordered)

You can combine ordered and unordered lists when nesting:

This pattern is extremely common in tutorials: numbered steps provide the overall sequence, and bullet points within each step list the specific sub-tasks that can be done in any order.

Task Lists (Checklists)

Use - [ ] for unchecked and - [x] for checked items:

  ☑ Write introduction
  ☑ Add code examples
  ☑ Create diagrams
  ☐ Record video tutorial
  ☐ Publish to production
  ☐ Announce on social media

These render as actual checkboxes on most platforms including GitHub, GitLab, and MDX-powered sites. They are excellent for:

• Project progress tracking in documentation
• Release checklists
• Setup requirement verification
• Todo items within tutorials
• Feature completion status

Note: In most MDX sites, task list checkboxes are read-only in the rendered output. They display the state defined in your source file but cannot be toggled by the reader (unlike GitHub Issues where they are interactive).

Multi-Line List Items

When a list item needs multiple paragraphs or complex content, indent the continuation with the same indentation as the list item text:

The blank line plus indentation tells the parser "this paragraph belongs to the list item above." Without proper indentation, the paragraph breaks out of the list and starts a new block.

Lists with Code Blocks

Including code blocks inside list items requires careful indentation:

The code block must be indented to align with the list item content (typically 3-4 spaces after the number and period).

Definition Lists (Not Standard but Useful)

Standard Markdown does not support definition lists, but some MDX configurations with plugins enable them:

If your MDX setup does not support definition lists, you can achieve a similar effect with bold terms and indented descriptions using regular lists.

When to Use Which List Type

Common Mistakes

1. Forgetting the space after the marker — -item is not a list, - item is
2. Inconsistent indentation — mixing 2-space and 4-space nesting causes parsing issues
3. Missing blank lines around lists — always leave blank lines before and after a list
4. Mixing markers in one list — pick - or * and stick with it
5. Over-nesting — more than 3 levels deep is a sign you need restructuring
6. Using bullet points for ordered steps — if sequence matters, use numbers
7. Starting numbered lists without context — always introduce what the list contains

Tips for Better Lists

• Keep list items parallel in structure. If one item starts with a verb, all items should start with verbs. If one is a noun phrase, all should be noun phrases.
• Keep items concise. If each item is 3+ sentences, consider using headings with paragraphs instead.
• Introduce every list. Tell the reader what the list contains before presenting it: "Here are the required dependencies:" followed by the list.
• Do not end list items with periods unless they are complete sentences. Short phrases do not need punctuation.
• Use bold for key terms at the start of descriptive list items to make them scannable.