This is a draft specification. It reflects how I've been handling my TODO lists for various small projects (too small to e.g. bother with a Trello board).
A TODO file looks like this:
# TODO for `todo.md` ## Write about it on www.rollc.at - [ ] 1 publish the post - [ ] 4 write more TODO items here - [ ] 5 spell check! - [x] 2 include a nice example - [ ] 5 with more sections - [x] 1 with checkboxes - [x] 2 with priorities - [x] 5 with nested lists ## Create some tools - [ ] 1 sorting - [ ] 3 report / summary - [ ] 1 digest of currently pending items - [ ] 3 stats on complete / pending - [ ] 3 stats on relative priorities - [ ] 4 recurisve operation on a file tree - [ ] 5 integrate with git for burndown tracking - [ ] 5 add-on library for common Md parsers - [ ] 1 Python - [ ] 4 Go - [ ] 5 Pandoc?
It is a single file, with plain, old Markdown, named
The file's contents consist of some free-form Markdown, which includes some checklists (possibly organised using
# section markers).
Each item on a checklist includes three things:
- A checkbox, in either checked (
[x]) or unchecked (
[ ]) state, meaning the item is either:
- [x] done
- [ ] not done
- An optional digit, in the range from 1 to 5, indicating the relative priority / importance / urgency of the item:
- 1 lowest is most important
- 5 highest is least important
- A free-form item description
Items are ticked off whenever completed.
Nested lists are allowed, to break down bigger tasks. Sub-items' importance is relative to parent's.
Whenever the list undergoes some maintenance (tick off some items, add more, adjust priorities and descriptions, etc), it should be sorted afterwards.
- Sorting must happen in simple ASCII order, so that unchecked (
[ ]) items go on the top, and more important items come before less important stuff.
- Sorting must otherwise preserve any other document structure, it is not right to just pipe the file into
sort(1)(unless the entire file is exactly one item per line).
Versioning and collaboration
Using a VCS is recommended. Git is suggested.
It is recommended that items are ticked off and lists sorted in the same unit of work (commit, pull request, revision, ...) that introduced the change.
While the format is meant to be very human-friendly, some tooling can make working with it even easier.
markdown-modewill react to pressing
enteror clicking in a checkbox by toggling it.
Sorting of non-nested lists can be easily achieved by selecting an entire list, and running
M-x sort-lineson the region.
More tools should be written. Once there is a repository, it will be linked here.