January 27, 2014 ☼ Markdown
As a plain-text person I generally gravitate to keeping my project materials in text files. As someone who believes HTML is the quintessential document format, I like to use Markdown to ease the transition from plain-text to sensibly structured HTML.
Naturally, one makes a lot of lists when taking meeting notes or capturing a list of tasks to be completed for a project. In Markdown single level lists are straightforward while multi-level lists, or outlines if you will, have all sorts of thorny edges depending on which Markdown parser you choose to use.
To begin a list item in Markdown one starts a line with -, +, or * followed by a whitespace character and then your list item text content.
Given Markdown’s close relationship to HTML’s text semantics it doesn’t have a “task” or “todo” item syntax. Sure HTML Forms has <input type="checkbox" /> but Markdown has never concerned itself with translating plain-text to HTML Forms markup.
Still Markdown is popular with the project documentation and note taking set and there are currently several attempts at employing a syntax for tasks. Here’s a summary of them as well how backwards compatible these extensions are via the Babelmark test suite tool.
(At time of writing the Babelmark 1 testbed’s Python Markdown implementation was failing due to a system error. I’ve removed those failures from the results.)
Update 1/28/14, 10:47 AM PST: I split out the Listacular/TaskAgent and TaskPaper/FoldingText sections as they really do have different behavior. Listacular (beta) is currently straddling two worlds though as it tries to support TaskPaper/FoldingText’s @done syntax.
GitHub introduced this syntax extension on January 9th, 2013:
- [ ] undone todo item
- [x] done todo item`- undone todo item
x done todo itemNeither of these are necessarily Markdown editors but both will accept subsets of the Markdown language for formatting. Listacular goes much farther than TaskAgent and is willing to render entire documents as Markdown and do its best to extract todo items (by looking at list items with the - marker rather than those with an + or *.)
x is not a valid to signal to a Markdown parser that you wish to have a list item so naturally these fail.- undone todo item
- todo item @doneTo be fair, neither TaskPaper or FoldingText actually claim to be “Markdown” editors. They are more “Markdown based” or inspired. Still, people confuse them enough with the Markdown editor set that I think it is worth calling this out.
@done with <span class="citation">@done</span>-- undone todo item
++ done todo item- or + symbol as a list item presumably because they are all looking for a whitespace character after one of these characters.-- item and kramdown actually barfed out a parser error.Only GitHub Flavored Markdown’s Task list and TaskPaper/FoldingText’s syntax survives mostly intact across most Markdown parsers. Sadly, almost none of the Markdown editors on the market use Github Flavored Markdown as their Markdown engine of choice. Mac OS X Markdown editor Erato is an exception but without a sufficient matching mobile client in the iOS ecosystem there’s little hope for a sane individual to hope to get by choosing this syntax. If omz:software’s Editorial for iPad ever makes it way to the iPhone a lot of us power users might be able to construct our own happy compromises. I can’t really speak to the state of Markdown todo support on Android or Windows Mobile but I’m happy to reference others’ research on this topic.