Task Lists

This Sphinx extension mimics the HTML output of the pymdownx.tasklist Markdown extension, which allows for the definition of task lists. With this extension and the mkdocs-material theme’s CSS, you can make list items prefixed with [ ] to render an unchecked checkbox or [x] to render a checked checkbox.

This extension can be optionally be used in other sphinx theme’s that support checkboxes.

This is already done in sphinx-immaterial theme:
extensions = ["sphinx_immaterial.task_lists"]
CSS not included with extension

The CSS for checkboxes is not included with this extension. Rather, the CSS is served from the sphinx-immaterial theme (which is inherited from mkdocs-material theme).

To use this extension with a theme that has no CSS support, try adding your own CSS:

:root {
  --md-task-list-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill-rule="evenodd" d="M1 12C1 5.925 5.925 1 12 1s11 4.925 11 11-4.925 11-11 11S1 18.075 1 12zm16.28-2.72a.75.75 0 0 0-1.06-1.06l-5.97 5.97-2.47-2.47a.75.75 0 0 0-1.06 1.06l3 3a.75.75 0 0 0 1.06 0l6.5-6.5z"/></svg>');
  --md-task-list-icon--checked: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill-rule="evenodd" d="M1 12C1 5.925 5.925 1 12 1s11 4.925 11 11-4.925 11-11 11S1 18.075 1 12zm16.28-2.72a.75.75 0 0 0-1.06-1.06l-5.97 5.97-2.47-2.47a.75.75 0 0 0-1.06 1.06l3 3a.75.75 0 0 0 1.06 0l6.5-6.5z"/></svg>');
}

/* style for the unchecked checkboxes */
.task-list-indicator::before {
  -webkit-mask-image: var(--md-task-list-icon);
  mask-image: var(--md-task-list-icon);
  background-color: hsla(232deg, 75%, 90%, 0.12);

  content: "";
  height: 1.25em;
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-size: contain;
  mask-size: contain;
  position: absolute;
  top: .15em;
  width: 1.25em;
}

/* style for the checked checkboxes */
.task-list-control > [type="checkbox"]:checked + .task-list-indicator::before {
  -webkit-mask-image: var(--md-task-list-icon--checked);
  mask-image: var(--md-task-list-icon--checked);
  background-color: hsl(122deg, 84%, 45%);
}

Config variables

custom_checkbox : bool = False

A global conf.py bool variable to enable custom CSS for all checkboxes shown. Default is False.

clickable_checkbox : bool = False

A global conf.py bool variable to enable user interaction with the checkboxes shown. Default is False.

Note

If this option is used, then any user changes will not be saved.

task-list Directive

.. task-list::

This directive traverses the immediate list’s items and adds a checkbox according to GitHub Flavored MarkDown.

:class: (string)

A space delimited list of qualified names that get used as the HTMl element’s class attribute.

The class option is only applied to the containing div element.

Custom icons scoped to immediate list only (not child lists)
.. task-list::
    :class: custom-task-list-style
    :custom:

    + [ ] Custom unchecked checkbox
    + [x] Custom checked checkbox

      .. task-list::
          :custom:

          * [ ] A goal for a task.
          * [x] A fulfilled goal.
  • Custom unchecked checkbox

  • Custom checked checkbox

    • A goal for a task.

    • A fulfilled goal.

/* style for the unchecked checkboxes */
.custom-task-list-style > ul > li > label .task-list-indicator::before {
  -webkit-mask-image: var(--md-admonition-icon--failure);
  mask-image: var(--md-admonition-icon--failure);
  background-color: hsl(0, 72%, 55%);
}

/* style for the checked checkboxes */
.custom-task-list-style>ul>.task-list-item>.task-list-control>[type="checkbox"]:checked+.task-list-indicator::before {
  -webkit-mask-image: var(--md-admonition-icon--success);
  mask-image: var(--md-admonition-icon--success);
  background-color: hsl(122, 84%, 45%);
}
:name: (string)

A qualified name that get used as the HTML element’s name attribute.

The name option is only applied to the containing div element. Use the ref role to reference the element by name.

:custom: (flag)

Allow custom styled checkboxes. Default is False unless custom_checkbox is enabled.

:clickable: (flag)

Allow user interaction with checkboxes. Default is False unless clickable_checkbox is enabled.

Note

If this option is used, then any user changes will not be saved.

Task List Example

The following task-list example demonstrates nested task-list. Notice that indentation is important with reStructuredText lists.

A feature spanning task-list example
.. task-list::
    :name: task_list_example
    :custom:

    1. [x] Task A
    2. [ ] Task B

       .. task-list::
           :clickable:

           * [x] Task B1
           * [x] Task B2
           * [] Task B3

           A rogue paragraph with a reference to
           the `parent task_list <task_list_example>`.

           - A list item without a checkbox.
           - [ ] Another bullet point.

    3. [ ] Task C
  1. Task A

  2. Task B

    • Task B1

    • Task B2

    • Task B3

    A rogue paragraph with a reference to the parent task_list.

    • A list item without a checkbox.

    • Another bullet point.

  3. Task C


Last update: Sep 30, 2022