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
- done
- also done
Capital or lowercase x, both work.
- 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.
For the .md file that arrives in Mail
A markdown file on a phone is the worst case: no editor, no preview, and a share sheet full of apps that want to import it into a library. The iPhone and iPad app opens it where it landed, renders it, and lets you edit and save it back.
For iPhone and iPad.