Markdown Task Lists

A Markdown task list is a checklist created with checkbox syntax that lets you track tasks, progress, and to-do items directly inside a Markdown document.

Unlike regular bullet or numbered lists, each item contains a checkbox that represents either a completed or pending task. On platforms that support interactive task lists, such as GitHub Issues and Pull Requests, users can check or uncheck items directly from the interface without editing the Markdown source.

Markdown task lists are commonly used for:

• GitHub README files
• GitHub Issues
• Pull Requests
• Project roadmaps
• Release checklists
• Technical documentation
• Personal notes
• Obsidian vaults

Task lists make documentation easier to follow by turning work items into actionable checklists. For standard bullet or numbered lists without checkboxes, see the Markdown Lists guide.

Why Use Markdown Task Lists?#

Task lists make documentation more actionable by showing what has been completed and what still needs attention. They're useful for both personal notes and collaborative projects where progress needs to be tracked over time.

Common use cases include:

• Tracking project progress
• Managing feature roadmaps
• Planning software releases
• Creating deployment checklists
• Organizing documentation tasks
• Tracking bug fixes
• Managing sprint backlogs
• Personal productivity lists

GitHub also supports interactive task lists in Issues and Pull Requests, allowing contributors to update progress directly from the web interface.

Markdown task lists use a list marker followed by square brackets. An empty space inside the brackets creates an unchecked task, while x (or X) marks the task as completed.

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

Output

Each task list item consists of:

• A list marker (-, *, or +)
• One space
• A checkbox ([ ] or [x])
• The task description

Although -, *, and + all create valid task lists in many Markdown parsers, the hyphen (-) is the most widely used and provides the best consistency across GitHub and other Markdown editors.

Task lists are part of GitHub Flavored Markdown (GFM) and are supported by most modern Markdown editors.

Completed Tasks#

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

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

Output

Most Markdown parsers accept both lowercase (x) and uppercase (X) inside the checkbox.

Mixed Task List Example#

Completed and pending tasks can appear together in the same checklist.

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

Output

Mixed task lists are commonly used for release planning, sprint tracking, documentation progress, and project roadmaps because they clearly show completed and remaining work.

When Should You Use Task Lists?#

Task lists work best whenever you need to track work instead of simply presenting information.

Common use cases include:

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

If you're only presenting information without tracking completion, use standard Markdown Lists instead of task lists.

Nested task lists help break large tasks into smaller, manageable subtasks. They're useful for project roadmaps, feature development, documentation, and release planning.

Indent child tasks beneath the parent task using consistent spacing.

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

Output

Use two or four spaces consistently for indentation, depending on your editor. Mixing indentation styles can cause nested tasks to render incorrectly in some Markdown parsers.

Multiple Levels of Task Lists#

Task lists can be nested multiple levels deep for larger projects.

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

Output

Although deep nesting is supported by most editors, limiting checklists to two or three levels usually keeps documentation easier to read and maintain.

Ordered Task Lists#

Task lists can also be combined with numbered lists when work needs to be completed in a specific sequence.

1. Setup Project

   - [x] Install Node.js
   - [x] Install dependencies

2. Build Project

   - [ ] Create components
   - [ ] Add routing

3. Deploy

   - [ ] Publish website

Output

This format works well for installation guides, deployment documentation, release procedures, and onboarding checklists.

Task Lists Inside Blockquotes#

Task lists can be placed inside blockquotes to highlight important checklists or call out required actions.

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

Output

This pattern is commonly used for release notes, migration guides, and operational documentation. For more formatting options, see the Markdown Blockquotes guide.

Task Lists with Links#

Task items can include standard Markdown links.

- [ ] Read the [Installation Guide](/docs)
- [ ] Review the [Markdown Basics](/markdown-basics)
- [ ] Publish the README

Output

This approach works well for contributor checklists, onboarding guides, and documentation review workflows.

Task Lists with Inline Code#

Inline code can be used inside task items for commands, filenames, variables, and configuration values.

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

Output

For multi-line commands or scripts, use a fenced code block instead of inline code. See the Markdown Code Blocks guide for complete examples.

GitHub Flavored Markdown (GFM) fully supports task lists across multiple GitHub features.

You can use task lists in:

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

In GitHub Issues and Pull Requests, checkboxes are interactive, allowing collaborators to update task status directly from the GitHub interface. In README files and most documentation pages, task lists are rendered as static checklists.

For a deeper look at GitHub-specific checklist patterns, see GitHub Task Lists. For the broader GFM feature set, see GitHub Flavored Markdown.

Task lists are a GitHub Flavored Markdown (GFM) extension rather than part of the core CommonMark specification. Most modern Markdown editors support them because they're widely used in documentation and software development.

Well-structured task lists are easier to scan, update, and maintain. These practices help keep checklists readable across GitHub and other Markdown editors.

Keep Tasks Action-Oriented#

Each checkbox should represent one clear action.

Good example

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

Avoid combining multiple actions into a single task, as it makes progress harder to track.

Group Related Tasks#

Organize related work under descriptive headings instead of creating one long checklist.

## Documentation

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

## Development

- [ ] Fix login bug
- [ ] Improve performance

Grouping related tasks makes large projects easier to navigate.

Use Nested Task Lists for Larger Projects#

Break complex work into smaller subtasks instead of creating long, flat checklists.

Nested task lists provide better structure for roadmaps, release plans, and feature development.

Mark Tasks as Soon as They're Completed#

Update completed items regularly so everyone sees the current project status.

Keeping task lists current is especially helpful when multiple contributors are working on the same project.

Choose One List Marker#

Markdown supports -, *, and + for task lists, but it's best to use a single style throughout the document.

Using one list marker improves consistency and keeps large checklists easier to read.

Preview Before Publishing#

Different Markdown parsers may render task lists slightly differently.

Preview your document in the platform where it will be published, such as GitHub, VS Code, Obsidian, or your documentation site, before sharing it.

Task list syntax is simple, but small formatting mistakes can prevent checkboxes from rendering correctly.

Missing Space Inside the Brackets#

Incorrect

- [] Create documentation

Correct

- [ ] Create documentation

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

Missing Space After the List Marker#

Incorrect

-[ ] Install dependencies

Correct

- [ ] Install dependencies

Always leave one space after the list marker before the checkbox.

Using Invalid 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

Inconsistent indentation can cause nested items to render incorrectly in some Markdown parsers.

Expecting Interactive Checkboxes Everywhere#

Interactive task lists are supported only on certain platforms, such as GitHub Issues and Pull Requests.

Most documentation sites, README files, and Markdown previews display task lists as static checkboxes.

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 fastest way to learn task lists is by creating your own checklists.

Open the Markdown Editor to build task lists with live preview, organize nested checklists, and test different formatting styles. If you're starting from scratch, use the Markdown Task List Generator to create checklists quickly, then export them to HTML, PDF, DOCX, or other supported formats.