[x]it! Syntax Guide

Go Back to Main Page
Read the Specification

Status

A checkbox can have one of four statuses: open, checked, ongoing, obsolete.

[ ] Open
[x] Checked
[@] Ongoing
[~] Obsolete

Any other character for the status is invalid.

[*] Invalid
[o] Invalid
[X] Invalid (uppercase)
[ ] Invalid (non-breaking space)

It’s also invalid if the status character is missing, or if it contains extra characters.

[] Invalid
[ ] Invalid
[ x ] Invalid
[@@] Invalid

The checkbox cannot be preceded by whitespace.

[x] Invalid
[x] Invalid

Description

The checkbox can be followed by a description, which is separated by one space from the checkbox.

[ ] Do this

Additional spaces can appear, which then belong to the description copy.

[ ] Do this

The description can be absent, or all spaces.

[ ]
[ ]
[ ]

The space separator is mandatory.

[ ]Invalid
[ ]! Invalid
[ ]. Invalid
[ ]!!. Invalid
[ ]#invalid
[ ]->2022-02-16 Invalid

The description can be continued on the next line, with increased indentation. Indentation is 4 spaces.

[ ] This is a longer ...
description text
[ ] And this one ...
is even ...
longer

When the description styling is specific to the status, the styling should apply to all subsequent lines likewise.

[x] These lines ...
should all ...
look the same

There may be additional spaces after the indentation, which then belong to the description copy.

[ ] This has some ...
more spaces
[ ] And this one ...
as well

Indentation cannot be anything else than 4 spaces.

[ ] The next line is ...
invalid (no space)
[ ] The next line is ...
invalid (1 spaces)
[ ] The next line is ...
invalid (2 spaces)
[ ] The next line is ...
invalid (3 spaces)
[ ] The next line is ...
    invalid (4 non-breaking spaces)
[ ] The next line is ...
invalid (tab)

Square brackets in the description (even at the beginning of subsequent lines) are not recognised as checkboxes.

[ ] A math formula: f[x]=x
[ ] [Description text]
[ ] [ ] Description text [ ]
[ ] The next line is ...
[ ] all description text
[ ] ! Check: [ #tags ] / [ -> 2022
(I.e., other tokens still work)

Priority

If a priority is specified, it must follow after the checkbox, and must be separated by one space from surrounding elements.

[ ] ! This is important
[ ] !!! This is very important
[ ] !!!!!!!!!! This super important

The priority can be padded with dots on either side.

[ ] ..! This is important
[ ] !!. This is more important
[ ] ... This is not important

Any additional spaces to the right belong to the description copy.

[ ] ! Do something
[ ] . Do something

There cannot be additional spaces to the left.

[ ] ! Do something
[ ] . Do something

The dots cannot appear on both sides, or in between.

[ ] .!. Invalid
[ ] !.! Invalid

If the space between priority and description is missing, the exclamation mark is treated as part of the description.

[ ] !This has regular priority
[ ] .The dot is not priority

Any exclamation marks after the priority don’t belong to the priority anymore, but are treated as description.

[ ] ! !!! This is important!
[ ] !! ! ! This ! is also important
[ ] !. ... This . is also important
[ ] . ! This is not important
[ ] The next line is also ...
!!! not important

Due Date

The description can contain a due date.

[ ] -> 2022-01-31
[ ] Do this -> 2022-01-31
[ ] -> 2022-01-31 (something)
[ ] Do something until ...
-> 2022-01-31

Due dates can be expressed through various patterns to reference a day, week, month, quarter or year.

[ ] -> 2022-01-31
[ ] -> 2022-01
[ ] -> 2022
[ ] -> 2022-W01
[ ] -> 2022-Q1

Instead of a hyphen, the delimiter can also be a slash.

[ ] -> 2022/01/31
[ ] -> 2022/W01

The delimiter style cannot be mixed, though.

[ ] -> 2022-01/31

Redundant due dates are not recognised.

[ ] -> 2022-01-31 -> 2022-01-31

Due dates can be surrounded by a space or punctuation (apart from a hyphen or slash).

[ ] Do this soon -> 2022-01-31!!!
[ ] Do this (-> 2022-01-31)

Any other surrounding character makes the due date unrecognised.

[ ] ---> 2022-01-31
[ ] Due-> 2022-01-31
[ ] -> 2022-01-31very urgent
[ ] -> 2022-01-31T10:00
[ ] -> 2022-01-31-0
[ ] -> 2022/01/31/0

The prefix must be exactly: a hyphen, a greater-than sign, and a space. Otherwise, the due date is not recognised.

[ ] ->2022-01-31
[ ] → 2022-01-31
[ ] -> 2022-01-31
[ ] >2022-01-31
[ ] Do until ->
2022-01-31

Tags

Description can contain tags. A tag starts with a hashtag, followed by letters (as of the Unicode letter category), digits, hyphens, or underscores.

[ ] #tag
[ ] #T-A-G
[ ] #--tag--
[ ] #__tag__
[ ] #t_a_g
[ ] #123
[ ] #___
[ ] #---
[ ] #1t2a3g
[ ] #täg
[ ] #今日は
[ ] #გამარჯობა

There can be multiple tags per description.

[ ] This #text contains #tags
[ ] #Actually, it #has a #LOT.
Even on the #next-line!

The tag is terminated by the first character that is not allowed in tags.

[ ] This is a #tag.
[ ] Tags: #tag1/#tag2
[ ] #t-a-g!
[ ] #--tag--?
[ ] #--tag--:text
[ ] (#tag)
[ ] #tag🥳

If there is no tag name, it’s not recognised.

[ ] Not a tag: #
[ ] Not a tag: #=value
[ ] Not a tag: #="value"

The tag can have a value. The value is separated by an equals sign, and it can contain the same characters than the tag name.

[ ] #tag=value
[ ] #t-a-g=v-a-l-u-e
[ ] #国=日本

The value can be empty or absent.

[ ] #tag=
[ ] #tag=""
[ ] #tag=''

For the tag value to contain other characters, the value can be quoted. In this case, the value is terminated by the closing quote.

[ ] #tag="v a l u e"
[ ] #tag='v!a.l?u+e'
[ ] #tag='foo'bar
[ ] #tag='foo'-bar
[ ] #tag='foo'!!
[ ] (#tag="bar")

Backslashes don’t have special meaning, i.e. escaping a quotation is not supported.

[ ] #tag='It\'s great'

If the closing quote is missing (or doesn’t match), the value is disregarded altogether. That implies that a tag value cannot span multiple lines.

[ ] #tag="v a l u e
[ ] #tag="v a l u e'
[ ] #tag="hello
World!"

Groups

When consecutive items are surrounded by blank lines, they are considered to be a group.

[ ] Item 1 of group
[ ] Item 2 of group

[ ] Item of another group

“Blank line” means either the line is empty, or it only consists of whitespace.

[ ] Item

[ ] Item

[ ] Item

An item cannot contain a blank line, even if the blank line is “indented” (i.e., has 4 spaces).

[ ] Descrip-

tion

A group can be preceded by a headline.

Todos
[ ] Item 1
[ ] Item 2

If a headline is not followed by items, it refers to an empty group.

Empty Group

The headline can neither start with whitespace, nor with an opening square bracket.

Todos
[ ] Do this

Todos
[ ] Do this

[Todos]
[ ] Do this

A headline must be separated by a blank line from a preceding item.

[ ] Do this
Todos
[ ] Do this

Encoding

The text of titles and descriptions (including tags) supports UTF-8 encoded text.

今日は
[ ] 小包を受け取る
[x] 夕食を作る

Ελληνικά
[ ] 💼 δούλεψε #σκληρά
[ ] απολαύστε τον #ήλιο ☀️