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.

extensions = ["sphinx_immaterial.task_lists"]

: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.

rST code CSS Hint

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 > li > .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.

.. 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