How to add a checkbox in Markdown:task list syntax and examples.

Markdown task list syntax

A task list is an ordinary list whose items begin with a checkbox marker. The recipe has three parts:

1. A list marker

   A dash, an asterisk or a plus, followed by a space: -. A numbered item such as 1. works too.

2. A box in square brackets

   [ ] with one space inside is an open box. [x] is a ticked one; a capital [X] counts as well. Nothing else goes between the brackets.

3. A space, then the text

   Without the space after ] the line stays plain text with brackets in it.

- [x] Draft the spec
- [x] Add the edge cases
- [ ] Get a review
- [ ] Hand it to the agent

This is what a reader sees:

• Draft the spec
• Add the edge cases
• Get a review
• Hand it to the agent

Nested checkboxes

Indent a task under another one to make a sub-task. Two spaces work in most renderers; four are the safest:

- [ ] Release 2.0
    - [x] Update the changelog
    - [ ] Tag the build
    - [ ] Announce it
- [ ] Plan 2.1

You can mix tasks with ordinary bullets in the same list, and put a paragraph, code or a quote under a task by indenting it to line up with the task's text. The parent box does not tick itself when its children are done; you tick it yourself.

Where Markdown checkboxes render

• GitHub shows task lists as checkboxes in Markdown files, issues, pull requests and comments. In an issue or a pull request you can tick a box on the page and GitHub edits the text for you.
• Markdown apps that follow GFM show them too. In DotMD they appear as boxes in the reader. The boxes are read-only there: to tick one, edit the line and change [ ] to [x].
• Minimal parsers that know only the original Markdown or CommonMark show the text as it is, with the brackets. It still reads as a to-do list, just not as boxes.

If you use DotMD Editor, pressing Enter at the end of a task starts the next one with an empty - [ ], so you can keep typing items.

A Markdown checkmark without a task list

When you want a tick in a table or a sentence, not a list, type the character itself. Unicode symbols are text, so they show up in every Markdown app:

GitHub also accepts emoji shortcodes such as :white_check_mark:. They are a GitHub feature: in another app they may show as the raw text, so prefer the character when the file will be read elsewhere.

Task lists in plans and specs

Task lists are not only for to-do apps. A plan or a spec written in Markdown often ends in a checklist of what is left to do, and each step is easy to review on its own line:

## Tasks
- [x] Add the settings screen
- [ ] Write the migration
- [ ] Update the tests
- [ ] Update the docs

Keep each task to one action that can be finished and checked. Use a heading for each group, and nest sub-tasks only when they belong to one parent.

Why a task list shows brackets instead of boxes

• No space after the bracket: - [x]Done is not a task. Write - [x] Done.
• Spaces inside the brackets: [ ] with two spaces, or [ x ], is plain text.
• No list marker: a line that begins with [ ] alone is not a list item.
• Text that starts with a parenthesis. GitHub's docs say to escape the parenthesis: write - [ ] \(Optional) Test it.
• The renderer lacks GFM. Then you see the brackets whatever you type.

To check how a plan with tasks looks, open the file in DotMD, where reading is free. Specs and plans are often written as task lists, and the boxes make a long one easy to scan.

Questions about Markdown checkboxes

More questions