Markdown task lists: - [ ] and - [x] explained

Task lists are the part of Markdown that turns a file into a to-do list. You will see them in project notes, release checklists, and in many plans that AI agents write.

This page explains the syntax, the common mistakes, and how to read and tick task lists in practice. For every other element, see the Markdown syntax guide.

The syntax

A task is a list item that starts with a box:

- [ ] Write the release notes
- [x] Update the version number

Result:

• Write the release notes
• Update the version number

Each task has four parts, in this order:

1. A list marker: -, * or +, or a number like 1.
2. One space.
3. The box: [ ] for open, [x] for done. The open box needs whitespace inside. Use a space.
4. One space, then the task text.

GFM also accepts an uppercase [X] as done.

Why a box does not render

If you see [ ] as text instead of a check box, the cause is usually one of these:

You wrote	Problem	Fix
[ ] Task	No list marker	- [ ] Task
-[ ] Task	No space after the marker	- [ ] Task
- [] Task	Nothing inside the box	- [ ] Task
- [ ]Task	No space after the box	- [ ] Task
- [v] Task	Only whitespace, x or X counts	- [x] Task

If the syntax is right and the box still shows as text, the tool you are using does not support GFM task lists. The file is fine. Open it in a viewer that supports GFM.

Nested tasks

Indent a child task by two spaces under - [ ] , so its - sits under the parent's box. Use three spaces under 1. [ ] .

- [ ] Ship the settings page
  - [x] Build the form
  - [ ] Add validation
  - [ ] Write tests
- [ ] Update the docs

Result:

• Ship the settings page
  • Build the form
  • Add validation
  • Write tests
• Update the docs

A ticked child does not tick its parent. Each box is separate. If you want the parent done only when every child is done, you tick it yourself.

Numbered task lists

Put the box after the number:

1. [x] Back up the database
2. [ ] Run the migration
3. [ ] Check the row counts

This is useful when order matters, such as steps in a plan.

How to tick a box

1. Open the Markdown file in a plain text editor.
2. Change the space inside the task's [ ] to x, making [x].
3. Save the file, then check it in a viewer with GFM support.

That changes one character, so it makes a small diff. Some rendered editors also let you click a box and save the change. Many web pages show boxes you cannot click.

A good habit when you review someone else's list, or an agent's: tick a box when you have checked the work, not when the list says it is done. That keeps the list honest.

Count open and done tasks from the terminal

Long plans can have dozens of tasks. A quick count tells you where things stand before you read anything. These commands work in the macOS and Linux terminal.

Count open tasks:

grep -cE '^[[:space:]]*[-*+] \[ \]' plan.md

Count done tasks:

grep -cE '^[[:space:]]*[-*+] \[[xX]\]' plan.md

List open tasks with their line numbers, including numbered ones:

grep -nE '^[[:space:]]*([-*+]|[0-9]+[.)]) \[ \]' plan.md

The counts include nested tasks. The first two commands skip numbered task lists; the third one includes them. They are quick checks, not a parser. They also count lines inside code blocks and lines like - [ ]Task that do not render as tasks.

Task lists in AI agent plans

Coding agents often write their plans as task lists. Each step is a box, and the agent ticks steps as it goes. That makes the plan easy to scan. It also means the file changes while you read it.

Two tips for reviewing these plans:

• Read the open tasks first. They tell you what is left and where the agent might need you.
• Treat a ticked box as a claim. Check the result before you trust it.

The guide on reading a Claude Code plan file walks through a full review, and how to review the Markdown your AI agents write covers the wider loop.

Where Skimmark fits

Skimmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development and has not been released. The app itself has no AI features.

Planned for v1: check-box lists rendered as boxes, with edit in place on the rendered page. The save leaves the lines you did not edit byte-for-byte the same. When it cannot promise that, Document Lock turns editing off for that file. Live Reload keeps your place when an agent ticks boxes in the same file.

You can see what Skimmark is and follow along at skimmark.com.