Markdown Checkbox
How to create Markdown checkboxes and task lists. Covers checked - [x], unchecked - [ ], nested tasks, GitHub clickables, and where they render.
Basic Syntax
A Markdown checkbox is an unordered list item with a bracket pair after the marker. Use a space for unchecked and an x for checked.
- [ ] Buy groceries
- [x] Walk the dog
- [ ] Write the changelog- Buy groceries
- Walk the dog
- Write the changelog
The bracket must contain exactly one character: a space or an x. The marker, bracket, and text each need a single space between them.
Checked vs Unchecked
Swap the space for an x to mark a task done. Some renderers accept an uppercase X, but lowercase is the safe default.
- [x] Merge pull request #42
- [x] Deploy to staging
- [ ] Run smoke tests- Merge pull request #42
- Deploy to staging
- Run smoke tests
Nested Tasks
Indent child checkboxes by two spaces. Keep siblings at the same indent so the parser nests them correctly. This is the standard way to build a Markdown checklist with sub-tasks.
- [ ] Ship v2.0
- [x] Finalize API
- [x] Write docs
- [ ] Update screenshots
- [ ] Announce release- Ship v2.0
- Finalize API
- Write docs
- Update screenshots
- Announce release
Do not mix indentation within the same nesting level. A one-space difference can flatten nested tasks or attach a child to the wrong parent.
GitHub Clickables
On GitHub, a task list in an issue, pull request, or comment renders as live checkboxes. Clicking a checkbox edits the source Markdown in place and updates the task progress shown next to the list heading.
- [ ] Must be done before merge
- [ ] Change is backwards compatible
- [ ] Tests pass locally- Must be done before merge
- Change is backwards compatible
- Tests pass locally
On GitHub these checkboxes are clickable and count toward the task-progress meter.
Multiple Checklists in One Doc
A blank line starts a new list. If you want separate task lists under different headings, end the first list with a blank line before the next heading.
Today:
- [x] Check metrics
- [ ] Reply to blocked PRs
This week:
- [ ] Interview candidatesToday:
- Check metrics
- Reply to blocked PRs
This week:
- Interview candidates
Common Mistakes
Checkboxes fail because of bracket spacing, list-marker choice, or indentation. Each row shows the broken version and the corrected one side by side.
Broken
- [] Empty taskFixed
- [ ] Empty taskBroken
- [ x ] TaskFixed
- [x] TaskBroken
1. [ ] Numbered taskFixed
- [ ] Numbered taskBroken
- [x]TaskFixed
- [x] TaskBroken
- [x] Item 1
- [x] Subtask A
- [ ] Subtask BFixed
- [x] Item 1
- [x] Subtask A
- [ ] Subtask BQuick Reference
| Syntax | Result | Notes |
|---|---|---|
| - [ ] task | Unchecked | Space inside brackets |
| - [x] task | Checked | Lowercase x is safest |
| - [X] task | Checked | Uppercase works on some parsers |
| - [ ] task | Nested task | Indent 2 spaces under parent |
| * [ ] task | Unchecked | Asterisk works too, but hyphen is conventional |
Platform Support
Task lists depend on GFM support. This table tells you where checkboxes render and where they stay as plain text.
| Platform | Supported? | Notes |
|---|---|---|
| GitHub | Yes | Clickable checkboxes in issues and PRs; nested tasks render correctly. |
| GitLab | Yes | Renders interactive task lists in issues and merge requests. |
| Obsidian | Yes | Live Preview shows clickable checkbox tasks. |
| Notion | Yes | Pasting a task list converts it into native to-do blocks. |
| VS Code preview | Yes | Built-in preview renders GFM task lists (read-only). |
| Docusaurus / VitePress / Astro | Yes | Remark plugins render task lists with checkboxes. |
| Discord | Partial | Renders the list marker but not the checkbox character. |
| Slack | No | mrkdwn does not support task list syntax. |
| Reddit (new) | Partial | Shows list items and brackets, not native checkboxes. |
| Reddit (old) | No | Task list syntax is not supported. |
| CommonMark | Partial | Task lists are a GFM extension, not part of the core spec. |
Frequently Asked Questions
How do you make a checkbox in Markdown?
Use an unordered list item followed by a pair of brackets: `- [ ] Unchecked task` or `- [x] Checked task`. The space or `x` must be the only character inside the brackets.
What Markdown syntax creates a checked box?
Place a lowercase `x` inside the brackets: `- [x] Completed task`. Some parsers also accept an uppercase `X`, but lowercase `x` is the most portable.
Are Markdown checkboxes part of standard Markdown?
No. Task lists are a GitHub Flavored Markdown (GFM) extension. They work on GitHub, GitLab, Obsidian, Notion, and most static-site generators, but not in CommonMark by itself.
Can you nest checkboxes in Markdown?
Yes. Indent the child task by two spaces under its parent item: ``` - [ ] Parent - [ ] Child ``` GFM renderers indent the child checkbox visually.
Can you click Markdown checkboxes on GitHub?
Yes. In GitHub issues, pull requests, and comments, GFM checkboxes are interactive. Clicking a checkbox updates the source Markdown in place and triggers a progress check next to the task list heading.
Why does my Markdown checkbox not render?
Common causes are missing spaces inside the brackets (`-[ ]` or `-[x]`), extra spaces around the `x`, missing space after the closing bracket, or using an ordered list number instead of a hyphen.
Does Notion support Markdown checkboxes?
Yes, when you paste Markdown into Notion. A `- [ ] task` list converts into a native Notion to-do block. You can also type `/to` in Notion directly.
How do you write a Markdown to-do list?
A Markdown to-do list is just a task list: write each item as `- [ ] Task name`. Mark completed items with `- [x]`. Combine them with nested indentation for sub-tasks and headings to group related work.
Related Markdown Guides
Checkboxes are an extension of Markdown lists. For related syntax and platform guides: