To-do lists are simple and universal. As such, there is a need for a simple and universal file format for them. Just like Markdown files, Todo files should be readable and editable as plain text, so as not to lock them to a single platform, application, or computer. Besides being human-friendly, Todo files should also be software-friendly, and there should be tools available to parse them, convert them, and integrate them into IDEs and project management solutions.

Todo files consist in text files with the .todo or .todo.md extension. The syntax, described in details below, is basically an extension to how people already manually write task lists in Markdown.

They allow to write down:

• Tasks lists, possibly nested
• Tasks with a completion status
• Tasks with custom tags
• Tasks with custom attribute+content

Example in ./.todo.md, which is the Todo file for the current project, or below:

- [x] Read the sushi recipe
- [ ] `in-progress` Buy ingredients
  - [x] Sea weed
        comment: It should be thick, not flimsy!
  - [x] Rice
  - [ ] Salmon
- [ ] Prepare the sushis
      blocked-by: task #1

Writing and reading a Todo file should be pretty easy with any editor. Simply conform to the syntax specs below.

There is an ongoing effort to build the software-level tooling that would allow Todo files to be easily integrated with existing or future project management tools, namely:

• in-discussion todo-json converter
• in-discussion todo-csv converter
• in-discussion GUI
• in-discussion linter

Todo files are valid Markdown files. All Markdown rules for lists, sub-lists, comments, code and so on can be applied here.

A Todo file consists in a list of tasks. Tasks consist of a main line followed by optional attribute lines. Example:

- [ ] Task 1
- [ ] Task 2
      some-attribute: Some value
      another-attribute: Another value
- [ ] Task 3

The main line starts by an indentation (a multiple of a tab or any number of spaces, but be consistent across the whole file, like in Python) that defines parent-children tasks relationships; followed by a space-joined succession of:

• A list character: - (recommended), +, or *
• A checkbox: [ ] (to do) or [x] (done)
• (optional) Tags: enclosed in backticks, written in kebab case
• A task title: must not start with a backtick so as not to be parsed as a tag

Example:

- [ ] `to-do` Foo
- [ ] `in-progress` `urgent` Bar
  + [x] Baz

Attribute lines are a concatenation of:

• Indentation: any number of space or tab, but it is recommended to use it to align all text content of a task
• Attribute name, in kebab-case
• Separator (: )
• Attribute content, can contain any string but must fit into the remaining line

Example:

- [ ] Foo
      bar: Lorem Ipsum
      qux-quux: dolor-sit-amet