Markdown Checkbox
How to make checkboxes and task lists in Markdown, where you can actually click them, and what to do in tables, numbered lists, and apps that do not support them.
Short answer
Write a list item with brackets: - [ ] To do for an empty box, - [x] Done for a checked one. This is a GitHub Flavored Markdown extension, not core Markdown. On GitHub the boxes are clickable in issues, pull requests, and comments, but read-only in a README or any other .md file.
Basic Syntax
A checkbox is a list item whose text starts with a bracket pair. The pieces are: list marker, space, [, one character, ], space, then the task text.
- [ ] Buy groceries
- [x] Walk the dog
- [ ] Write the changelog- Buy groceries
- Walk the dog
- Write the changelog
### Today
- [x] Check metrics
- [ ] Reply to blocked PRs
### This week
- [ ] Interview candidatesToday
- Check metrics
- Reply to blocked PRs
This week
- Interview candidates
Each heading ends the list above it, so you get one checklist per section.
Checked vs Unchecked
A space inside the brackets is unchecked. An x is checked, and the GFM spec accepts an uppercase X as well. Anything else, including an empty pair or extra spaces, is not a checkbox at all.
- [x] Lowercase x
- [X] Uppercase X
- [ ] Unchecked- Lowercase x
- Uppercase X
- Unchecked
Nested and Numbered Tasks
Indent a sub-task so its marker lines up with the parent's text: 2 spaces under a - item, 3 under a 1. item. The full rule is in the nested lists guide.
- [ ] Ship v2.0
- [x] Finalize API
- [x] Write docs
- [ ] Update screenshots
- [ ] Announce release- Ship v2.0
- Finalize API
- Write docs
- Update screenshots
- Announce release
1. [x] Back up the database
2. [ ] Run the migration
3. [ ] Notify the team- Back up the database
- Run the migration
- Notify the team
The GFM spec defines task items on any list item, so numbered checklists render on GitHub and GitLab too.
Clickable Checkboxes on GitHub
Where you write the task list on GitHub decides whether people can tick it.
| Where | Checkboxes |
|---|---|
| Issue or pull request description | Clickable. Progress (for example 1 of 3) shows in the repository's issue list. |
| Comments and discussions | Clickable. Clicking rewrites the [ ] or [x] in the comment for you. |
| README and other .md files | Read-only. Edit the file to change a box. |
## Before merging
- [ ] Tests pass locally
- [ ] Docs updated
- [ ] \(Optional) Screenshot attachedBefore merging
- Tests pass locally
- Docs updated
- (Optional) Screenshot attached
GitHub's docs say to escape a parenthesis that starts the task text, as in \(Optional).
```[tasklist] preview feature on April 30, 2025 and points people to sub-issues instead. Plain - [ ] task lists were never part of that and still work.Checkboxes in Tables, and Literal Brackets
Task syntax only works at the very start of a list item. Inside a table cell, [x] is just text, and GitHub's HTML allowlist does not include <input>, so a raw HTML checkbox is removed. Use a symbol.
| Task | Done |
| ------------- | :--: |
| Write tests | ✅ |
| Update docs | ⬜ || Task | Done |
|---|---|
| Write tests | ✅ |
| Update docs | ⬜ |
On GitHub you can also type :white_check_mark: and :white_large_square: shortcodes.
- \[ ] Not a checkbox, just brackets
- \[x] Also plain text- [ ] Not a checkbox, just brackets
- [x] Also plain text
A backslash before [ stops the task marker from forming.
Obsidian Task States
Obsidian uses the same syntax and lets you tick boxes in Reading view. It also counts any character in the brackets as complete, which is how people build extra states. On their own these all render as checked; distinct icons come from a theme or CSS snippet, and the Tasks plugin can treat them as statuses.
- [x] Done
- [/] In progress
- [-] Cancelled
- [?] Question- Done
- [/] In progress
- [-] Cancelled
- [?] Question
On GitHub and in other GFM renderers, only [x] is a checkbox. The other three show as literal text, as in this preview.
Platform Support
Task lists need GitHub Flavored Markdown or an equivalent extension. Where they are missing, the brackets show up as text.
| Platform | Supported? | Notes |
|---|---|---|
| GitHub | Yes | Clickable in issues, pull requests, discussions, and comments. Read-only in .md files such as a README. |
| GitLab | Yes | Clickable in issues, merge requests, epics, and comments. Also supports [~] for an inapplicable task. |
| Obsidian | Yes | Clickable in Reading view. Any character in the brackets marks the task done; custom icons need a theme or CSS snippet. |
| VS Code preview | No | The built-in preview shows a bullet with literal [ ] / [x]. The Markdown Checkboxes or Markdown All in One extension adds checkboxes. |
| Docusaurus / Astro | Yes | Both enable GitHub Flavored Markdown by default, so task lists render as read-only checkboxes. |
| MkDocs | Partial | Python-Markdown has no task lists on its own; add the pymdownx.tasklist extension. |
| Notion | Partial | Native to-do blocks: type [] then space. Notion does not document converting pasted - [ ] lines. |
| Slack | Partial | Only inside Block Kit markdown blocks sent by apps (added March 2026). Not in the composer or mrkdwn. |
| Discord | No | - [ ] renders as a bullet followed by literal brackets. |
| No | Not part of Reddit's Markdown. The brackets show as text. | |
| CommonMark | No | Core CommonMark renders literal [ ] text. Checkboxes come from the GFM task list extension. |
Common Mistakes
A checkbox that will not render is nearly always a spacing problem inside or around the brackets.
Broken
- [] Empty taskFixed
- [ ] Empty taskBroken
- [ x ] TaskFixed
- [x] TaskBroken
- [x]TaskFixed
- [x] TaskBroken
[ ] Task with no list markerFixed
- [ ] Task with a list markerBroken
- [x] Item 1
- [x] Subtask A
- [ ] Subtask BFixed
- [x] Item 1
- [x] Subtask A
- [ ] Subtask BQuick Reference
| Syntax | Result | Notes |
|---|---|---|
| - [ ] task | Unchecked | Space inside the brackets |
| - [x] task | Checked | Lowercase x |
| - [X] task | Checked | Uppercase also valid in GFM |
| * [ ] task | Unchecked | Any bullet marker works |
| 1. [ ] task | Numbered task | Valid GFM; renders on GitHub and GitLab |
| - [ ] task | Nested task | 2 spaces under a - parent |
| - \[ ] task | Literal [ ] | Backslash escapes the bracket |
| - [~] task | Inapplicable | GitLab only |
| - [-] task | Custom state | Obsidian themes and plugins; checked by default |
Frequently Asked Questions
How do you make a checkbox in Markdown?
Start a list item, then add a pair of brackets and a space: - [ ] for an empty box or - [x] for a checked one. The brackets must hold exactly one character, and there must be a space after the closing bracket.
How do you check a box in Markdown?
Put an x between the brackets: - [x] Done. GitHub Flavored Markdown accepts lowercase x or uppercase X. To uncheck it, replace the x with a space.
Are checkboxes part of standard Markdown?
No. Task lists are a GitHub Flavored Markdown extension. GitHub, GitLab, Obsidian, and most static site generators support them (VS Code's built-in preview needs an extension), but a strict CommonMark parser shows - [ ] as a bullet with literal brackets.
Can you click Markdown checkboxes on GitHub?
Yes, in issues, pull requests, discussions, and comments. Clicking a box edits the underlying Markdown for you, and an issue's task progress shows up in places like the repository's issue list.
Why can't I check the boxes in my README?
GitHub renders task lists in Markdown files as read-only checkboxes. To change one, edit the file and swap [ ] for [x], which needs write access to the repository. Use an issue if you want boxes people can click.
Can you nest checkboxes in Markdown?
Yes. Indent the child task so its marker lines up with the parent's text, which is 2 spaces under a - item: - [ ] Parent - [ ] Child
Can I use checkboxes in a numbered list?
Yes. GitHub Flavored Markdown defines task items on any list item, so 1. [ ] Step renders a numbered checkbox on GitHub and GitLab. Use a bullet list if the file also has to render in a tool you have not tested.
How do I put a checkbox in a Markdown table?
Task list syntax only works at the start of a list item, so - [ ] inside a table cell stays as text. Use a symbol instead, such as ✅ and ⬜, or GitHub's :white_check_mark: shortcode. Raw <input type="checkbox"> HTML is not on GitHub's allowed-tag list.
How do I show [ ] without it turning into a checkbox?
Escape the opening bracket with a backslash: - \[ ] text. On GitHub, also escape an opening parenthesis right after the box, as in - [ ] \(Optional) text, which GitHub's docs call out.
Why is my Markdown checkbox not rendering?
Check for empty brackets ([]), spaces around the x ([ x ]), no space after the bracket ([x]Task), a missing list marker in front, or a platform that does not support task lists, such as Discord, Reddit, or a strict CommonMark renderer.
Does Obsidian support other checkbox states like [-] or [/]?
Obsidian treats any character inside the brackets as complete, so [-], [/], and [?] all render as checked by default. Different icons for each state come from a theme or CSS snippet, and the Tasks plugin can treat them as statuses such as In Progress or Cancelled.
Do Notion, Slack, and Discord support Markdown checkboxes?
Notion has native to-do blocks: type [] then space. Slack renders - [ ] only inside Block Kit markdown blocks that apps send. Discord does not support task lists; the brackets show as plain text.
What happened to GitHub tasklist blocks?
The ```[tasklist] code-block feature was a GitHub preview that was retired on April 30, 2025, with sub-issues as the replacement. Ordinary - [ ] task lists were not affected and still work everywhere on GitHub.