How to Create Task Lists in Markdown
Create a checkbox in Markdown by starting a list item with brackets: - [ ] for an unchecked task and - [x] for a completed one. The space inside the empty brackets is required — - [] will not render as a checkbox.
Platform Support
Task lists are a GFM extension built on top of ordinary lists, which means all the normal list rules apply: they nest with indentation, they work under ordered list markers (1. [ ] task is valid), and a blank line before the list is needed after a paragraph. The checked state accepts an upper- or lowercase x. Because they are real list items, you can mix tasks and plain bullets in one list and add inline formatting to task text — including links to issues and ~~strikethrough~~ on abandoned items.
The syntax is strict in two places people do not expect. First, the empty checkbox needs exactly [ ] — bracket, single space, bracket. Typing [] without the space, or putting two spaces inside, renders literal brackets. Second, there must be a space after the closing bracket before the task text: - [ ]Buy milk fails, - [ ] Buy milk works.
On GitHub, task lists are interactive and do real work: checkboxes in issues, pull request descriptions, and comments can be clicked to toggle, which edits the underlying Markdown for you. GitHub also counts them — an issue with task lists shows a progress indicator like "3 of 7 tasks" in issue lists, and task list items in an issue body can reference other issues to create lightweight tracking relationships. This makes - [ ] the backbone of PR checklists and release task tracking.
Rendering elsewhere varies more than for most syntax. Obsidian supports task lists natively and plugins extend them with due dates and queries. Notion converts them to to-do blocks on import. Discord and Slack render the brackets literally, so for chat apps you are better off with emoji checkmarks. In static site generators, support depends on the parser: GFM-mode parsers render disabled checkboxes by default (readers cannot toggle them), which is usually what you want in published docs.
Examples
- [x] Completed task
- [ ] Incomplete task
- [ ] Another task- Completed task
- Incomplete task
- Another task
Create interactive checklists using brackets.
- [ ] Release v2.0
- [x] Update changelog
- [x] Bump version
- [ ] Publish to npm- Release v2.0
- Update changelog
- Bump version
- Publish to npm
Task lists nest exactly like regular lists — indent two spaces under the parent.
- [x] Tests pass locally
- [ ] Updated the [docs](https://example.com/docs)
- [ ] ~~Bench results~~ (not needed for this change)- Tests pass locally
- Updated the docs
-
Bench results(not needed for this change)
Common Mistakes
- [] Task without the inner space- [ ] Task with a space inside the bracketsThe unchecked box must be exactly [ ] — bracket, one space, bracket. Empty [] renders as literal brackets.
- [ ]Task text touching the bracket- [ ] Task text after a spaceA space is required between the closing bracket and the task text.
[ ] A task without a list marker- [ ] A task as a list itemCheckboxes only work inside list items. The - (or 1.) marker before the brackets is mandatory.
Platform Notes
GitHub
Interactive in issues, PRs, and comments — click to toggle. Issues show "x of y tasks" progress, and task items can reference other issues for tracking.
Obsidian
Native support with clickable checkboxes in reading view. Plugins like Tasks add due dates, recurrence, and queries on top of the same syntax.
Notion
Markdown task lists convert to native to-do blocks on import. While typing, use [] followed by a space to create a to-do block.
Discord
Not supported — the brackets render as plain text. Use emoji (white check marks) for ad-hoc checklists in chat.
Frequently Asked Questions
How do I make a checkbox in Markdown?
Start a list item with brackets: - [ ] for unchecked, - [x] for checked. The space inside the empty brackets and the space after the closing bracket are both required.
Why is my checkbox showing as literal brackets?
Either the inner space is missing (- [] fails), there is no space after the bracket, the brackets are not part of a list item, or the platform simply does not support task lists (Discord and Slack do not).
Can readers check the boxes on GitHub?
Yes — in issues, PR descriptions, and comments, anyone with edit access can click checkboxes to toggle them, and GitHub updates the underlying Markdown. In rendered README files the boxes are display-only.
Can I nest tasks under other tasks?
Yes. Task lists follow normal list nesting rules: indent subtasks two spaces under the parent item. Mixed lists of tasks and plain bullets also work.
Related Syntax
Lists
Learn Markdown lists: unordered bullets with -, ordered lists with numbers, nesting rules, loose vs tight lists, and how to avoid broken numbering.
Strikethrough
Learn how to strike through text in Markdown using double tildes (~~text~~).
Blockquotes
Learn how to create blockquotes in Markdown with the > character, including multi-paragraph quotes, nested quotes, callouts/admonitions, and lazy continuation rules.