Docutils | Overview | About | Users | Reference | Developers

Docutils TODO lists

TODO lists allow you to create a list of items with checkboxes. In extended Markdown, they are called task lists.

Checkbox variants

[x] ASCII-art checkbox.

[ ] ASCII space character and NBSP are smaller than the x.

[ ] The "figure space" has the correct width but is not easy to type.

You may define substitutions for ballot box and checked ballot box or other suitable Unicode characters:

☐ U+2610 BALLOT BOX

☑ U+2611 BALLOT BOX WITH CHECK

🗹 U+1F5F9 BALLOT BOX WITH BOLD CHECK

List Markup

Paragraphs

☑ Simple paragraphs are easy for small lists with short values

☐ but not well suited for complex TODO items.

Line Blocks

☑ Line blocks are rendered as "unstyled" lists.
🗹 They don't need additional styling.
☐ However, you cannot nest block elements.

Description Lists

A description list works out of the box in HTML5 and XeTeX.
It looks suboptimal in the rST source (definition list with class value "description").
[x]
Lists may use ASCII-art or substitutions.
[ ]
All list markup variants require special styling based on a preceding class directive.

Bullet Lists

  • ☑ bullet lists (similar to the Markdown for task lists) can be styled accordingly.

  • ☐ They don't look good in the rST source.

  • [x] Lists may use ASCII-art or substitutions.

  • [ ] The "figure space" has the correct width.

  • ☑ Another idea: use bullet lists with + and - markers.

    • Clean and simple markup in the source.
    • A new marker character starts a new list :-(
    • Requires change to the writer: Pass the "bullet" attribute to the output document (use HTML5 "data-" attriibutes?).

Field Lists

☑:Compile this example with rst2html5,
🗹:compare markup variants,
☐:select the best.
[x]:ASCII-art checkbox.
[ ]:The "figure space" has the correct width.
[ ]:CSS styling can switch to monospace fonts for the ASCII-art boxes, so an ASCII space character can be used.
x:ASCII-art checkbox - brackets added by CSS.
 :Simple rST source, easy typing.
x:checkbox border added by CSS.
 :Simple rST source, easy typing.

I recommend a field list with class argument and some CSS styling.