Markdown checkbox
A task list is a bulleted list where each item starts with a pair of brackets. Empty brackets give an empty box, an x inside gives a ticked one.
- [ ] not done yet
- [x] done
- [X] also done- not done yet
- done
- also done
Capital or lowercase x, both work.
- [ ] parent task
- [x] a step that is finished
- [ ] a step that is not- parent task
- a step that is finished
- a step that is not
What usually goes wrong
- The space between the brackets is required:
- [] itemrenders as literal brackets. This is the most common reason a checkbox does not appear. - There must be a space after the closing bracket too.
- It has to be a list item. Brackets on their own line, without the leading dash, are just brackets.
- Task lists are a GitHub-flavoured extension. A strict CommonMark renderer shows the brackets as text.
Where it behaves differently
| Platform | Behaviour |
|---|---|
| GitHub | Checkboxes in issues and pull requests are clickable, and ticking one edits the source. In a README they render but are read-only. |
| Obsidian | Clickable, and it supports extra states such as - [/] for in progress. |
| Discord and Slack | No task lists. The brackets show as text. |
Questions
Why is my markdown checkbox not showing?
Nine times out of ten the space inside the brackets is missing. It must be `- [ ]`, not `- []`. The tenth time, the line is not part of a list because the dash is missing.
Can I tick a checkbox by clicking it?
In GitHub issues and pull requests, and in editors like Obsidian, yes. In a rendered README or a static site it is display only, since there is nothing to save the change to.