✨ NEW: Add strikethrough extension (#502)

The `strikethrough` extension allows text within `~~` delimiters to have a strikethrough (horizontal line) placed over it.
For example, `~~strikethrough with *emphasis*~~`.

Note, this extension is currently only supported for HTML output,
and will generate a `myst.strikethrough` warning
(since docutils does not have a native strikethrough node).

docs/conf.py

@@ -85,6 +85,7 @@
     "smartquotes",
     "replacements",
     "linkify",
+    "strikethrough",
     "substitution",
     "tasklist",
 ]
@@ -102,6 +103,8 @@
     "using/reference.md": "syntax/reference.md",
 }
 
+suppress_warnings = ["myst.strikethrough"]
+
 
 def run_apidoc(app):
     """generate apidoc

docs/docutils.md

@@ -2,6 +2,9 @@
 
 # MyST with Docutils
 
+```{versionadded} 0.16.0
+```
+
 Sphinx, and thus MyST-Parser, is built on top of the [Docutils](https://docutils.sourceforge.io/docs/) package.
 MyST-Parser offers a renderer, parser and CLI-interface for working directly with Docutils, independent of Sphinx, as described below.
 

docs/syntax/optional.md

@@ -36,6 +36,7 @@ myst_enable_extensions = [
     "linkify",
     "replacements",
     "smartquotes",
+    "strikethrough",
     "substitution",
     "tasklist",
 ]
@@ -73,6 +74,22 @@ text  | converted
 ``--`` | --
 ``---`` | ---
 
+(syntax/strikethough)=
+
+## Strikethrough
+
+```{versionadded} 0.17.0
+```
+
+The `strikethrough` extension allows text within `~~` delimiters to have a strikethrough (horizontal line) placed over it.
+For example, `~~strikethrough with *emphasis*~~` renders as: ~~strikethrough with *emphasis*~~.
+
+:::{warning}
+This extension is currently only supported for HTML output,
+and you will neeed to suppress the `myst.strikethrough` warning
+(see [](howto/warnings))
+:::
+
 (syntax/math)=
 ## Math shortcuts
 
@@ -595,6 +612,9 @@ and are applied to markdown list items starting with `[ ]` or `[x]`:
 (syntax/fieldlists)=
 ## Field Lists
 
+```{versionadded} 0.16.0
+```
+
 Field lists are mappings from field names to field bodies,
 based on the [reStructureText syntax](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists).
 

docs/syntax/syntax.md

@@ -403,6 +403,9 @@ and can be used to store information for blog posting (see [ablog's myst-parser
 
 ### Setting a title
 
+```{versionadded} 0.17.0
+```
+
 If `myst_title_to_header` is set to `True`, and a `title` key is present in the front matter,
 then the title will be used as the document's header (parsed as Markdown.
 For example:

myst_parser/docutils_renderer.py

@@ -948,6 +948,19 @@ def render_table_row(self, token: SyntaxTreeNode) -> None:
                     with self.current_node_context(para, append=True):
                         self.render_children(child)
 
+    def render_s(self, token: SyntaxTreeNode) -> None:
+        """Render a strikethrough token."""
+        # TODO strikethrough not currently directly supported in docutils
+        self.create_warning(
+            "Strikethrough is currently only supported in HTML output",
+            line=token_line(token, 0),
+            subtype="strikethrough",
+            append_to=self.current_node,
+        )
+        self.current_node.append(nodes.raw("", "<s>", format="html"))
+        self.render_children(token)
+        self.current_node.append(nodes.raw("", "</s>", format="html"))
+
     def render_math_inline(self, token: SyntaxTreeNode) -> None:
         content = token.content
         node = nodes.math(content, content)

myst_parser/main.py

@@ -107,6 +107,7 @@ def check_extensions(self, attribute, value):
                 "smartquotes",
                 "replacements",
                 "linkify",
+                "strikethrough",
                 "substitution",
                 "tasklist",
             ]
@@ -242,6 +243,9 @@ def create_md_parser(
 ) -> MarkdownIt:
     """Return a Markdown parser with the required MyST configuration."""
 
+    # TODO warn if linkify required and linkify-it-py not installed
+    # (currently the parse will unceremoniously except)
+
     if config.commonmark_only:
         # see https://spec.commonmark.org/
         md = MarkdownIt("commonmark", renderer_cls=renderer).use(
@@ -252,9 +256,10 @@ def create_md_parser(
 
     if config.gfm_only:
         # see https://github.github.com/gfm/
-        # TODO strikethrough not currently supported in docutils
         md = (
             MarkdownIt("commonmark", renderer_cls=renderer)
+            # note, strikethrough currently only supported tentatively for HTML
+            .enable("strikethrough")
             .enable("table")
             .use(tasklists_plugin)
             .enable("linkify")
@@ -287,7 +292,8 @@ def create_md_parser(
         md.enable("linkify")
         if md.linkify is not None:
             md.linkify.set({"fuzzy_link": config.linkify_fuzzy_links})
-
+    if "strikethrough" in config.enable_extensions:
+        md.enable("strikethrough")
     if "dollarmath" in config.enable_extensions:
         md.use(
             dollarmath_plugin,

tests/test_renderers/fixtures/myst-config.txt

@@ -35,6 +35,22 @@ www.example.com
             www.example.com
 .
 
+[gfm-strikethrough] --myst-gfm-only="yes"
+.
+~~strike~~
+.
+<document source="<string>">
+    <paragraph>
+        <system_message level="2" line="1" source="<string>" type="WARNING">
+            <paragraph>
+                Strikethrough is currently only supported in HTML output [myst.strikethrough]
+        <raw format="html" xml:space="preserve">
+            <s>
+        strike
+        <raw format="html" xml:space="preserve">
+            </s>
+.
+
 [gfm-disallowed-html] --myst-gfm-only="yes"
 .
 <strong> <title> <style> <em>