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.