Markdown: Markdown List Syntax and Nesting

Lists are the simplest way to turn scattered information into structured content — readers can grasp the key points at a glance.

1. What You'll Learn

• Syntax for unordered and ordered lists
• Correct way to nest lists
• Creating and using task lists
• Paragraphs, code blocks, and blockquotes inside lists
• Common list mistakes and how to fix them

2. A Project Manager's Real Story

(1) Pain Point: Chaotic Task Assignments

Chris is a project manager for a development team. Every Monday, he writes the weekly task plan in a document. He used to describe tasks in plain text — team members frequently missed items and mixed up priorities. Someone would ask, "Is this my task or yours?" Another would say, "I didn't know where this task ranked in priority."

(2) Solution: Structuring Tasks with Lists

Chris switched to using Markdown lists to organize tasks: ordered lists for priorities, task lists (- [ ]) for completion status, and nested lists for subtasks. The team's reading efficiency improved dramatically:

## Weekly Tasks

1. **[High Priority] Database Migration**
   - [ ] Export old data
   - [ ] Write migration script
   - [ ] Test data integrity
2. **[Medium Priority] API Documentation Update**
   - [x] Update user API docs (completed)
   - [ ] Add new endpoint examples

(3) Benefit: Clear Task Ownership

3. Unordered Lists

(1) Basic Syntax

Unordered lists start with -, *, or + followed by a space:

- Apple
- Banana
- Orange

* Apple
* Banana
* Orange

+ Apple
+ Banana
+ Orange

Tip: All three symbols produce the same result. We recommend sticking with - — it's the least likely to be confused with other syntax like italic *.

(2) Multi-Paragraph List Items

If a list item contains multiple paragraphs, keep the indentation consistent:

- Item one: This is the main content.

  This is additional explanation for this item (blank line + 2-space indent).

- Item two: Description of the second item.

  More supplementary information.

▶ Example: Organizing Information with Unordered Lists

## Project Checklist

- **Frontend**
  - Responsive layout testing
  - Browser compatibility check

- **Backend**
  - API stress testing
  - Database backup verification

- **DevOps**
  - SSL certificate expiration check
  - Log rotation configuration

Output:

TEXT 📖 Display only

📋 Copy

Renders as a structured checklist organized by team, with each category containing specific action items.

4. Ordered Lists

(1) Basic Syntax

Ordered lists start with a number followed by a period:

1. Step one: Initialize the project
2. Step two: Install dependencies
3. Step three: Configure the environment
4. Step four: Start the development server

Tip: Markdown does not require consecutive numbers — you can write 1. for every item and it will auto-increment when rendered. But using real numbers makes the source more readable.

(2) Starting from a Specific Number

Some scenarios require starting from a number other than 1:

1. The first three steps are in the previous section
4. Step four (continued)
5. Step five

Tip: On GitHub, you can also insert explanatory text between list items and continue the numbering — Markdown will recognize the sequence automatically.

▶ Example: Expressing Steps with Ordered Lists

## Deployment Workflow

1. Pull latest code: `git pull origin main`
2. Install dependencies: `npm install`
3. Run tests: `npm test`
4. Build the project: `npm run build`
5. Upload to server: `scp -r dist/ user@server:/var/www/`
6. Restart the service: `pm2 restart app`

Output:

TEXT 📖 Display only

📋 Copy

Renders as numbered steps. Ordered lists are a natural fit for step-by-step guides — each step contains an action command and a brief explanation.

Tip: In step-by-step guides, ordered lists are the natural choice for representing execution order. Each step includes one action command and a short description.

5. Nested Lists

Nested lists are created through indentation. Child lists are indented 2 more spaces (or 1 Tab) than their parent:

(1) Unordered List Nested in Unordered List

- Programming Languages
  - Compiled
    - C
    - C++
    - Rust
  - Interpreted
    - Python
    - JavaScript
    - Ruby
- Databases
  - Relational
    - PostgreSQL
    - MySQL

(2) Unordered List Nested in Ordered List

1. Install Python
   - Download the installer from the official website
   - Check "Add Python to PATH"
2. Set up a virtual environment
   - Create environment: `python -m venv venv`
   - Activate environment: `source venv/bin/activate`

▶ Example: Three-Level Nesting for Category Structure

## Frontend Technology Stack

- **Frameworks**
  - React
    - Core concepts: Components, State, Props
    - Ecosystem: React Router, Redux
  - Vue
    - Core concepts: Reactive data, Templates
    - Ecosystem: Vue Router, Pinia
- **Styling**
  - CSS
  - SCSS
  - Tailwind

Output:

TEXT 📖 Display only

📋 Copy

Renders as a three-level nested list with clear visual hierarchy — each level indented further to the right.

Caution: Don't nest more than 3 levels — readability drops sharply. If you need deeper hierarchy, consider using headings or tables instead.

6. Task Lists

Task lists are a GFM extension. Use - [ ] for incomplete items and - [x] for completed items:

- [x] Complete project initialization
- [x] Implement user login
- [ ] Write API documentation
- [ ] Deploy to production
- [ ] Performance optimization

Caution: The [x] in task lists is case-insensitive — both [x] and [X] mean completed. There must be a space after the bracket: use - [ ] not -[].

▶ Example: Tracking Project Progress with Task Lists

## E-Commerce Project Sprint 3

### Completed
- [x] Product listing page
- [x] Shopping cart
- [x] User registration/login

### In Progress
- [ ] Payment API integration
  - [x] Alipay SDK integration
  - [ ] Payment callback handling
  - [ ] Refund flow

### To Do
- [ ] Order management dashboard
- [ ] Product search feature

Output:

TEXT 📖 Display only

📋 Copy

Renders with checkboxes — completed items show as checked, incomplete items as unchecked. Perfect for project status tracking.

Tip: Using task lists in GitHub Issues and Pull Requests is extremely effective — team members can see progress at a glance.

7. Other Content Inside Lists

(1) Code Blocks Inside Lists

Code blocks inside list items need extra indentation (8 spaces or two Tabs):

- Run test cases:

        npm run test -- --coverage

- Check code formatting:

        npx eslint src/

Caution: Code blocks inside lists can't use the ``` fenced syntax (it breaks the list in some parsers). The recommended approach is 8-space indentation.

(2) Blockquotes Inside Lists

- Key finding:
  > Users spend an average of only 12 seconds on this page.
  > The main reason is slow load time.

8. Complete Example: Planning a Project with Lists

Project Kickoff Plan

## Sprint 1: Foundation (Weeks 1-2)

- [x] Project initialization
  1. Create Git repository
  2. Configure CI/CD
  3. Set up dev environment
- [ ] User system
  - [x] Registration/login API
  - [ ] Email verification
  - [ ] OAuth third-party login
- [ ] Database design
  - [x] ER diagram complete
  - [ ] Table creation scripts
  - [ ] Seed data

## Sprint 2: Core Features (Weeks 3-4)

1. **Product Module**
   - Product CRUD
   - Category management
   - Search functionality
2. **Order Module**
   - Create order
   - Payment flow
   - Order status management

> Note: All tasks in the scorecard must be completed by the end of the Sprint.

Expected result: A clear project plan organized by Sprint, using multiple list types to organize tasks at different levels of granularity.

❓ FAQ

📖 Summary

• Use - for unordered lists, 1. for ordered lists, and - [ ] for task lists
• Nest lists by indenting 2-4 spaces
• Code blocks inside lists need 8-space indentation
• [x] in task lists means completed, [ ] means not yet done
• Lists are commonly used for task checklists, step-by-step guides, and categorized summaries
• Try to keep list items roughly the same length, 1-2 lines each

📝 Exercises

1. Beginner: List 5 technical topics you plan to learn this week with an unordered list, describe the learning steps (from setup to practice) with an ordered list, and track your progress with a task list.

2. Intermediate: Create a "Project Migration Plan" containing at least 3 main phases (ordered list), each phase containing subtasks (nested unordered list), and an inspection checklist (task list).

3. Challenge: Write a list item that mixes nested lists, code blocks, and blockquotes — all three content types together. For example: inside a "Deployment Steps" list item, embed a bash command code block, and add a blockquote underneath with a cautionary note.

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us