Markdown Task Lists and Checklists: Syntax and Workflow

A markdown task list is a bulleted list where each item starts with [ ] or [x]. That is all the syntax there is, and it turns any note into a to-do list that sits next to the context it belongs to. Task lists are a GitHub Flavored Markdown extension, so they are widely supported but not part of the original markdown. This guide covers the syntax, nesting, a workflow that holds up over weeks, and the real limits.

The syntax

- [ ] Write the draft
- [x] Choose a title
- [ ] Send for review

Each line is a dash, a space, an opening bracket, a space for open or an x for done, a closing bracket, another space, then the task text. Both spaces matter: -[ ] and - [] will not be recognized as tasks. A capital X usually works as well, but lowercase is the convention.

Numbered tasks work too, using the numbered-list form:

1. [x] Book venue
2. [ ] Send invitations

Nested tasks

Indent a task under its parent to break a larger job into steps.

- [ ] Launch the newsletter
  - [x] Write welcome email
  - [ ] Review design
  - [ ] Test links
- [ ] Plan the first issue

Indent by two to four spaces, using the same amount throughout the note. Mixed indentation is the most common reason a nested list renders flat. Whether a parent task appears finished when all its children are ticked depends on the app. In most editors it does not change automatically, so tick the parent yourself.

Mixing tasks with notes

The real advantage over a separate to-do app is context. A task written inside the note it came from carries its reasons with it. Useful patterns:

• Meeting notes: write discussion as normal text and capture action items as tasks, with the owner’s name in the line.
• Project page: keep a “Next steps” heading with a task list under it, and move finished tasks to a “Done” heading.
• Reading notes: add follow-up tasks such as “check the source” beside the passage that prompted them.

## Action items
- [ ] Ada: send the revised outline
- [ ] Sam: confirm the date
- [x] Ada: book the room

A lightweight workflow

1. Capture inline. Whenever a task comes up while you write, type - [ ] and the task on the spot. Do not stop to organize.
2. Tag notes that hold open work. Add a tag such as #todo to the note so you can find it later.
3. Review weekly. Open the tagged notes, tick what is done, delete what is no longer relevant and rewrite vague tasks.
4. Link related notes. Use wiki links such as [[Newsletter launch]] so a task can point to the note with the details.
5. Archive finished notes. When every task is ticked, remove the tag so the review list stays short.

Write tasks as actions that start with a verb (“Email Sam the draft”, not “Draft”). A task you can finish in one sitting gets done; a task that is really a project stays unticked for months.

Using task lists in atiea

atiea highlights markdown as you type, so a task list is easy to scan in the editor as you write it. Inline #tags let you mark notes that have open work, [[wiki links]] connect a task to a detail note, and pinned notes keep your current checklist at the top of the note list. Use Cmd+F to find tasks by text and Cmd+N to start a new checklist note quickly. See the full feature list for everything else.

Example: a weekly review note

Here is a complete note you could copy as a starting point. It combines a tag, headings, wiki links and tasks:

# Weekly review #todo

## This week
- [x] Send invoice
- [x] Reply to the editor
- [ ] Finish chapter outline, see [[Book project]]

## Next week
- [ ] Book dentist
- [ ] Draft talk abstract
  - [ ] Collect three examples
  - [ ] Ask Sam for feedback

## Waiting on others
- [ ] Printer quote from Ada

Each Friday, duplicate the headings into a new note, carry over anything still unticked and leave the old note as a record of what you finished. A “Waiting on others” section is worth having because tasks you cannot act on otherwise clutter the list you can.

Common mistakes

• Missing space after the dash or inside the brackets. The line then renders as plain text.
• Putting a task directly after a paragraph with no blank line. Some renderers merge it into the paragraph.
• Tabs mixed with spaces. Nesting breaks. Pick one.
• One giant list. A hundred unticked items is a pile, not a plan. Split by project and prune often.

Limits and when not to use this

Standard markdown task lists have no due dates, reminders, priorities, recurring tasks or assignment. If a task must happen at a specific time, put it in a calendar or reminders app and keep the note for context. If you coordinate tasks with several people and need status views, a dedicated task manager is a better fit than a text file. Markdown checklists work best for personal work, project notes and lists that live inside the note that explains them.

It is also worth knowing that a rendered checkbox is not guaranteed to be clickable in every app or exported file. In some tools you tick a task by editing the x in the source. Check how your editor behaves before you build habits around it.

Related reading

The markdown cheat sheet lists the rest of the syntax, and how to take notes in markdown shows where checklists fit in a wider note-taking routine. If you are comparing apps for this, start with the atiea markdown editor page or the app checklist. If Apple Notes is your current tool, see whether Apple Notes supports markdown.