Home/Docs/Markdown Task Lists

Markdown Task Lists

Learn how to create Markdown task lists (checkboxes) using simple syntax. This guide covers checked and unchecked checkboxes, nested task lists, GitHub task lists, best practices, common mistakes, and real-world examples.

A Markdown task list is a checklist made up of checkboxes that helps track tasks, progress, and to-do items. Unlike a normal list, each item includes a checkbox that can be either completed or incomplete.

Task lists are widely used in GitHub README files, Issues, Pull Requests, project roadmaps, technical documentation, Obsidian vaults, and VS Code Markdown files — making them essential for project planning and collaboration.

Practice as you read: Open the Markdown Editor to build task lists with live preview, keep the Markdown Cheat Sheet open for quick syntax lookup, or use the Markdown Task List Generator to create checklists instantly.

Open EditorDownload PDF

What Is a Markdown Task List?

A Markdown task list is a checklist made up of checkboxes that helps track tasks, progress, and to-do items.

Task lists are widely used in:

  • GitHub README files
  • GitHub Issues
  • Pull Requests
  • Project roadmaps
  • Technical documentation
  • Personal notes
  • Obsidian vaults
  • VS Code Markdown files

Unlike a normal list, each item includes a checkbox that can be either completed or incomplete.

Task lists are especially useful for project planning and collaboration. For standard bullet and numbered lists without checkboxes, see the Markdown Lists guide.

Why Use Markdown Task Lists?

Task lists make documentation more interactive and organized.

They help you:

  • Track project progress
  • Create to-do lists
  • Manage feature roadmaps
  • Plan releases
  • Document installation steps
  • Organize bug fixes
  • Monitor project milestones

GitHub even allows users to check or uncheck task list items directly within Issues and Pull Requests.

Markdown Task List Syntax

Markdown task lists are created using a hyphen followed by square brackets.

An empty space inside the brackets creates an unchecked task.

- [ ] Write documentation
- [ ] Review pull request
- [ ] Deploy application

Output

Rendered Output

  • Write documentation
  • Review pull request
  • Deploy application

Each checkbox begins with:

  • -
  • One space
  • [ ]

This syntax is supported by GitHub Flavored Markdown (GFM) and most modern Markdown editors.

Completed Task

To mark a task as complete, replace the empty space with the letter x.

- [x] Install dependencies
- [x] Configure environment
- [x] Run tests

Output

Rendered Output

  • Install dependencies
  • Configure environment
  • Run tests

Both lowercase x and uppercase X are accepted by most Markdown parsers.

Mixed Task List Example

A task list can contain both completed and pending items.

- [x] Create project
- [x] Add documentation
- [ ] Write API guide
- [ ] Publish website

Output

Rendered Output

  • Create project
  • Add documentation
  • Write API guide
  • Publish website

This format is commonly used in GitHub project planning and release checklists.

When Should You Use Task Lists?

Task lists are ideal for:

  • Project planning
  • Feature tracking
  • Documentation checklists
  • Deployment guides
  • Bug tracking
  • Sprint planning
  • Release checklists
  • Personal productivity
  • Team collaboration

For ordinary bullet points that don't represent actionable items, use standard Markdown lists instead.

Nested Task Lists

Markdown supports nested task lists, allowing you to organize large projects into smaller tasks.

Nested checklists are useful for breaking complex work into manageable steps.

- [ ] Build Website
  - [x] Create homepage
  - [x] Create blog
  - [ ] Create documentation
  - [ ] Add search

Output

Rendered Output

  • Build Website
    • Create homepage
    • Create blog
    • Create documentation
    • Add search

Nested task lists are commonly used in project roadmaps and software development.

Multiple Levels of Task Lists

You can create multiple nesting levels using indentation.

- [ ] Launch Product
  - [ ] Website
    - [ ] Homepage
    - [ ] Documentation
  - [ ] Marketing
    - [ ] Social Media
    - [ ] Blog Posts

Output

Rendered Output

  • Launch Product
    • Website
      • Homepage
      • Documentation
    • Marketing
      • Social Media
      • Blog Posts

Deep nesting is supported by most Markdown editors, but limiting nesting to two or three levels keeps documents easier to read.

Ordered Task Lists

Task lists can also be combined with numbered lists.

1. Setup Project
   - [x] Install Node.js
   - [x] Install dependencies
2. Build Project
   - [ ] Create components
   - [ ] Add routing
3. Deploy
   - [ ] Publish website

Output

Rendered Output

  1. Setup Project
    • Install Node.js
    • Install dependencies
  2. Build Project
    • Create components
    • Add routing
  3. Deploy
    • Publish website

This format works well for step-by-step tutorials and deployment guides.

Task Lists Inside Blockquotes

Task lists can be placed inside blockquotes to highlight important checklists.

> Deployment Checklist
>
> - [ ] Backup database
> - [ ] Run tests
> - [ ] Deploy application

Output

Rendered Output

Deployment Checklist

  • Backup database
  • Run tests
  • Deploy application

This technique is useful for release notes and important deployment instructions. For more on blockquote syntax, see Markdown Blockquotes.

Task Lists with Code

Inline code works naturally inside task lists.

- [ ] Run `npm install`
- [ ] Execute `npm run dev`
- [ ] Verify `package.json`

Output

Rendered Output

  • Run npm install
  • Execute npm run dev
  • Verify package.json

Task lists with code snippets are frequently used in developer documentation.

GitHub Task Lists

GitHub Flavored Markdown (GFM) fully supports interactive task lists.

They can be used in:

  • README files
  • Issues
  • Pull Requests
  • Discussions
  • Project documentation
  • Wikis

When used inside GitHub Issues or Pull Requests, users can check or uncheck items directly from the web interface.

This makes task lists an excellent choice for tracking progress during software development.

Platform Compatibility

Platform Task Lists Supported
GitHub ✅ Interactive
GitLab ✅ Interactive
VS Code Preview ✅
Obsidian ✅
Docusaurus ✅
MkDocs ✅
Hugo ✅
Astro Starlight ✅
CommonMark Editors Partial

Task lists are part of GitHub Flavored Markdown (GFM). Most modern Markdown editors support them, although interactive checkboxes are generally available only on platforms such as GitHub and GitLab.

Best Practices for Markdown Task Lists

Markdown task lists are most effective when they are clear, organized, and easy to update. Follow these best practices to create professional checklists.

Keep Tasks Short

Each task should describe a single action.

Good example:

- [ ] Update documentation
- [ ] Fix broken links
- [ ] Publish release

Avoid combining multiple actions into one checkbox.

Group Related Tasks

Organize similar tasks under a common heading.

## Documentation

- [ ] Update README
- [ ] Add screenshots
- [ ] Review API docs

## Development

- [ ] Fix login bug
- [ ] Improve performance

This makes long checklists much easier to scan.

Use Nested Task Lists

Large projects become easier to manage when broken into smaller subtasks.

Instead of creating one long checklist, group related work together using nested task lists.

Update Completed Tasks

Mark completed work immediately.

Completed checkboxes provide an accurate picture of project progress and help collaborators understand what still needs attention.

Don't Overuse Task Lists

Use task lists only when tracking actionable items.

For general information or feature descriptions, use regular Markdown lists instead.

Preview Before Publishing

Always preview your Markdown to ensure task lists render correctly across GitHub, VS Code, Obsidian, or your documentation platform.

Common Markdown Task List Mistakes

Even though task lists use simple syntax, a few common mistakes can prevent them from rendering properly.

Missing Space Inside the Brackets

Incorrect:

- [] Create documentation

Correct:

- [ ] Create documentation

There must be one space between the brackets for an unchecked task.

Missing Space After the Hyphen

Incorrect:

-[ ] Install dependencies

Correct:

- [ ] Install dependencies

Proper spacing improves compatibility with Markdown parsers.

Incorrect Checked Syntax

Incorrect:

- [done] Deploy website

Correct:

- [x] Deploy website

Only x or X inside the brackets creates a completed task.

Incorrect Indentation

Nested task lists require consistent indentation.

Incorrect:

- [ ] Website
 - [ ] Homepage

Correct:

- [ ] Website
  - [ ] Homepage

Using consistent indentation keeps nested checklists readable.

Real-World Examples

Task lists are widely used in GitHub repositories, software projects, documentation sites, release planning, and personal productivity workflows because they make progress easy to track.

GitHub Project Roadmap

## Version 2.0

- [x] Authentication
- [x] Dashboard
- [ ] Notifications
- [ ] Analytics
- [ ] Mobile App

Documentation Checklist

- [x] Write introduction
- [x] Add installation guide
- [ ] Add API reference
- [ ] Review screenshots

Website Launch Checklist

- [x] Register domain
- [x] Configure hosting
- [ ] Test contact form
- [ ] Submit sitemap
- [ ] Launch website

Daily To-Do List

- [ ] Reply to emails
- [ ] Review pull requests
- [ ] Update documentation
- [ ] Publish blog post

Practice Markdown Task Lists

The best way to learn task lists is by creating your own checklists.

Open the Markdown Editor to build interactive task lists, nested checklists, and project roadmaps with live preview. Use the Markdown Task List Generator to create checklists quickly, then export your Markdown to HTML, PDF, DOCX, or other supported formats.

Summary

Markdown task lists provide a simple and effective way to track progress, organize projects, and manage to-do items.

In this guide, you learned:

  • What Markdown task lists are
  • Checkbox syntax
  • Checked and unchecked tasks
  • Nested task lists
  • Ordered task lists
  • GitHub task lists
  • Platform compatibility
  • Best practices
  • Common mistakes
  • Frequently asked questions

Whether you're managing a GitHub project, writing documentation, planning a release, or organizing personal tasks, Markdown task lists make your content more structured, actionable, and easier to maintain.

Continue Learning

Continue learning Markdown with these guides:

Available now

The best way to learn Markdown task lists is by writing them yourself. Open the Markdown Editor to experiment with checkboxes, nested task lists, and project roadmaps while previewing the rendered output in real time.

Frequently Asked Questions

  1. 1

    What is a Markdown task list?

    A Markdown task list is a checklist that uses checkboxes to track tasks, progress, or to-do items. It is commonly used in GitHub README files, Issues, Pull Requests, documentation, and personal notes.

  2. 2

    How do I create a checkbox in Markdown?

    Use a hyphen followed by square brackets. Example: - [ ] Incomplete task and - [x] Completed task. An empty space creates an unchecked box, while x marks the task as complete.

  3. 3

    Does GitHub support Markdown task lists?

    Yes. GitHub Flavored Markdown (GFM) fully supports task lists in README files, Issues, Pull Requests, Discussions, Wikis, and project documentation. GitHub also allows interactive checkboxes in Issues and Pull Requests.

  4. 4

    Can I create nested task lists?

    Yes. Indent child tasks beneath a parent task. Example: - [ ] Website with indented - [ ] Homepage and - [ ] Documentation beneath it. Nested task lists are useful for organizing larger projects.

  5. 5

    Can I use numbered task lists?

    Yes. Task lists work with ordered lists. Example: 1. Setup with indented - [x] Install dependencies and - [ ] Configure project beneath it. This format is commonly used in tutorials and deployment guides.

  6. 6

    Why isn't my checkbox working?

    Common reasons include missing space inside [ ], missing space after the hyphen, incorrect indentation, using unsupported Markdown editors, or typing [done] instead of [x]. Always preview your Markdown to verify the output.

  7. 7

    Which Markdown editors support task lists?

    Most modern Markdown editors support task lists, including GitHub, GitLab, VS Code, Obsidian, Docusaurus, MkDocs, Hugo, and Astro Starlight. Interactive checkboxes are generally available only on platforms such as GitHub and GitLab.

  8. 8

    Can I include links and code inside task lists?

    Yes. Task items can contain links, inline code, emphasis, and other Markdown formatting. Example: - [ ] Read the Documentation and - [ ] Run npm install.

  9. 9

    Should I use task lists or bullet lists?

    Use task lists for actionable items that need to be completed. Use regular bullet lists when presenting information that doesn't require tracking.

  10. 10

    Are Markdown task lists part of CommonMark?

    Task lists are part of GitHub Flavored Markdown (GFM) rather than the core CommonMark specification. Many modern Markdown editors support them because of their popularity.