✨ NEW: Add tasklist extension (#370)

Task lists utilise the [markdown-it-py tasklists plugin](markdown_it:md/plugins), and are applied to Markdown list items starting with `[ ]` or `[x]`. ```markdown - [ ] An item that needs doing - [x] An item that is complete ```
executablebooks · May 4, 2021 · a450808 · a450808
1 parent ac7e1f7
commit a450808
Show file tree

Hide file tree

Showing 9 changed files with 67 additions and 3 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -71,6 +71,7 @@
     "replacements",
     "linkify",
     "substitution",
+    "tasklist",
 ]
 myst_url_schemes = ("http", "https", "mailto")
 myst_heading_anchors = 2

diff --git a/docs/using/intro.md b/docs/using/intro.md
@@ -272,6 +272,7 @@ List of extensions:
 - "replacements": automatically convert some common typographic texts
 - "smartquotes": automatically convert standard quotations to their opening/closing variants
 - "substitution": substitute keys, see the [substitutions syntax](syntax/substitutions) for details
+- "tasklist": add check-boxes to the start of list items, see the [tasklist syntax](syntax/tasklists) for details
 
 Math specific, when `"dollarmath"` activated, see the [Math syntax](syntax/math) for more details:
 

diff --git a/docs/using/syntax-optional.md b/docs/using/syntax-optional.md
@@ -35,7 +35,8 @@ myst_enable_extensions = [
     "linkify",
     "replacements",
     "smartquotes",
-    "substitution"
+    "substitution",
+    "tasklist",
 ]
 ```
 
@@ -335,7 +336,7 @@ The paths to other files should be relative to the current file, for example
 
 By adding `"deflist"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
 you will be able to utilise definition lists.
-Definition lists utlise the [markdown-it-py deflist plugin](markdown_it:md/plugins), which itself is based on the [Pandoc definition list specification](http://johnmacfarlane.net/pandoc/README.html#definition-lists).
+Definition lists utilise the [markdown-it-py deflist plugin](markdown_it:md/plugins), which itself is based on the [Pandoc definition list specification](http://johnmacfarlane.net/pandoc/README.html#definition-lists).
 
 This syntax can be useful, for example, as an alternative to nested bullet-lists:
 
@@ -408,6 +409,22 @@ Term 3
   <img src="img/fun-fish.png" alt="fishy" width="200px">
 ```
 
+(syntax/tasklists)=
+## Task Lists
+
+By adding `"tasklist"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+you will be able to utilise task lists.
+Task lists utilise the [markdown-it-py tasklists plugin](markdown_it:md/plugins),
+and are applied to markdown list items starting with `[ ]` or `[x]`:
+
+```markdown
+- [ ] An item that needs doing
+- [x] An item that is complete
+```
+
+- [ ] An item that needs doing
+- [x] An item that is complete
+
 (syntax/images)=
 
 ## Images

diff --git a/myst_parser/docutils_renderer.py b/myst_parser/docutils_renderer.py
@@ -360,6 +360,9 @@ def render_text(self, token: SyntaxTreeNode) -> None:
 
     def render_bullet_list(self, token: SyntaxTreeNode) -> None:
         list_node = nodes.bullet_list()
+        if token.attrs.get("class"):
+            # this is used e.g. by tasklist
+            list_node["classes"] = str(token.attrs["class"]).split()
         self.add_line_and_source_path(list_node, token)
         with self.current_node_context(list_node, append=True):
             self.render_children(token)
@@ -372,6 +375,9 @@ def render_ordered_list(self, token: SyntaxTreeNode) -> None:
 
     def render_list_item(self, token: SyntaxTreeNode) -> None:
         item_node = nodes.list_item()
+        if token.attrs.get("class"):
+            # this is used e.g. by tasklist
+            item_node["classes"] = str(token.attrs["class"]).split()
         self.add_line_and_source_path(item_node, token)
         with self.current_node_context(item_node, append=True):
             self.render_children(token)

diff --git a/myst_parser/main.py b/myst_parser/main.py
@@ -14,6 +14,7 @@
 from mdit_py_plugins.myst_blocks import myst_block_plugin
 from mdit_py_plugins.myst_role import myst_role_plugin
 from mdit_py_plugins.substitution import substitution_plugin
+from mdit_py_plugins.tasklists import tasklists_plugin
 from mdit_py_plugins.wordcount import wordcount_plugin
 
 from . import __version__  # noqa: F401
@@ -55,6 +56,7 @@ def check_extensions(self, attribute, value):
                 "replacements",
                 "linkify",
                 "substitution",
+                "tasklist",
             ]
         )
         if diff:
@@ -171,6 +173,8 @@ def default_parser(config: MdParserConfig) -> MarkdownIt:
         md.use(amsmath_plugin)
     if "deflist" in config.enable_extensions:
         md.use(deflist_plugin)
+    if "tasklist" in config.enable_extensions:
+        md.use(tasklists_plugin)
     if "substitution" in config.enable_extensions:
         md.use(substitution_plugin, *config.sub_delimiters)
     if config.heading_anchors is not None:

diff --git a/tests/test_sphinx/sourcedirs/extended_syntaxes/conf.py b/tests/test_sphinx/sourcedirs/extended_syntaxes/conf.py
@@ -5,7 +5,14 @@
 myst_dmath_allow_space = False
 myst_dmath_double_inline = True
 mathjax_config = {}
-myst_enable_extensions = ["dollarmath", "amsmath", "deflist", "colon_fence", "linkify"]
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "deflist",
+    "colon_fence",
+    "linkify",
+    "tasklist",
+]
 myst_html_meta = {
     "description lang=en": "meta description",
     "property=og:locale": "en_US",

diff --git a/tests/test_sphinx/sourcedirs/extended_syntaxes/index.md b/tests/test_sphinx/sourcedirs/extended_syntaxes/index.md
@@ -56,3 +56,6 @@ This is a caption in **Markdown**
 :::
 
 linkify URL: www.example.com
+
+- [ ] hallo
+- [x] there
diff --git a/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html
@@ -137,6 +137,20 @@ <h1>
       www.example.com
      </a>
     </p>
+    <ul class="contains-task-list simple">
+     <li class="task-list-item">
+      <p>
+       <input class="task-list-item-checkbox" disabled="disabled" type="checkbox"/>
+       hallo
+      </p>
+     </li>
+     <li class="task-list-item">
+      <p>
+       <input checked="checked" class="task-list-item-checkbox" disabled="disabled" type="checkbox"/>
+       there
+      </p>
+     </li>
+    </ul>
    </section>
   </div>
  </div>

diff --git a/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.xml b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.xml
@@ -73,3 +73,14 @@
             linkify URL: 
             <reference refuri="http://www.example.com">
                 www.example.com
+        <bullet_list classes="contains-task-list">
+            <list_item classes="task-list-item">
+                <paragraph>
+                    <raw format="html" xml:space="preserve">
+                        <input class="task-list-item-checkbox" disabled="disabled" type="checkbox">
+                     hallo
+            <list_item classes="task-list-item">
+                <paragraph>
+                    <raw format="html" xml:space="preserve">
+                        <input class="task-list-item-checkbox" checked="checked" disabled="disabled" type="checkbox">
+                     there