gfm.tasklist – Task list support

The gfm.tasklist module provides GitHub-like support for task lists. Those are normal lists with a checkbox-like syntax at the beginning of items that will be converted to actual checkbox inputs. Nested lists are supported.

Example syntax:

- [x] milk
- [ ] eggs
- [x] chocolate
- [ ] if possible:
    1. [ ] solve world peace
    2. [ ] solve world hunger

Note

GitHub has support for updating the Markdown source text by toggling the checkbox (by clicking on it). This is not supported by this extension, as it requires server-side processing that is out of scope of a Markdown parser.

Available configuration options

Name Type Default Description
unordered bool True Set to False to disable parsing of unordered lists.
ordered bool True Set to False to disable parsing of ordered lists.
max_depth integer ∞ Set to a positive integer to stop parsing nested task lists that are deeper than this limit.
list_attrs dict, callable {} Attributes to be added to the <ul> or <ol> element containing the items.
item_attrs dict, callable {} Attributes to be added to the <li> element containing the checkbox. See Item attributes.
checkbox_attrs dict, callable {} Attributes to be added to the checkbox element. See Checkbox attributes.

List attributes

If option list_attrs is a dict, the key-value pairs will be applied to the <ul> (resp. <ol>) unordered (resp. ordered) list element, that is the parent element of the <li> elements.

Warning

These attributes are applied to all nesting levels of lists, that is, to both the root lists and their potential sub-lists, recursively.

You can control this behavior by using a callable instead (see below).

If option list_attrs is a callable, it should be a function that respects the following prototype:

def function(list, depth: int) -> dict:

where:

  • list is the <ul> or <ol> element;
  • depth is the depth of this list relative to its root list (root lists have a depth of 1).

The returned dict items will be applied as HTML attributes to the list element.

Note

Thanks to this feature, you could apply attributes to root lists only. Take this code sample:

import markdown
from gfm import TaskListExtension

def list_attr_cb(list, depth):
    if depth == 1:
        return {'class': 'tasklist'}
    return {}

tl_ext = TaskListExtension(list_attrs=list_attr_cb)

print(markdown.markdown("""
- [x] some thing
- [ ] some other
    - [ ] sub thing
    - [ ] sub other
""", extensions=[tl_ext]))

In this example, only the root list will have the tasklist class attribute, not the one containing “sub” items.

Item attributes

If option item_attrs is a dict, the key-value pairs will be applied to the <li> element as its HTML attributes.

Example:

item_attrs={'class': 'list-item'}

will result in:

<li class="list-item">...</li>

If option item_attrs is a callable, it should be a function that respects the following prototype:

def function(parent, element, checkbox) -> dict:

where:

  • parent is the <li> parent element;
  • element is the <li> element;
  • checkbox is the generated <input type="checkbox"> element.

The returned dict items will be applied as HTML attributes to the <li> element containing the checkbox.

Checkbox attributes

If option checkbox_attrs is a dict, the key-value pairs will be applied to the <input type="checkbox"> element as its HTML attributes.

Example:

checkbox_attrs={'class': 'list-cb'}

will result in:

<li><input type="checkbox" class="list-cb"> ...</li>

If option checkbox_attrs is a callable, it should be a function that respects the following prototype:

def function(parent, element) -> dict:

where:

  • parent is the <li> parent element;
  • element is the <li> element.

The returned dict items will be applied as HTML attributes to the checkbox element.

Typical usage

import markdown
from gfm import TaskListExtension

print(markdown.markdown("""
- [x] milk
- [ ] eggs
- [x] chocolate
- not a checkbox
""", extensions=[TaskListExtension()]))

<ul>
<li><input checked="checked" disabled="disabled" type="checkbox" /> milk</li>
<li><input disabled="disabled" type="checkbox" /> eggs</li>
<li><input checked="checked" disabled="disabled" type="checkbox" /> chocolate</li>
<li>not a checkbox</li>
</ul>
class gfm.tasklist.TaskListExtension(*args, **kwargs)[source]

Bases: markdown.extensions.Extension

An extension that supports GitHub task lists. Both ordered and unordered lists are supported and can be separately enabled. Nested lists are supported.

Example:

- [x] milk
- [ ] eggs
- [x] chocolate
- [ ] if possible:
    1. [ ] solve world peace
    2. [ ] solve world hunger
getConfig(key, default='')

Return a setting for the given key or an empty string.

getConfigInfo()

Return all config descriptions as a list of tuples.

getConfigs()

Return all configs settings as a dict.

setConfig(key, value)

Set a config setting for key with the given value.

setConfigs(items)

Set multiple config settings given a dict or list of tuples.