How do you create a nested list in markdown?

Indent sub-items with 2-4 spaces (or one tab) beneath the parent item: - Parent item, then two spaces and - Sub-item on the next line.

What is the difference between - * and + for bullet lists in markdown?

All three produce identical rendered output. The choice is purely stylistic. Hyphens (-) are the most widely used convention in modern markdown style guides.

How do you add a paragraph inside a bullet list item in markdown?

Add a blank line after the list item text, then indent the continuation paragraph with 4 spaces (or one tab). This creates a loose list item with multiple paragraphs.

How to Create a Bullet List in Markdown

The quick answer: Start each line with a hyphen (-), asterisk (*), or plus sign (+) followed by a space. Hyphens are the most common convention.

Basic Syntax

- First item - Second item - Third item

All three markers produce identical rendered output: - Hyphen style (most common) * Asterisk style + Plus style

Mixing markers in the same list is technically valid but creates visual inconsistency in the source. Pick one and stay consistent. For a full breakdown of all list syntax options, see the Markdown list reference.

The Space After the Marker Is Required

-item — wrong: no space between marker and text, renders as literal text - item — correct: space between - and the item text

Nested Lists

Indent sub-items with 2–4 spaces to create nested lists: - Main item - Sub-item A - Sub-item B - Sub-sub-item - Another main item

CommonMark requires at least 1 space of indentation beyond the parent list marker to qualify as a sub-item. Most style guides recommend 2 or 4 spaces for readability.

Maximum Nesting Depth

Technically unlimited, but practically: stop at three levels. Deeper nesting signals that your content structure needs rethinking — consider using headings and separate sections instead.

Loose vs Tight Lists

A tight list has no blank lines between items: - Apple - Banana - Cherry

A loose list has blank lines between items: - Apple - Banana - Cherry

Loose lists render with more vertical spacing between items and wrap each item in a

tag. Use tight lists for short items, loose lists when items need breathing room or contain multiple sentences.

Multi-Paragraph List Items

To add multiple paragraphs to a single list item, add a blank line after the first paragraph and indent the continuation by 4 spaces: - First list item. This is a second paragraph still inside the first list item. It continues here. - Second list item.

Mixed List Types

You can nest ordered lists inside unordered lists and vice versa: - Install prerequisites 1. Node.js 18+ 2. npm or yarn - Clone the repository - Run the setup script

Continuation Lines

Long list items can wrap across multiple source lines without indentation, as long as there's no blank line: - This is a very long list item that wraps onto multiple lines in the source file but renders as a single continuous item.

Platform-by-Platform Breakdown

GitHub and GitLab

Full support for all three markers. GitHub renders tight and loose lists correctly. Nested lists work with both 2-space and 4-space indentation.

Obsidian

Full support. Obsidian's folding feature lets you collapse nested list levels. The Tab key automatically creates nested items in the editor.

Notion

Notion supports bullet lists via markdown import. In the Notion UI, lists are "Toggle" blocks (collapsible) or regular bulleted list blocks.

Discord

Discord supports - and * for bullet lists. Lists render with bullet points. Nesting is supported with indentation.

Slack

Slack supports bullet lists using - markers. Nesting works with indentation. Slack also auto-renders lists when you press Enter after a list item.

Common Mistakes

Missing Space After Marker

-item renders as plain text. - item renders as a bullet point. The space is mandatory.

Inconsistent Markers

Mixing -, *, and + in the same list is valid but confusing. Some linters (markdownlint) will flag it. Standardize on - across your documents.

Accidental List Creation

A line that happens to start with a hyphen can accidentally create a list item when you wanted prose. Escape it: \- not a list item.

Over-Nesting

Lists nested more than 3 levels deep usually indicate a structural problem. Flatten the content using headings and separate sections instead.

Real-World Use Cases

Feature Lists

Product feature lists are the most common use of bullet lists in markdown: - No signup required - Export as PDF or HTML - Three professional themes - Works with any AI output

Meeting Agendas

Bullet lists work well for agenda items where the sequence isn't critical. If the order matters (agenda with a strict schedule), use numbered lists instead.

AI Output Formatting

ChatGPT and Claude heavily use bullet lists when generating summaries, options lists, pros/cons, and key points. These render beautifully in MarkdownTools — the clean theme especially gives bullet lists excellent visual weight.

Full reference: Markdown Bullet Lists.

Ready to put this into practice? Paste your markdown into the free MarkdownTools PDF exporter or HTML converter — no signup required.