Markdown task lists

A task list is a list with checkboxes. You write it as plain text, and apps that support it show a box in front of each item. It is a good fit for to-do lists, checklists in pull requests, and meeting notes with action items.

Basic syntax

Write a list item, then [ ] for an open task or [x] for a finished one, then a space and the text.

- [ ] Write the release notes
- [x] Update the changelog
- [ ] Tag the release

Result:

• Write the release notes
• Update the changelog
• Tag the release

The exact rules

The GitHub Flavored Markdown (GFM) spec is strict about the marker:

• It must come at the very start of the list item’s text.
• It is a left bracket, then one space or the letter x, then a right bracket.
• x can be lower case or upper case.
• At least one space must follow the right bracket.

You can use any list marker: -, *, + or a number.

* [X] An asterisk and a capital X work

1. [ ] Numbered lists work too
2. [x] Done

Result:

• An asterisk and a capital X work

1. Numbered lists work too
2. Done

Common mistakes

These lines look close, but they are not task items. They render as normal list items or plain text with the brackets visible.

- [] No space between the brackets
- [x]No space after the bracket
- Buy milk [ ] marker not at the start

[ ] Not a list item

Result:

• [] No space between the brackets
• [x]No space after the bracket
• Buy milk [ ] marker not at the start

[ ] Not a list item

Nesting

Task lists nest like any other list. Indent the sub-tasks so they line up with the parent’s text. Under - that is two spaces.

- [ ] Launch
  - [x] Build
  - [x] Test
  - [ ] Publish
- [x] Write announcement

Result:

• Launch
  • Build
  • Test
  • Publish
• Write announcement

A parent box does not tick itself when all sub-tasks are done. Each checkbox is independent. It reflects only what is written in its own line.

Mixing tasks and normal items

A list can contain both task items and normal items. Sub-items under a task can be plain notes.

- [ ] Book the venue
  - Ask for a room with a projector
  - Budget is fixed
- [ ] Send invitations

Result:

• Book the venue
  • Ask for a room with a projector
  • Budget is fixed
• Send invitations

Formatting inside tasks

The text after the marker is normal Markdown. Links, emphasis and inline code all work. Many people strike through finished items.

- [x] ~~Fix the login bug~~
- [ ] Review the **API** changes in `client.js`

Result:

• Fix the login bug
• Review the API changes in client.js

Where it works

Task lists are not part of CommonMark. A strict CommonMark renderer shows a bullet followed by the literal text [ ] or [x]. That is still readable, which is one reason the syntax is popular.

Task lists are defined in the GFM spec as an extension. The spec says the marker is replaced with a checkbox. It does not say whether you can click it. That is up to each app.

• GitHub renders task lists in issues, pull requests, comments and Markdown files. In issues, pull requests and comments you can tick the boxes directly if you are allowed to edit the text. In a rendered file in a repository the boxes are read-only.
• GitLab renders task lists and lets you tick them in issues and merge requests.
• Obsidian renders task lists and lets you tick them in the note.
• VS Code: support in the built-in Markdown preview depends on your version and extensions, so check your app.

Some apps add states of their own, such as other characters between the brackets. These are not part of GFM and do not carry over to other apps. Stick to [ ] and [x] if the file should work everywhere.

To read a checklist without the brackets, Markko shows .md files formatted on a Mac and in Quick Look.

FAQ

Related