Markdown Lists

Unordered Lists

Start each line with a dash -, asterisk *, or plus sign + followed by a space. All three markers produce the same bullet list. The dash is the most widely used convention.

Dash (most common)

- Apples
- Bananas
- Cherries

Asterisk

* Apples
* Bananas
* Cherries

Plus sign

+ Apples
+ Bananas
+ Cherries

Pick one marker and stick with it throughout your document. Mixing markers within the same list level can cause some processors to split them into separate lists.

Ordered Lists

Start each line with a number, a period, and a space. Markdown auto-numbers the items in sequence — the actual numbers you type after the first one do not matter.

1. Clone the repository
2. Install dependencies
3. Run the dev server

Lazy numbering

You can use 1. for every item. Markdown will still render them as 1, 2, 3. This makes it easier to reorder items without renumbering.

1. Clone the repository
1. Install dependencies
1. Run the dev server

Starting from a specific number

The first number sets the starting value. Subsequent items continue from there regardless of the numbers you type.

3. Third step
1. Fourth step
1. Fifth step

Nested Lists

Indent a list item by 2 to 4 spaces (or 1 tab) to create a sub-list. You can nest unordered lists inside ordered lists and vice versa. Most Markdown processors support multiple levels of nesting.

- Fruits
  - Apples
  - Bananas
- Vegetables
  - Carrots
  - Broccoli

Mixing ordered and unordered

1. First step
   - Detail A
   - Detail B
2. Second step
   - Detail C
   - Detail D

Three levels deep

- Level 1
  - Level 2
    - Level 3

Task Lists / Checklists

Task lists use a dash, a space, and square brackets. An empty bracket [ ] is unchecked; a bracket with an x [x] is checked. This is a GitHub Flavored Markdown (GFM) extension, widely supported across platforms.

- [ ] Write the introduction
- [x] Create the outline
- [ ] Add code examples
- [x] Proofread the draft

On GitHub and GitLab, task lists in issues and pull requests are interactive — you can click the checkboxes to toggle them. In other contexts, they render as static checkboxes.

Nested task lists

- [x] Setup
  - [x] Install Node.js
  - [x] Clone the repo
- [ ] Development
  - [ ] Build the UI
  - [ ] Write tests

Multi-line List Items

To add extra lines or paragraphs to a list item, indent the continuation text to align with the first character of the item content (typically 2–4 spaces).

Paragraph inside a list item

1. Clone the repository.

   Make sure you have Git installed before
   running this command. On macOS, Git ships
   with the Xcode Command Line Tools.

2. Run `npm install` to fetch dependencies.

Multiple paragraphs in one item

- First item, first paragraph.

  First item, second paragraph.

- Second item.

Lists with Other Elements

You can embed code blocks, blockquotes, and images inside list items by indenting them to align with the item content.

Code block inside a list

1. Install the package:

   ```
   npm install markdown-it
   ```

2. Import it in your code.

Blockquote inside a list

- Remember the principle:

  > Keep it simple, stupid.

- Apply it everywhere.

Image inside a list

1. Open the settings page:

   ![Settings screenshot](settings.png)

2. Toggle the dark mode switch.

Indent the image syntax by the same number of spaces as the list content (typically 3–4 spaces for ordered lists). A blank line before and after the image helps some processors render it correctly.

Definition Lists

Definition lists associate a term with one or more definitions. They are not part of standard CommonMark but are supported by PHP Markdown Extra, Pandoc, and some editors. The syntax uses a colon followed by a space on the line after the term.

Markdown
: A lightweight markup language for creating
  formatted text using a plain-text editor.

HTML
: The standard markup language for documents
  designed to be displayed in a web browser.

Because definition lists are not universally supported, use them only when you know your target platform handles them. GitHub and GitLab do not render definition list syntax — the text will appear as plain paragraphs instead.

Platform Support

Most list features are part of standard Markdown, but task lists and definition lists depend on the platform. Here is what works where.

Common Mistakes

No blank line before the list

Some Markdown processors require a blank line between a paragraph and the start of a list. Without it, the list may render as plain text.

Here are the items:     <-- no blank line
- Apples                <-- may not render as a list

Here are the items:     <-- blank line before
                        <-- (empty line)
- Apples                <-- renders correctly

Wrong indentation for nested items

Nested items need 2–4 spaces of indentation. Using only 1 space or too many spaces can break the nesting or create an unintended code block.

Mixing markers inconsistently

Using different markers (-, *, +) within the same list level can cause some processors to treat consecutive items as separate lists with gaps between them.

- Apples            <-- consistent, use this
- Bananas
- Cherries

- Apples            <-- inconsistent, avoid this
* Bananas
+ Cherries

Forgetting the space after the marker

The marker must be followed by a space. Without the space, the line is treated as a paragraph, not a list item.

Read Lists in MDViewer

MDViewer is a native macOS app for reading and previewing Markdown files. It renders task lists with interactive checkboxes, nested lists with proper indentation, and all standard list types instantly. Double-click any .md file in Finder and see it rendered. Lite is free; Pro adds editing, Git history, and PDF export.

Requires macOS 13.0 or later. Intel and Apple Silicon.

FAQ

How do I create a bullet list in Markdown?

Start each line with a dash followed by a space: - Item. You can also use * or + instead of -. All three markers produce the same bullet list. The dash is the most common convention and is recommended by most style guides.

How do I make a numbered list in Markdown?

Start each line with a number, a period, and a space: 1. First, 2. Second, 3. Third. The actual numbers you type after the first one do not matter — Markdown auto-numbers them. You can write 1. for every line and it will still render as 1, 2, 3.

How do I create a checkbox list in Markdown?

Use a dash, a space, and square brackets: - [ ] Todo item for unchecked, - [x] Done item for checked. This is a GitHub Flavored Markdown (GFM) extension and works on GitHub, GitLab, Obsidian, and many Markdown editors including MDViewer.

How do I nest lists in Markdown?

Indent the nested item by 2 to 4 spaces before the list marker. For example, write - Parent on one line, then   - Child (two spaces before the dash) on the next. You can nest ordered lists inside unordered lists and vice versa, and most processors support multiple levels of nesting.

Can I start a numbered list at a specific number?

Yes. The first number you use sets the starting number. If you begin with 3., the list renders starting at 3. After the first item, Markdown continues sequencing regardless of the numbers you type. For example, 3. Apple, 1. Banana, 1. Cherry renders as 3, 4, 5.

What's the difference between -, *, and + for lists?

There is no difference in output. All three markers produce the same unordered (bullet) list. The dash - is the most common convention. Pick one and use it consistently throughout your document — mixing markers within the same list level can cause some processors to treat them as separate lists.