Task Lists and Checkboxes in Markdown: How to Track To-Dos in Plain Text

A Markdown task list is a bulleted list where each item starts with a checkbox: [ ] for something still to do, [x] for something done. It is plain text you can type anywhere, and on any tool that speaks GitHub Flavored Markdown it renders as a real, clickable checkbox. Here is how to write task lists, where they work, and how to keep your to-dos portable.

Quick answer

Start a normal bulleted list, then put a pair of square brackets right after the dash. Leave a space inside the brackets for an open task, or put an x inside for a finished one:

- [ ] Draft the release notes
- [x] Tag the version
- [ ] Publish the post

Two details decide whether it works. First, the space after the closing bracket is required — so - [ ]Buy milk will not parse as a task. And the letter is case-insensitive: [x] and [X] both mark an item complete (GFM spec). In a renderer that understands GitHub Flavored Markdown, each line becomes a checkbox. In a plain editor it stays readable exactly as typed, which is the point of keeping to-dos in Markdown.

Step-by-step

Write the checkboxes

Each task list item is a list item whose text begins with a task list marker: a left bracket, either a space or an x, then a right bracket, followed by at least one space (GFM spec). The bullet itself can be -, *, or + — they all work the same way:

- [ ] Outline the article
* [ ] Find two sources
+ [x] Pick a title

Keep it to one task per line. A task list is just an ordinary Markdown list with markers added, so everything you already know about lists carries over — including the rule that you need a blank line between a paragraph and the first item. If you write READMEs, the same lists show up there too; see our guide to writing a README in Markdown.

Nest subtasks

Indent a task by two spaces (or a tab) to make it a subtask of the line above:

- [ ] Ship the update
  - [x] Write tests
  - [ ] Update the changelog
  - [ ] Bump the version

Nesting lets one checklist hold a small project without ever leaving plain text.

Add links, code, and detail

After the checkbox, a task line is normal Markdown, so you can drop in links, inline code, or emphasis:

- [ ] Review the pull request before Friday
- [ ] Fix the `parseDate()` edge case

On GitHub, a task that references an issue or pull request shows up as a tracked item with a progress count, so a plain checklist doubles as a tracker (GitHub Docs).

Check things off

Where the Markdown is rendered interactively — GitHub issues, pull requests, comments, and Markdown files in a repository — you click a checkbox to toggle it, and the underlying text flips from [ ] to [x] on its own (GitHub Docs). In a static rendered page the boxes show their state but are not clickable; there you edit the text to change them.

Common problems and fixes

A handful of things trip people up — and most are one-character fixes.

| Symptom | Cause | Fix | |---|---|---| | Box shows as literal [ ] text | Renderer only supports plain CommonMark | Task lists are a GFM extension, not in core CommonMark (CommonMark); open the file in a GFM-aware tool | | Item is a bullet, not a checkbox | No space after the ] | Write - [ ] task, not - [ ]task | | The whole list fails to form | No blank line before it | Put a blank line between the previous paragraph and the first item | | Checkbox will not toggle | It is a static page, not an interactive view | Edit the [ ] / [x] text directly |

The important one is portability. Because task lists are an extension, a file full of checkboxes is still valid, readable plain text everywhere — it simply will not show clickable boxes in tools that stick to plain CommonMark. Markdown was designed so the source reads cleanly on its own (Daring Fireball), which is why a checklist is useful even before anything renders it.

Doing this with Carets

Carets is a fast, native notes and code editor for iPhone, iPad, and Mac, built around Markdown and plain text — a natural home for checklists you want to keep and reuse. Your notes are plain .md files, so a task list you write in Carets stays portable: the same [ ] and [x] text opens in any Markdown tool and outlasts any single app.

A few things make daily tracking easy. Markdown and plain text are first-class, so you type - [ ] and keep moving instead of hunting for a checkbox button. Files, projects, and tags keep separate checklists — a release plan, a reading list, a grocery run — organized and searchable. And syntax highlighting makes the markers and any inline code easy to scan at a glance. It is the same editor across iPhone, iPad, and Mac, so a list you start on your phone is waiting on your desktop. Browse more Markdown how-tos when you want the next one.

Carets is available on the App Store for iPhone, iPad, and Mac.

FAQ

Do Markdown task lists work everywhere?

No. They are part of GitHub Flavored Markdown, an extension to the CommonMark spec (CommonMark). Anywhere GFM is supported they render as checkboxes; in a plain CommonMark renderer they appear as literal [ ] text but stay perfectly readable.

What is the difference between [ ] and [x]?

[ ] — a space between the brackets — is an open task. [x] is complete. The letter is case-insensitive, so [X] works too (GFM spec).

Can I nest task lists?

Yes. Indent a task by two spaces or a tab under its parent line to create subtasks, the same way you nest any Markdown list.

Can I check a box without editing the text?

In interactive views like GitHub issues, pull requests, and comments, click the box and the Markdown updates itself. On a static rendered page, edit the [ ] / [x] text directly.