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:
$ comrak -e tasklist -t commonmark -t xml
- -
- Write the docs
- Build the runner
Write the docs
Build the runner
- -
Write the docs
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:
$ comrak -e tasklist -t commonmark -t xml
- --
- foo
- bar
- baz
foo
bar
baz
- --
foo
bar
baz
No other symbol is permitted unless relaxed task list character is enabled. The following are not task list items:
$ comrak -e tasklist -t commonmark -t xml
- -----
- [y] a
- [] b
- [ ] c
- [xx] d
- [ x] e
- [ ] f
[y] a
[] b
[ ] c
[xx] d
[ x] e
[→] f
- -----
[y] a
[] b
[ ] c
[xx] d
[ x] e
[→] f
The marker may be followed by a space or a tab:
$ comrak -e tasklist -t commonmark -t xml
- -
- foo
- bar
foo
bar
- -
foo
bar
The marker must not be followed directly by other text:
$ comrak -e tasklist -t commonmark -t xml
-
- [x]foo
[x]foo
-
[x]foo
The same applies to any other inline content:
$ comrak -e tasklist -t commonmark -t xml
-
- [x]foo
[x]foo
-
[x]
foo
The marker may be followed by a soft line break or a hard line break:
$ comrak -e tasklist -t commonmark -t xml
-
- foo
foo
-
foo
$ comrak -e tasklist -t commonmark -t xml
-
-
foo
foo
-
foo
The marker may make up the whole paragraph:
$ comrak -e tasklist -t commonmark -t xml
-
-
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:
$ comrak -e tasklist -t commonmark -t xml
[x] foo
[x] foo
[x] foo
$ comrak -e tasklist -t commonmark -t xml
-
- foo [x] bar
foo [x] bar
-
foo [x] bar
$ comrak -e tasklist -t commonmark -t xml
-
- [x] foo
[x] foo
-
[x]
foo
$ comrak -e tasklist -t commonmark -t xml
-
-
foo
[x] bar
foo
[x] bar
-
foo
[x] bar
$ comrak -e tasklist -t commonmark -t xml
-
-
[x] foo
[x] foo
-
[x] foo
$ comrak -e tasklist -t commonmark -t xml
-
-
[x] foo
[x] foo
-
[x] foo
$ comrak -e tasklist -t commonmark -t xml
-
-
[x] foo
[x] foo
-
[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:
$ comrak -e tasklist -t commonmark -t xml
-
-
[x] foo
[x] foo
-
[x] foo
The first block may begin on the line after the list marker:
$ comrak -e tasklist -t commonmark -t xml
-
- foo
foo
-
foo
Inline structure also comes first. A backslash escape or an entity reference cannot form part of a marker:
$ comrak -e tasklist -t commonmark -t xml
-
- [x] foo
[x] foo
-
[x] foo
$ comrak -e tasklist -t commonmark -t xml
-
- [x] foo
[x] foo
-
[x] foo
Links and link reference definitions take precedence over the marker:
$ comrak -e tasklist -t commonmark -t xml
-
$ comrak -e tasklist -t commonmark -t xml
-
$ comrak -e tasklist -t commonmark -t xml
-
-
Only the marker at the beginning of the paragraph is recognised; anything after it is content:
$ comrak -e tasklist -t commonmark -t xml
-
- [x] foo
[x] foo
-
[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:
$ comrak -e tasklist -t commonmark -t xml
1. 2.3.
- Bird
- McHale
- Parish
Bird
McHale
Parish
1. 2.3.
Bird
McHale
Parish
One list may mix task list items and other list items:
$ comrak -e tasklist -t commonmark -t xml
- --
- bullet point one
- bullet point two and some extra text
- bullet point three
bullet point one
bullet point two and some extra text
bullet point three
- --
bullet point one
bullet point two and some extra text
bullet point three
Task lists may be nested:
$ comrak -e tasklist -t commonmark -t xml
- - --
- item
- item2
- item3
- item4
item
item2
item3
item4
- - --
item
item2
item3
item4
A task list item may consist of the marker alone:
$ comrak -e tasklist -t commonmark -t xml
- -
- -
The marker may also be followed only by other blocks:
$ comrak -e tasklist -t commonmark -t xml
- -
-
- foo
foo
-
foo
When a task list is loose, the checkbox precedes the item’s first paragraph rather than appearing inside it:
$ comrak -e tasklist -t commonmark -t xml
-
-
-
foo
-
bar
foo
bar
-
-
foo
bar
The same applies when an item with several blocks makes the list loose:
$ comrak -e tasklist -t commonmark -t xml
-
-
foo
bar
foo
bar
-
foo
bar
A lazy continuation line continues the paragraph as usual:
$ comrak -e tasklist -t commonmark -t xml
-
- foo bar
foo
bar
-
foo
bar
Task lists may appear in any container, such as a block quote:
$ comrak -e tasklist -t commonmark -t xml
- foo
foo
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:
$ comrak -e tasklist -t commonmark -t xml
- --
- List item 1
- This list item is bold
- There is some
codehere
List item 1
This list item is bold
There is some code here
- --
List item 1
This list item is
bold
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:
$ comrak -e tasklist -t commonmark -t xml
-
- foo
foo
-
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:
$ comrak -e tasklist -t commonmark -t xml
*
- [!] Red
[!] Red
-
[!] Red
With the option, it is:
$ comrak -e tasklist --relaxed-tasklist-character -t commonmark -t xml
*
- Red
Red
-
Red
Only a space makes the item incomplete:
$ comrak -e tasklist --relaxed-tasklist-character -t commonmark -t xml
- --
- foo
- bar
- baz
foo
bar
baz
- --
foo
bar
baz
The symbol must still be exactly one character:
$ comrak -e tasklist --relaxed-tasklist-character -t commonmark -t xml
- -
- [ab] foo
- [] bar
[ab] foo
[] bar
- -
[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:
$ comrak -e tasklist --relaxed-tasklist-character -t commonmark -t xml
- -
- [] foo
- [
] barbaz`
[] foo
[] bar baz`
- -
[] foo
[
] bar
baz`
Task list classes
With --tasklist-classes (render.tasklist_classes), HTML output adds these classes for styling:
contains-task-liston each task listtask-list-itemon each task list itemtask-list-item-checkboxon each checkbox
Other lists and list items get no classes:
$ comrak -e tasklist --tasklist-classes -t commonmark -t xml
- - 1.
*
- foo
- bar
- baz
- qux
foo
bar
baz
qux
- - 1.
-
foo
bar
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:
$ comrak -e table -e tasklist -t commonmark -t xml
| name | |
|---|---|
| [ ] | Rell |
| [x] | Kai |
name
[ ]
Rell
[x]
Kai
name
[ ]
Rell
[x]
Kai
With the option, they become checkboxes:
$ comrak -e table -e tasklist --tasklist-in-table -t commonmark -t xml
| name | |
|---|---|
| Rell | |
| Kai |
name
Rell
Kai
name
Rell
Kai
This applies to header cells too:
$ comrak -e table -e tasklist --tasklist-in-table -t commonmark -t xml
| foo |
foo
foo
The marker must be the cell’s only content. None of these cells contain a checkbox:
$ comrak -e table -e tasklist --tasklist-in-table -t commonmark -t xml
| a | b | c |
|---|---|---|
| [x] foo | foo [x] | [x] |
a
b
c
[x] foo
foo [x]
[x]
a
b
c
[x] foo
foo [x]
[x]
Relaxed task list characters are recognised in cells too:
$ comrak -e table -e tasklist --tasklist-in-table --relaxed-tasklist-character -t commonmark -t xml
| name | |
|---|---|
| Rell | |
| Kai | |
| [x] No. | Ez |
name
Rell
Kai
[x] No.
Ez
name
Rell
Kai
[x] No.
Ez
With task list classes, only the checkbox gets a class:
$ comrak -e table -e tasklist --tasklist-in-table --tasklist-classes -t commonmark -t xml
| name | |
|---|---|
| Rell | |
| Kai |
name
Rell
Kai
name
Rell
Kai
Interactions
--gfm enables task lists, along with the other GitHub Flavored Markdown extensions:
$ comrak --gfm -t commonmark -t xml
-
- foo
foo
-
foo
With autolinks, the marker must still be followed by whitespace:
$ comrak -e tasklist -e autolink -t commonmark -t xml
- -
- www.example.com
- [x]www.example.com
www.example.com
[x]www.example.com
- -
www.example.com
[x]www.example.com
With description lists, details are not list items, so they cannot be task list items:
$ comrak -e tasklist -e description-lists -t commonmark -t xml
- Term
-
[x] foo
Term
[x] foo
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:
$ comrak -e tasklist --relaxed-tasklist-character --smart -t commonmark -t xml
-
- [”] foo
[”] foo
-
[”] 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:
- requires a space or tab after the marker, on the same line, and doesn’t recognise a marker followed by a line break (example 7, example 8) or a marker that makes up the whole paragraph (example 9, example 28, example 29);
- requires the marker to be on the same line as the list marker, and that line to begin with the list marker, which rules out a first block that begins on the next line (example 18) and a task list inside a block quote (example 33);
- recognises the marker before inline parsing, so the marker takes precedence over a shortcut reference link with a matching definition (example 22);
- recognises the marker before it sees a setext heading underline, which yields a task list item that contains a heading (example 17);
- removes all whitespace after the marker (example 35); and,
- marks an item complete if
[x]or[X]appears anywhere on its line, so- [ ] see [x]is complete (example 24).
Regressions
The following examples guard against regressions.
A multi-byte symbol with --relaxed-tasklist-character (#689):
$ comrak -e tasklist --relaxed-tasklist-character -t commonmark -t xml
- -
- xy
- zw
xy
zw
- -
xy
zw
An entity reference cannot supply the whitespace after a marker (found by fuzzing):
$ comrak -e tasklist -t commonmark -t xml
- [ ]
[ ]
-
[ ]
Inline content immediately following a marker is preserved (#559):
$ comrak -e tasklist -t commonmark -t xml
-
-
Blue
Blue
-
Blue
Source positions account for the removed marker (#542):
$ comrak -e tasklist --sourcepos -t commonmark -t xml
- -
- foo
- bar
foo
bar
- -
foo
bar