A task list is a list that contains task list items. Each task list item is either complete or incomplete. Use task lists for to-do lists, sequences of steps, or any other list whose items can be done or not done.

Task lists originate in GitHub Flavored Markdown. This document describes Comrak’s task lists, which can differ from GitHub’s. GitLab uses Comrak’s task lists, so this document is also the canonical spec for GitLab Flavored Markdown task lists.

To enable task lists, pass -e tasklist (or --gfm) on the command line, or set extension.tasklist in the options struct.

Here’s a typical task list:

Example 1
$ comrak -e tasklist
- [ ] Write the docs
- [x] Build the runner

Syntax

A task list item symbol is a space, x, or X.

A task list item marker is a left bracket ([), followed by a task list item symbol, followed by a right bracket (]).

A task list item is a list item whose first block is a paragraph that begins with a task list item marker. The marker must be followed by a space, a tab, a soft line break, a hard line break, or the end of the paragraph.

Comrak determines the document’s block structure and inline structure before it recognises task list item markers. The marker and the whitespace after it must be literal characters, and must not form part of any other inline construct.

A task list item is incomplete if the symbol in its marker is a space, and complete otherwise:

Example 2
$ comrak -e tasklist
- [ ] foo
- [x] bar
- [X] baz

No other symbol is permitted unless relaxed task list character is enabled. The following are not task list items:

Example 3
$ comrak -e tasklist
- [y] a
- [] b
- [  ] c
- [xx] d
- [ x] e
- [→] f

The marker may be followed by a space or a tab:

Example 4
$ comrak -e tasklist
- [x] foo
- [x]→bar

The marker must not be followed directly by other text:

Example 5
$ comrak -e tasklist
- [x]foo

The same applies to any other inline content:

Example 6
$ comrak -e tasklist
- [x]*foo*

The marker may be followed by a soft line break or a hard line break:

Example 7
$ comrak -e tasklist
- [x]
  foo
Example 8
$ comrak -e tasklist
- [x]\
  foo

The marker may make up the whole paragraph:

Example 9
$ comrak -e tasklist
- [x]

The marker must begin the first block of a list item, and that block must be a paragraph. None of the following are task list items:

Example 10
$ comrak -e tasklist
[x] foo
Example 11
$ comrak -e tasklist
- foo [x] bar
Example 12
$ comrak -e tasklist
- *[x]* foo
Example 13
$ comrak -e tasklist
- foo

  [x] bar
Example 14
$ comrak -e tasklist
- > [x] foo
Example 15
$ comrak -e tasklist
- # [x] foo
Example 16
$ comrak -e tasklist
-     [x] foo

Block structure comes first. Here, the marker begins a setext heading rather than a paragraph, so the item is not a task list item:

Example 17
$ comrak -e tasklist
- [x] foo
  ---

The first block may begin on the line after the list marker:

Example 18
$ comrak -e tasklist
-
  [x] foo

Inline structure also comes first. A backslash escape or an entity reference cannot form part of a marker:

Example 19
$ comrak -e tasklist
- \[x] foo
Example 20
$ comrak -e tasklist
- [x] foo

Links and link reference definitions take precedence over the marker:

Example 21
$ comrak -e tasklist
- [x]/url foo
Example 22
$ comrak -e tasklist
- [x] foo

[x]: /url
Example 23
$ comrak -e tasklist
- [x]: /url

Only the marker at the beginning of the paragraph is recognised; anything after it is content:

Example 24
$ comrak -e tasklist
- [ ] [x] foo

Lists of tasks

A list containing at least one task list item is a task list.

Task list items may appear in ordered lists:

Example 25
$ comrak -e tasklist
1. [ ] Bird
2. [ ] McHale
3. [x] Parish

One list may mix task list items and other list items:

Example 26
$ comrak -e tasklist
- [ ] bullet point one
- bullet point two and some extra text
- [x] bullet point three

Task lists may be nested:

Example 27
$ comrak -e tasklist
- [x] item
  - [ ] item2
  - [x] item3
- [ ] item4

A task list item may consist of the marker alone:

Example 28
$ comrak -e tasklist
- [ ]
- [x]

The marker may also be followed only by other blocks:

Example 29
$ comrak -e tasklist
- [x]
  - [ ] foo

When a task list is loose, the checkbox precedes the item’s first paragraph rather than appearing inside it:

Example 30
$ comrak -e tasklist
- [x] foo

- [ ] bar

The same applies when an item with several blocks makes the list loose:

Example 31
$ comrak -e tasklist
- [x] foo

  bar

A lazy continuation line continues the paragraph as usual:

Example 32
$ comrak -e tasklist
- [x] foo
bar

Task lists may appear in any container, such as a block quote:

Example 33
$ comrak -e tasklist
> - [x] foo

Output

HTML output replaces the marker with a disabled checkbox <input> element followed by a single space. The element has a checked attribute if the item is complete:

Example 34
$ comrak -e tasklist
- [ ] List item 1
- [ ] This list item is **bold**
- [x] There is some `code` here

The page’s CSS determines whether the rendered page shows bullets or numbers beside the checkboxes.

The output omits the space or tab after the marker, but keeps any further whitespace as content:

Example 35
$ comrak -e tasklist
- [x]  foo

CommonMark output writes the marker back with its symbol, followed by a space.

In XML output, a task list item is a taskitem element. Its completed attribute is true if the item is complete, and false otherwise. A task list’s list element has tasklist="true".

In the AST, a task list item is a NodeValue::TaskItem. Its NodeTaskItem holds the symbol (None for a space) and the symbol’s source position. A task list’s NodeList has is_task_list set.

Options

Relaxed task list character

With --relaxed-tasklist-character (parse.relaxed_tasklist_matching), a task list item symbol may be any single character other than ] or a line ending.

Without the option, this is not a task list item:

Example 36
$ comrak -e tasklist
* [!] Red

With the option, it is:

Example 37
$ comrak -e tasklist --relaxed-tasklist-character
* [!] Red

Only a space makes the item incomplete:

Example 38
$ comrak -e tasklist --relaxed-tasklist-character
- [~] foo
- [-] bar
- [ ] baz

The symbol must still be exactly one character:

Example 39
$ comrak -e tasklist --relaxed-tasklist-character
- [ab] foo
- [] bar

Inline structure still comes first. In the first item, \] is a backslash escape. In the second, the backtick begins a code span:

Example 40
$ comrak -e tasklist --relaxed-tasklist-character
- [\] foo
- [`] bar `baz`

Task list classes

With --tasklist-classes (render.tasklist_classes), HTML output adds these classes for styling:

Other lists and list items get no classes:

Example 41
$ comrak -e tasklist --tasklist-classes
- [x] foo
- bar
  1. [ ] baz

* qux

Task lists in tables

With --tasklist-in-table (parse.tasklist_in_table), a table cell whose entire content is a task list item marker becomes a checkbox.

Without the option, such cells stay as text:

Example 42
$ comrak -e table -e tasklist
|     | name |
| --- | ---- |
| [ ] | Rell |
| [x] | Kai  |

With the option, they become checkboxes:

Example 43
$ comrak -e table -e tasklist --tasklist-in-table
|     | name |
| --- | ---- |
| [ ] | Rell |
| [x] | Kai  |

This applies to header cells too:

Example 44
$ comrak -e table -e tasklist --tasklist-in-table
| [x] |
| --- |
| foo |

The marker must be the cell’s only content. None of these cells contain a checkbox:

Example 45
$ comrak -e table -e tasklist --tasklist-in-table
| a       | b       | c     |
| ------- | ------- | ----- |
| [x] foo | foo [x] | *[x]* |

Relaxed task list characters are recognised in cells too:

Example 46
$ comrak -e table -e tasklist --tasklist-in-table --relaxed-tasklist-character
|         | name |
| ------- | ---- |
| [~]     | Rell |
| [x]     | Kai  |
| [x] No. | Ez   |

With task list classes, only the checkbox gets a class:

Example 47
$ comrak -e table -e tasklist --tasklist-in-table --tasklist-classes
|     | name |
| --- | ---- |
| [ ] | Rell |
| [x] | Kai  |

Interactions

--gfm enables task lists, along with the other GitHub Flavored Markdown extensions:

Example 48
$ comrak --gfm
- [x] foo

With autolinks, the marker must still be followed by whitespace:

Example 49
$ comrak -e tasklist -e autolink
- [x] www.example.com
- [x]www.example.com

With description lists, details are not list items, so they cannot be task list items:

Example 50
$ comrak -e tasklist -e description-lists
Term

: [x] foo

With --smart, inline parsing transforms some punctuation. Inline parsing comes before marker recognition, so a transformed character is not literal and cannot be a task list item symbol:

Example 51
$ comrak -e tasklist --relaxed-tasklist-character --smart
- ["] foo

Differences from cmark-gfm

cmark-gfm, the reference implementation of GitHub Flavored Markdown, recognises task list items differently. It matches the marker against the source line on which a list item’s first block opens, before it parses that block’s content. The line must begin with an optional indent, a list marker, whitespace, and a task list item marker, followed by a space or tab. To decide whether the item is complete, cmark-gfm searches the whole line for [x] or [X].

Comrak recognises the marker after it determines block and inline structure, as described in Syntax. cmark-gfm has no equivalent of the options described above. The two implementations agree on every other example above, except that cmark-gfm:

Regressions

The following examples guard against regressions.

A multi-byte symbol with --relaxed-tasklist-character (#689):

Example 52
$ comrak -e tasklist --relaxed-tasklist-character
- [あ] xy
  - [い] zw

An entity reference cannot supply the whitespace after a marker (found by fuzzing):

Example 53
$ comrak -e tasklist
-→[ ]&NewLine;

Inline content immediately following a marker is preserved (#559):

Example 54
$ comrak -e tasklist
- [ ] `Blue`

Source positions account for the removed marker (#542):

Example 55
$ comrak -e tasklist --sourcepos
- [x] foo
  - [ ] bar