Markdown Checklist Syntax: Task Lists, Nesting and Shortcuts

Markdown checklist syntax is a list marker, a space, square brackets with a space inside, another space, then the task. So - [ ] Buy milk is an open item and - [x] Buy milk is a done one. The syntax comes from GitHub Flavored Markdown (GFM), which calls it a "task list". Original Markdown and strict CommonMark don't include it, so renderers that follow only those show the brackets as plain text.

The exact Markdown checklist syntax

- [ ] Draft the outline
- [ ] Email Sam the budget
- [x] Book the meeting room

Each part matters:

A GFM renderer turns each item into a list item with a checkbox in front. In the HTML output, that checkbox is a disabled <input type="checkbox">. This is why a rendered Markdown file usually shows boxes you can't click. Some apps make them clickable, as covered in the app support section below.

Numbered checklists

You can also use an ordered list marker:

1. [ ] Back up the laptop
2. [ ] Install the update
3. [ ] Restart

This renders numbers and checkboxes together, which helps when the order of steps matters.

Showing literal brackets

If you want a list item that starts with [ ] as text instead of a checkbox, escape the first bracket with a backslash:

- \[ ] This shows the brackets as text

Nested checklist items

Indent a child item so that its list marker lines up under the parent's text. Under a - parent, that means two spaces. Four spaces also works in GFM and is easier to see.

- [ ] Launch the newsletter
  - [x] Pick a sending tool
  - [ ] Write the first issue
    - [ ] Intro
    - [ ] Three links
  - [ ] Set a send date

Under a numbered parent like 1. , the text starts three characters in, so indent the child three spaces:

1. [ ] Move house
   - [ ] Book the van
   - [ ] Change the address with the bank

These mistakes break nesting:

• Too little indentation. One space under - makes the line a new item at the same level, not a child.
• Mixed tabs and spaces. Spaces behave the same in every renderer, so stick to them.
• Indenting too far. Four or more spaces beyond where the parent's text starts can turn the line into a code block if a blank line comes before it. Without the blank line, it can get merged into the parent's text.

In plain Markdown, ticking a parent doesn't tick its children. Each box is independent, so a parent marked [x] with [ ] children is valid and renders exactly as written.

Which apps support Markdown checklists

Apps handle checklists in one of three ways. Some show the brackets as text, some render read-only checkboxes, and some render boxes you can click.

Suppose you write checklists in a .md file for a website, a docs tool or a static site generator, and the boxes appear as [ ] text. Check whether the tool's Markdown library has a GFM or "task lists" option, and whether that option is switched on.

Markdown note apps differ in whether boxes are clickable and which shortcut toggles them. Check each app's own documentation before you rely on either.

Markdown keyboard shortcuts for checklists

Markdown itself has no keyboard shortcuts because it's just text. In a plain text editor you type - [ ] by hand. Editors that convert Markdown as you type add their own shortcuts.

In Gubb

We make Gubb, a small notes app for Mac and Windows. Its editor converts Markdown markers when you press Space at the start of a line. Checklists don't need the - prefix:

1. Type the task text.
2. Press Return to add the next item.
3. Press Return on an empty item to leave the checklist.
4. Click the box to tick or untick an item. Ticked items are struck through.

Gubb also has formatting shortcuts, so you don't have to type Markdown symbols for styling. They use the Command key (⌘), and each one also works with Control:

The Gubb notes help covers the editor in more detail.

Know two limits before you use Gubb for Markdown files:

• The syntax is only a typing shortcut. Gubb stores notes in its own local database, not as .md files.
• Its Markdown export currently writes the editor's internal data, not readable Markdown.

If your checklist has to end up in a Markdown file or on GitHub, write it in a text editor using the GFM syntax above. If you just want a quick list to tick off, Gubb's shortcut saves you typing the dash and brackets.

When you need more than checkboxes

Plain Markdown checklists have no due dates, priorities or reminders. In Gubb, a line containing only gubb@todo (or /todo) becomes a to-do block. The block supports due dates, priorities (None, Low, Medium, High or Urgent), notes and subtasks. Tasks are grouped into Overdue, Today, Tomorrow, Upcoming and No Date. Gubb doesn't send reminders for due dates.

The to-do list help explains the block, and our guide to making a to-do list on Mac compares other ways to do it.

In Apple Notes

Apple Notes has its own checklists instead of Markdown syntax. Press ⇧⌘L or choose Format > Checklist to start one, then click the circles to tick items. Apple Notes is free and syncs through iCloud, so if your notes already live there, that's the built-in way.

If your checklist shows as text

1. No list marker. In a .md file, [ ] Task on its own is plain text. Add - in front: - [ ] Task.
2. No space inside the brackets. [] isn't a GFM checkbox, so use [ ]. Gubb's typing shortcut accepts [], but Markdown files don't.
3. No space after the bracket. - [ ]Task renders as text. Add a space: - [ ] Task.
4. The renderer doesn't support task lists. Strict CommonMark and original Markdown show the brackets. Switch on the GFM or task-list option in your tool, or use a renderer that supports GFM.
5. Nested items are flat or turn into code. Fix the indentation: two spaces under - , three under 1. , and no tabs mixed with spaces.
6. Boxes render on GitHub but won't click. Either you're viewing a repository file, which is read-only, or you don't have permission to edit the issue or comment.

FAQ

Is it [x] or [X]?
Both work in GFM and in Gubb's typing shortcut. Lowercase [x] is more common in files you'll share.

Can I use * instead of -?
Yes. *, - and + all work as list markers. Use one marker throughout a list, because switching markers starts a new list in CommonMark-based renderers.

Is there a checklist syntax in standard Markdown?
No. Task lists are a GFM extension, so a tool needs GFM support (or a task-list option) to render them as checkboxes.

Can a Markdown checklist have due dates?
Not as syntax. You can write a date in the task text, but nothing will act on it. For dates, use a to-do app or a to-do block like Gubb's.

The Markdown cheat sheet covers headings, links, tables and code. If you're new to the format, start with what Markdown is. Gubb has a 7-day free trial for Mac.