Markdown Task Lists: Add Checklists and Checkboxes

Checklists are one of the most useful features you can add to a document, and with markdown task list checkboxes you can build them without leaving your plain-text editor. GitHub Flavored Markdown (GFM) extends standard Markdown with a simple, memorable syntax for todo items, and once you know it you can turn any README, issue, or note into a clickable checklist in seconds.

This guide covers the exact syntax, how it renders, how to nest and combine task items, where task lists actually work, and a practical release-checklist example you can copy and adapt.

The GFM task list syntax

A task list is just a regular bullet list where each item starts with a pair of brackets containing either a space or an x:

- [ ] An unchecked task
- [x] A completed task

The rules are simple:

• The line must begin with a list marker (-, +, or *) followed by a space.
• The brackets [ ] must contain exactly one character: a space for "not done" or an x for "done".
• The x is case-insensitive — [x] and [X] both render as a checked box.
• After the closing bracket you need one space before the task text.

So all three of these produce a checked item:

- [x] Write the release notes
- [X] Tag the build
- [X] Publish to npm

GFM is lenient about the contents of the brackets, but to keep your files portable stick to [ ] and [x]. Some renderers will quietly treat [o] or [?] as unchecked, others ignore them entirely.

How task lists render

On GitHub itself, those bracket pairs turn into interactive checkboxes. Readers can click a box directly in the issue or PR and GitHub commits the change back to the source, flipping [ ] to [x] (or the reverse) automatically. This is what makes task lists so popular for tracking issue progress — the document stays plain text, but the UI is fully interactive.

In most other renderers — including static site generators, documentation tools, and the preview pane of a good editor — the checkboxes are non-interactive: they appear as checked or unchecked boxes but can't be toggled by clicking. A handful of editors let you click to toggle in source view, which writes the change back to your file.

Want to see how your own checklist will look before publishing? Paste it into the in-browser editor for an instant live preview, or drop the rendered file into the online MD viewer to inspect the output.

Nested task lists

Task items are list items, which means they nest exactly like ordinary bullets — indent with two or more spaces (four is the common convention) and the nested item becomes a subtask:

- [ ] Launch the landing page
    - [x] Write the copy
    - [x] Design the hero image
    - [ ] Get legal review
- [ ] Set up analytics
    - [ ] Add the tracking snippet
    - [ ] Verify events in the dashboard

Because each task is just a list item, you can nest as deeply as you like. In practice, two levels is plenty; beyond that the document gets hard to read and you should consider splitting it into separate sections.

Mixing task items with regular list items

You don't have to make every bullet a checkbox. Regular list items and task items can sit side by side, which is handy when a list mixes actionable steps with context:

- [ ] Confirm the deploy succeeded in production
- [ ] Smoke-test the checkout flow
- This release includes the new tax engine — see the changelog for details
- [ ] Update the status page

The plain bullets render normally and the bracketed ones render as checkboxes. This works in ordered lists too:

1. [ ] Read the runbook
2. [ ] Open a maintenance window
3. Notify the on-call engineer
4. [ ] Execute the migration script

One caveat: in ordered lists, GitHub renders the checkboxes but you can't toggle them by clicking the way you can with unordered task lists. If you need interactivity, stick to bullets.

Where task lists work (and where they don't)

Support for task lists is part of GFM, so anything that parses GFM will handle them. Here's a quick map:

Environment	Renders checkboxes	Interactive (click to toggle)
GitHub issues, PRs, discussions	Yes	Yes
GitHub README / files	Yes	No (view only)
GitLab	Yes	Yes (in issues)
Most modern Markdown editors	Yes	Sometimes
Plain CommonMark parsers	No — shows literal [ ]	No
Some older wiki engines	No	No

If you're publishing somewhere that only understands base CommonMark, the brackets will show up as literal text. For public docs targeting multiple platforms, test your output in the online MD viewer first. For a broader look at which features belong to GFM versus plain Markdown, our GitHub Flavored Markdown guide breaks it down feature by feature.

Practical example: a release checklist

Here's a realistic checklist you can drop into a RELEASE.md, a GitHub issue, or a project wiki. Copy it, adapt the items, and check them off as you go:

# v2.3.0 Release Checklist

## Code
- [x] Merge `feature/billing` into `main`
- [x] Bump version in `package.json`
- [ ] Update the `CHANGELOG.md`
- [ ] Tag the release (`git tag v2.3.0`)

## QA
- [ ] Run the full test suite on CI
- [ ] Manual smoke test of checkout
- [ ] Verify upgrade path from v2.2.x

## Comms
- [ ] Publish release notes to the blog
- [ ] Post the announcement in `#releases`
- [ ] Update the docs site

A few things worth noticing in this example:

• Tasks are grouped under ## headings so the list stays scannable.
• Completed items use [x]; pending items use [ ] — when a reader scans the file, the unchecked boxes stand out immediately.
• Each task is small and concrete. "Update the changelog" is a checkbox; "finish the release" is not.

Key takeaways

• Task lists use - [ ] for unchecked and - [x] (or - [X]) for checked items.
• On GitHub they render as interactive checkboxes that write changes back to your file; elsewhere they're usually view-only.
• Nest subtasks by indenting, and mix task items freely with plain list items.
• Support is a GFM feature — pure CommonMark parsers will show the brackets literally, so test before you publish.
• Paste a checklist into the live editor to preview it instantly, no install required.

Ready to build your own checklist? Open the in-browser Markdown editor and start ticking boxes.