Markdown Checkboxes: How to Make a Task List
By the MDConverter team · Updated · 2 min read
Quick answer
A Markdown checkbox is a list item that starts with - [ ] (unchecked) or - [x] (checked). Task lists are a GitHub Flavored Markdown extension, so they work on GitHub, GitLab, Obsidian, VS Code, Notion imports and most modern editors. On GitHub issues and pull requests the boxes are clickable; in files and most renderers they are display-only.
Task list syntax
Write a list marker, a space, square brackets with a space (or an x) inside, another space, then the task.
- [x] Book the venue
- [x] Send invitations
- [ ] Order catering
- [ ] Print name badges- Book the venue
- Send invitations
- Order catering
- Print name badges
x both mark a box as done. The space inside [ ] is required.Nested tasks and numbered checklists
Indent sub-tasks under a parent the same way as nested lists. Numbered task lists work too.
1. [x] Draft the report
2. [ ] Review
- [x] Check figures
- [ ] Proofread
3. [ ] Send to the client- Draft the report
- Review
- Check figures
- Proofread
- Send to the client
Where checkboxes are clickable
- GitHub issues and pull request descriptions: clicking a box edits the Markdown for you, and GitHub shows progress ("2 of 4 tasks") on the issue. In
.mdfiles on GitHub they are not clickable. - Obsidian, Typora, Joplin, Logseq: click in reading or live-preview mode.
- VS Code preview, MkDocs, static sites: shown as disabled checkboxes.
- Notion: imported task lists become to-do blocks; typing
[]in Notion creates one.
Checkboxes inside tables
Task list syntax only works at the start of a list item, not inside a table cell. In tables, use emoji (✅ ⬜) or Unicode boxes (☑ ☐) instead. MarkdownTables.com covers the options in checkboxes in Markdown tables.
Checklists in Word, PDF and plain text
When you export a checklist, Markdown to Word writes ☐ and ☒ symbols at the start of each item so the list prints clearly, Markdown to PDF shows checkbox shapes, and Remove asterisks from ChatGPT text turns them into ☐ and ☑ characters that survive in any text box.
Task list support by app
| App | Supported | Notes |
|---|---|---|
| GitHub issues & PRs | Yes | Clickable, with progress shown on the issue. |
| GitHub .md files | Partly | Rendered as checkboxes, not clickable. |
| GitLab | Yes | Clickable in issues and merge requests. |
| Obsidian | Yes | Clickable; extra states such as [/] with community themes. |
| VS Code preview | Partly | Rendered, not clickable. |
| Discord, Slack | No | Shown as literal [ ] text. |
| No | Not supported; use emoji. |
Common mistakes and how to fix them
| Problem | Fix |
|---|---|
-[ ] shows brackets instead of a box | Add a space after the dash: - [ ]. |
- [] Task is not a checkbox | Put a space inside the brackets: - [ ]. |
| Box not clickable on GitHub | Clickable boxes work in issues, PRs and comments, not in repository files. |
| Task text starting with “(” breaks the box | GitHub asks you to escape it: - [ ] \(Optional) item. |
Tools for this
Frequently Asked Questions About Checkboxes & task lists
Comprehensive answers to common technical, formatting, security, and compatibility questions.
Related reading
- Markdown Lists: Bullet Points, Numbered Lists and Nested Lists — Bullets, numbered lists, nesting, starting numbers and the indentation rules that trip people up.
- Markdown Flavors: CommonMark vs GitHub Flavored Markdown and More — Why the same Markdown renders differently, and what each major flavor adds.
- How to Make a Collapsible Section in Markdown — Hide long content behind a click with <details> and <summary> — with Markdown inside.