Markdown task lists and checkboxes

A task list in Markdown is a list of checkbox items, written by starting each list item with - [ ] for an unchecked box or - [x] for a checked one. The space or x sits inside square brackets right after the list marker. Task lists are a GitHub Flavored Markdown extension, not part of core CommonMark, so support varies by renderer.

Markdown task lists and checkboxes syntax reference

Markdown task lists and checkboxes key facts

• Start a list item with - [ ] for an unchecked box or - [x] for a checked box, with a space after the marker and a space or x inside the brackets.
• Task lists are a GitHub Flavored Markdown extension, not part of core CommonMark, so support varies by renderer.
• The brackets must be the first content in the item; text before them makes it an ordinary list item.
• Each item compiles to an <li> containing a checkbox <input>, usually disabled, followed by the item text.
• Checkbox behaviour depends on context. GitHub issues and pull requests can provide editable task items, while README files and most documentation pages render the state without letting a click edit the source.
• Task items nest like any list item, and a parent and its children track their checked state independently.

Separate checkbox syntax from checkbox behaviour

Task-list syntax stores checked and unchecked states in Markdown source. Whether a reader can click the rendered checkbox depends on the application. GitHub issues may make task items interactive, while a static documentation page usually renders disabled checkboxes.

Keep the task text meaningful without relying only on the checked state. Use nested tasks sparingly and align them using the same indentation rules as nested lists. For workflows requiring owners, dates, dependencies, or automation, a project-management system is more suitable than a long Markdown checklist.

Basic syntax

Write a normal list item, then place a pair of square brackets right after the marker. Put a space inside for an unchecked box or an x for a checked box, followed by a space and the item text.

Markdown

- [ ] Write the draft
- [x] Outline the sections
- [ ] Review with the team

Rendered output

HTML output

<ul class="contains-task-list">
  <li class="task-list-item"><input type="checkbox" disabled> Write the draft</li>
  <li class="task-list-item"><input type="checkbox" checked disabled> Outline the sections</li>
  <li class="task-list-item"><input type="checkbox" disabled> Review with the team</li>
</ul>

The exact markup varies by renderer, but the pattern is the same: each item becomes an <li> containing a disabled checkbox <input> followed by the text. On many platforms the checkbox is rendered disabled, so it displays state but cannot be clicked to change it.

Checked and unchecked items

The only difference between a checked and an unchecked item is what sits inside the brackets. A space is unchecked. A lowercase x is checked. Many renderers also accept an uppercase X.

Markdown

- [x] Completed task
- [X] Also completed
- [ ] Not done yet

Rendered output

Nested task lists

Task items nest like any list item. Indent the child items under their parent. Indent by the width needed for your list marker, commonly two or four spaces.

Markdown

- [ ] Ship the release
  - [x] Merge the branch
  - [ ] Tag the version
  - [ ] Publish notes

Rendered output

Mixing task items with regular items

You can mix checkbox items and plain items in the same list. Only the items that start with the bracket syntax become checkboxes.

Markdown

- [ ] A task with a checkbox
- A plain bullet, no checkbox
- [x] Another completed task

Rendered output

Interactivity and toggling

On some platforms the checkboxes are interactive: clicking a box in a rendered document toggles it and updates the underlying Markdown. GitHub, GitLab, and Obsidian support click to toggle in issues, pull requests, and notes. In static renderers, the checkbox shows the state from the source text but is disabled, so you change it by editing the [ ] or [x] in the Markdown.

Interactivity is a platform feature layered on top of the syntax. The Markdown itself only records the checked or unchecked state as text.

Flavor differences

Task lists are a GitHub Flavored Markdown extension. They are not in core CommonMark, and support across the other flavors is partial. Where a flavor does not natively define task lists, a specific renderer or plugin may still add them, so results vary.

Task lists began at GitHub in 2013 and remain a GFM extension. CommonMark deliberately keeps them out of the core spec, in part because their value relies on interactive toggling that goes beyond plain text to HTML conversion. Pandoc supports them through its task_lists extension. MultiMarkdown and Markdown Extra do not define task lists in their core syntax, so their cells are marked Verify: a specific build or plugin may add checkbox rendering, but you should confirm it in the tool you use.

Other platforms (GitLab, Obsidian, Notion, Reddit)

• GitLab: full task list support with interactive toggling, similar to GitHub.
• Obsidian: renders task lists and supports click to toggle, with plugins that add extra checkbox states.
• Notion: uses its own to-do block. Pasted - [ ] Markdown may convert to a to-do block on import, but it is not the same syntax internally.
• Reddit: does not render GFM task lists. The bracket syntax shows as literal text.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific renders task list items as list entries with a checkbox reflecting the checked or unchecked state from the source. Items written with - [x] show as checked, and items written with - [ ] show as unchecked.

Try it in the Markdific online editor.

Common mistakes and gotchas

• No space inside the brackets. An unchecked box is - [ ] with a space between the brackets. Writing - [] with nothing inside is not a task item in most renderers.
• Missing the space after the marker. The list marker, a space, then the brackets: - [ ]. Skipping the space after the dash breaks the item.
• Text before the brackets. The brackets must be the first content in the item. Text before them makes it a plain list item.
• Expecting checkboxes in CommonMark or Reddit. These do not render task lists, so the brackets appear as literal text.
• Assuming boxes are always clickable. Interactivity depends on the platform. Many renderers show a disabled checkbox that you change by editing the source.
• Using a capital letter where the renderer wants lowercase. Most renderers accept x and X, but if a checkbox fails to fill, try lowercase x.

Best practices

• Use - [ ] and - [x] with a single space inside and after the brackets.
• Keep the brackets as the first content of the item, right after the marker.
• Use lowercase x for checked items for the widest compatibility.
• Reserve task lists for platforms that support them. For portable documents, remember they may show as raw brackets elsewhere.
• Nest subtasks with consistent indentation, and do not assume a parent auto checks when its children are done.
• For a portable plain-text checklist, a regular bulleted list may be safer.

HTML equivalent

Task list items compile to list items that each contain a checkbox <input>, usually disabled, followed by the item text. Checked items add the checked attribute.

Markdown

- [x] Done
- [ ] Todo

HTML output

<ul class="contains-task-list">
  <li class="task-list-item"><input type="checkbox" checked disabled> Done</li>
  <li class="task-list-item"><input type="checkbox" disabled> Todo</li>
</ul>

FAQ

How do you make a checkbox in Markdown? Start a list item with a dash and a space, then square brackets. Put a space inside for an unchecked box or an x for a checked box, like a dash, a space, then open bracket, space, close bracket.

Are task lists part of standard Markdown? No. Task lists are a GitHub Flavored Markdown extension. They are not in core CommonMark, and support in MultiMarkdown and Markdown Extra should be verified per renderer.

What is the difference between a checked and unchecked item? The character inside the brackets. A space is unchecked and a lowercase x is checked. Most renderers also accept an uppercase X for a checked box.

Are Markdown checkboxes clickable? It depends on the platform. GitHub, GitLab, and Obsidian let you click to toggle. Many other renderers show a disabled checkbox, so you change the state by editing the brackets in the source.

Do task lists work on GitHub? Yes. GitHub introduced task lists and renders them as interactive checkboxes in issues, pull requests, and Markdown files.

Can you nest task lists in Markdown? Yes. Indent child items under a parent item the same way you nest a regular list. Each checkbox tracks its own state unless a platform links parents and children.

Why is my task list showing as plain text? The renderer probably does not support task lists, or the syntax is off. Check for a space inside the brackets, a space after the list marker, and that you are on a platform such as GitHub that supports the extension.

Can you make an ordered or numbered task list in Markdown? Some renderers accept 1. [ ] with a number instead of a dash, but support is less consistent than the unordered form. The widely supported syntax uses a dash, so prefer - [ ] unless you know your renderer handles numbered task items.

How do you check off a task in a rendered Markdown document? On GitHub, GitLab, and Obsidian you click the checkbox to toggle it, which updates the underlying [ ] or [x] in the source. In static renderers the box is disabled, so you check it off by editing the brackets in the Markdown.

Does a Markdown task list show completion progress? The syntax itself does not track progress. Some platforms, such as GitHub issues and pull requests, add a progress indicator that counts checked items, but that is a platform feature layered on top of the plain Markdown.

What is the difference between a task list and a regular bulleted list? A task list item starts with - [ ] or - [x] and renders as a checkbox, while a regular bullet has no brackets and renders as a plain marker. Only items that begin with the bracket syntax become checkboxes.

Sources and compatibility references

• GFM specification: task-list items
• GitHub: task lists

Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.

Related pages

• Markdown documentation hub
• Lists in Markdown
• Strikethrough in Markdown
• Blockquotes in Markdown
• Markdown flavors compared