MDUtil

Checkboxes and Task Lists in Markdown

A list item that starts with [ ] becomes an empty checkbox, and one that starts with [x] a ticked one. This guide covers task list syntax, the mistakes that break it, and which apps let you click the boxes.

Quick answer

How do you make a checkbox in Markdown?

Write a list item with square brackets after the marker: - [ ] task for an empty checkbox and - [x] task for a ticked one. Task lists come from GitHub Flavored Markdown and work on GitHub, GitLab, Obsidian and most editors.

Markdown
- [x] Pick a title
- [ ] Write the draft
- [ ] Ask for a review

Result

  • Pick a title
  • Write the draft
  • Ask for a review

Task list syntax and examples

A task is an ordinary list item with brackets at the start, so everything that works in lists works here too.

Empty and ticked boxes

Put a space between the brackets for an open task and an x for a done one. An uppercase X works too.

Markdown
- [ ] Open task
- [x] Done task
- [X] Also done

Result

  • Open task
  • Done task
  • Also done

Numbered tasks

Brackets work after numbers as well, for steps that must happen in order.

Markdown
1. [x] Back up the database
2. [ ] Run the migration
3. [ ] Check the logs

Result

  1. Back up the database
  2. Run the migration
  3. Check the logs

Nested tasks

Indent a task under another to split it into smaller steps.

Markdown
- [ ] Launch the new site
  - [x] Write the release notes
  - [ ] Update the screenshots

Result

  • Launch the new site
    • Write the release notes
    • Update the screenshots

With formatting and links

The text after the brackets can hold bold text, links and strikethrough.

Markdown
- [x] ~~Fix the login bug~~
- [ ] Review [the pull request](https://example.com/pull/42)
- [ ] **Release** version 2.0

Result

Mistakes that break a checkbox

The brackets need a space or an x inside, a space must follow them, and the line must be a list item.

Markdown
- [] Empty brackets
- [x]No space after the bracket

[ ] No list marker

Result

  • [] Empty brackets
  • [x]No space after the bracket

[ ] No list marker

GitLab: tasks that no longer apply

GitLab adds a third state, [~], for tasks that no longer apply.

Markdown
- [x] Write the code
- [~] Translate the docs
- [ ] Ship it

GitLab only. Other Markdown apps display this differently, so there is no preview.

Checkboxes in popular apps

Every app that follows GitHub Flavored Markdown shows the boxes. Whether you can click them depends on the app and the page.

AppSupportNotes
GitHubSupportedBoxes in issues, pull requests and comments can be clicked; in files they are read-only.
GitLabSupportedClickable in issues and merge requests. [~] marks a task that no longer applies.
ObsidianSupportedBoxes can be clicked in reading view and live preview.
NotionDiffersTyping [] makes a to-do block.
DiscordNot supportedBrackets are shown as typed.
SlackNot supportedMessages have no checkboxes.

Questions and answers

Why isn't my checkbox showing?

Check that the line starts with a list marker such as - , that the brackets hold a space or an x ([] does not work), that a space follows the ], and that the app supports GitHub Flavored Markdown.

Can I click the checkboxes?

In GitHub and GitLab issues, pull requests and comments, yes: clicking a box updates the text. In rendered files and most previews the boxes are read-only.

Can I use an uppercase X?

Yes. [X] and [x] both mark a task as done.

Can tasks be nested or numbered?

Yes. Indent a task under another to nest it, or write 1. [ ] for a numbered task.

How do I add a checkbox outside a list?

Markdown makes checkboxes only in list items. Outside a list, type the characters ☐ and ☑ instead.

Do checkboxes work in Notion, Discord or Slack?

Notion makes a to-do block when you type []. Discord and Slack have no checkboxes and show the brackets as typed.

How does GitHub count tasks?

GitHub counts the boxes in a pull request's description and shows the progress, such as "1 of 3 tasks", in the list of pull requests.

What HTML does a task list produce?

Each task becomes a list item that starts with <input type="checkbox" disabled>, with checked added for done tasks.