✨ More/improved syntax extensions (GFM alerts, GFM autolink, ...) (#1128)

Author: chrisjsewell

.pre-commit-config.yaml

@@ -35,8 +35,8 @@ repos:
       additional_dependencies:
       - types-urllib3
       - sphinx~=8.2
-      - markdown-it-py~=4.0
-      - mdit-py-plugins~=0.5.0
+      - markdown-it-py~=4.2
+      - mdit-py-plugins~=0.6.0
       files: >
         (?x)^(
             myst_parser/.*py|

docs/conf.py

@@ -96,6 +96,7 @@
 # -- MyST settings ---------------------------------------------------
 
 myst_enable_extensions = [
+    "alert",
     "dollarmath",
     "amsmath",
     "deflist",

docs/syntax/admonitions.md

@@ -3,6 +3,10 @@
 Admonitions (also known as callouts) highlight a particular block of text,
 that exists slightly apart from the narrative of your page, such as a note or a warning.
 
+:::{seealso}
+The [alert extension](syntax/alerts) provides GitHub-style alerts as a lightweight alternative syntax for admonitions.
+:::
+
 Admonitions are a special case of {{directive}} extensions.
 It is advised to use admonitions with the [colon_fence](#syntax/colon_fence) extension, which signify that the content of the block is also MyST Markdown.
 

docs/syntax/optional.md

@@ -28,12 +28,14 @@ To enable all the syntaxes explained below:
 
 ```python
 myst_enable_extensions = [
+    "alert",
     "amsmath",
     "attrs_inline",
     "colon_fence",
     "deflist",
     "dollarmath",
     "fieldlist",
+    "gfm_autolink",
     "html_admonition",
     "html_image",
     "linkify",
@@ -89,6 +91,12 @@ text  | converted
 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*~~.
 
+```{versionadded} 5.1.0
+`myst_strikethrough_single_tilde` option
+```
+
+To also allow single tilde delimiters (e.g. `~strikethrough~`), set `myst_strikethrough_single_tilde = True` in your {{ confpy }}.
+
 :::{warning}
 This extension is currently only supported for HTML output,
 and you will need to suppress the `myst.strikethrough` warning
@@ -296,6 +304,27 @@ This extension requires that [linkify-it-py](https://github.com/tsutsu3/linkify-
 Either directly; `pip install linkify-it-py` or *via* `pip install myst-parser[linkify]`.
 :::
 
+(syntax/gfm-autolink)=
+## GFM Autolinks
+
+```{versionadded} 5.1.0
+```
+
+Adding `"gfm_autolink"` to `myst_enable_extensions` (in the {{ confpy }}) will enable the [GitHub Flavored Markdown autolink extension](https://github.github.com/gfm/#autolinks-extension-).
+This recognises bare `www.` URLs, `http(s)://` URLs, and email addresses, converting them to hyperlinks.
+
+Unlike the `linkify` extension, `gfm_autolink` does **not** require any additional package to be installed.
+It follows the GFM specification for determining URL boundaries.
+
+:::{note}
+`gfm_autolink` and `linkify` should not both be enabled at the same time, as they serve the same purpose with different matching algorithms.
+
+Key differences:
+
+- **`linkify`** matches schema-less domains (e.g. `example.com` with `fuzzy_link=True`), supports many protocols, and requires `linkify-it-py`.
+- **`gfm_autolink`** only matches `www.`-prefixed URLs, `http(s)://`/`mailto:`/`xmpp:` URLs, and email addresses. It has no extra dependency and follows GFM URL boundary rules exactly.
+:::
+
 (syntax/substitutions)=
 
 ## Substitutions (with Jinja2)
@@ -412,6 +441,13 @@ you can also use `:::` delimiters to denote directives, instead of ```` ``` ````
 Using colons instead of back-ticks has the benefit of allowing the content to be rendered correctly, when you are working in any standard Markdown editor.
 It is ideal for admonition type directives (as documented in [Directives](syntax/directives)) or tables with titles, for example:
 
+```{versionadded} 5.1.0
+`myst_colon_fence_exact_match` option
+```
+
+By default, a closing colon fence with *at least* as many colons as the opening fence will close the block (matching the behaviour of backtick fences).
+To require the closing fence to have *exactly* the same number of colons as the opening, set `myst_colon_fence_exact_match = True` in your {{ confpy }}.
+
 :::::{myst-example}
 
 :::{note}
@@ -590,6 +626,38 @@ and are applied to markdown list items starting with `[ ]` or `[x]`:
 - [x] An item that is complete
 :::
 
+(syntax/alerts)=
+## Alerts (GitHub-style callouts)
+
+```{versionadded} 5.1.0
+```
+
+By adding `"alert"` to `myst_enable_extensions` (in the {{ confpy }}),
+you can use [GitHub-style alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) (also known as callouts).
+These are rendered as admonition nodes in the output.
+
+The syntax is a blockquote beginning with a special marker like `[!NOTE]`:
+
+:::{myst-example}
+> [!NOTE]
+> This is a note alert.
+
+> [!TIP]
+> This is a tip alert.
+
+> [!IMPORTANT]
+> This is an important alert.
+
+> [!WARNING]
+> This is a warning alert.
+
+> [!CAUTION]
+> This is a caution alert.
+:::
+
+The five supported alert types map to the following docutils admonition nodes:
+`NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`.
+
 (syntax/fieldlists)=
 ## Field Lists
 

myst_parser/config/main.py

@@ -28,6 +28,7 @@ def check_extensions(inst: "MdParserConfig", field: dc.Field, value: Any) -> Non
         raise TypeError(f"'{field.name}' not iterable: {value}")
     diff = set(value).difference(
         [
+            "alert",
             "amsmath",
             "attrs_image",
             "attrs_inline",
@@ -36,6 +37,7 @@ def check_extensions(inst: "MdParserConfig", field: dc.Field, value: Any) -> Non
             "deflist",
             "dollarmath",
             "fieldlist",
+            "gfm_autolink",
             "html_admonition",
             "html_image",
             "linkify",
@@ -440,6 +442,24 @@ def __repr__(self) -> str:
         },
     )
 
+    strikethrough_single_tilde: bool = dc.field(
+        default=False,
+        metadata={
+            "validator": instance_of(bool),
+            "help": "Allow single tilde (~) for strikethrough, in addition to double (~~)",
+            "extension": "strikethrough",
+        },
+    )
+
+    colon_fence_exact_match: bool = dc.field(
+        default=False,
+        metadata={
+            "validator": instance_of(bool),
+            "help": "Require closing colon fence to have exactly the same number of colons as the opening",
+            "extension": "colon_fence",
+        },
+    )
+
     # docutils only (replicating aspects of sphinx config)
 
     suppress_warnings: Sequence[str] = dc.field(

myst_parser/mdit_to_docutils/base.py

@@ -515,7 +515,40 @@ def render_list_item(self, token: SyntaxTreeNode) -> None:
         self.copy_attributes(token, item_node, keys=("class", "id"))
         self.add_line_and_source_path(item_node, token)
         with self.current_node_context(item_node, append=True):
-            self.render_children(token)
+            # Handle built-in tasklist checkbox (markdown-it-py >= 4.1)
+            meta = token.meta if token.meta else {}
+            if "checked" in meta:
+                checked = meta["checked"]
+                editable = self.md.options.get("tasklists_editable", False)
+                if editable:
+                    item_node["classes"].append("enabled")
+                checked_attr = 'checked="checked" ' if checked else ""
+                disabled_attr = "" if editable else 'disabled="disabled" '
+                checkbox_html = (
+                    f'<input class="task-list-item-checkbox" '
+                    f'{checked_attr}{disabled_attr}type="checkbox">'
+                )
+                self.render_children(token)
+                # The first child is always a paragraph: markdown-it-py emits
+                # paragraph_open/close for both tight and loose lists (tight
+                # lists mark them hidden, but we render them regardless).
+                # Tasklist items by definition start with `[ ]`/`[x]` text
+                # content, so a paragraph is always the first block child.
+                if item_node.children and isinstance(
+                    item_node.children[0], nodes.paragraph
+                ):
+                    item_node.children[0].insert(
+                        0, nodes.raw("", checkbox_html, format="html")
+                    )
+                else:
+                    self.create_warning(
+                        "Tasklist item has no leading paragraph for checkbox",
+                        MystWarnings.RENDER_METHOD,
+                        line=token_line(token, 0),
+                        append_to=self.current_node,
+                    )
+            else:
+                self.render_children(token)
 
     def render_em(self, token: SyntaxTreeNode) -> None:
         node = nodes.emphasis()
@@ -552,6 +585,30 @@ def render_blockquote(self, token: SyntaxTreeNode) -> None:
                         inline=True,
                     )
 
+    _alert_node_mapping: dict[str, type[nodes.Element]] = {
+        "NOTE": nodes.note,
+        "TIP": nodes.tip,
+        "IMPORTANT": nodes.important,
+        "WARNING": nodes.warning,
+        "CAUTION": nodes.caution,
+    }
+
+    def render_alert(self, token: SyntaxTreeNode) -> None:
+        """Render a GitHub-style alert as a docutils admonition."""
+        kind = token.info.upper() if token.info else ""
+        node_cls = self._alert_node_mapping.get(kind, nodes.admonition)
+        admonition = node_cls()
+        if node_cls is nodes.admonition:
+            # Generic admonition needs a title
+            title = nodes.title("", kind.capitalize())
+            admonition += title
+        self.add_line_and_source_path(admonition, token)
+        with self.current_node_context(admonition, append=True):
+            self.render_children(token)
+
+    def render_alert_title(self, token: SyntaxTreeNode) -> None:
+        """Skip the alert title — docutils admonitions generate their own."""
+
     def render_hr(self, token: SyntaxTreeNode) -> None:
         node = nodes.transition()
         self.add_line_and_source_path(node, token)

myst_parser/parsers/mdit.py

@@ -8,18 +8,19 @@
 
 from markdown_it import MarkdownIt
 from markdown_it.renderer import RendererProtocol
+from markdown_it.rules_block import make_fence_rule
 from mdit_py_plugins.amsmath import amsmath_plugin
 from mdit_py_plugins.attrs import attrs_block_plugin, attrs_plugin
-from mdit_py_plugins.colon_fence import colon_fence_plugin
 from mdit_py_plugins.deflist import deflist_plugin
 from mdit_py_plugins.dollarmath import dollarmath_plugin
 from mdit_py_plugins.field_list import fieldlist_plugin
 from mdit_py_plugins.footnote import footnote_plugin
 from mdit_py_plugins.front_matter import front_matter_plugin
+from mdit_py_plugins.gfm import gfm_plugin
+from mdit_py_plugins.gfm_autolink import gfm_autolink_plugin
 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 myst_parser.config.main import MdParserConfig
@@ -43,16 +44,13 @@ def create_md_parser(
 
     if config.gfm_only:
         # see https://github.github.com/gfm/
-        md = (
-            MarkdownIt("commonmark", renderer_cls=renderer)
-            # note, strikethrough currently only supported tentatively for HTML
-            .enable("strikethrough")
-            .enable("table")
-            .use(tasklists_plugin, enabled=config.enable_checkboxes)
-            .enable("linkify")
-            .use(wordcount_plugin, per_minute=config.words_per_minute)
+        md = MarkdownIt("commonmark", renderer_cls=renderer)
+        md.use(
+            gfm_plugin,
+            tasklists_editable=config.enable_checkboxes,
         )
-        md.options.update({"linkify": True, "myst_config": config})
+        md.use(wordcount_plugin, per_minute=config.words_per_minute)
+        md.options.update({"myst_config": config})
         return md
 
     md = (
@@ -76,8 +74,11 @@ def create_md_parser(
         md.enable("linkify")
         if md.linkify is not None:
             md.linkify.set({"fuzzy_link": config.linkify_fuzzy_links})
+    if "gfm_autolink" in config.enable_extensions:
+        md.use(gfm_autolink_plugin)
     if "strikethrough" in config.enable_extensions:
         md.enable("strikethrough")
+        md.options["strikethrough_single_tilde"] = config.strikethrough_single_tilde
     if "dollarmath" in config.enable_extensions:
         md.use(
             dollarmath_plugin,
@@ -87,15 +88,28 @@ def create_md_parser(
             double_inline=config.dmath_double_inline,
         )
     if "colon_fence" in config.enable_extensions:
-        md.use(colon_fence_plugin)
+        colon_fence = make_fence_rule(
+            markers=(":",),
+            token_type="colon_fence",
+            exact_match=config.colon_fence_exact_match,
+        )
+        md.block.ruler.before(
+            "fence",
+            "colon_fence",
+            colon_fence,
+            {"alt": ["paragraph", "reference", "blockquote", "list", "footnote_def"]},
+        )
     if "amsmath" in config.enable_extensions:
         md.use(amsmath_plugin)
     if "deflist" in config.enable_extensions:
         md.use(deflist_plugin)
     if "fieldlist" in config.enable_extensions:
         md.use(fieldlist_plugin)
     if "tasklist" in config.enable_extensions:
-        md.use(tasklists_plugin, enabled=config.enable_checkboxes)
+        md.options["tasklists"] = True
+        md.options["tasklists_editable"] = config.enable_checkboxes
+    if "alert" in config.enable_extensions:
+        md.options["alerts"] = True
     if "substitution" in config.enable_extensions:
         md.use(substitution_plugin, *config.sub_delimiters)
     if "attrs_inline" in config.enable_extensions:

pyproject.toml

@@ -36,8 +36,8 @@ requires-python = ">=3.11"
 dependencies = [
     "docutils>=0.20,<0.23",
     "jinja2", # required for substitutions, but let sphinx choose version
-    "markdown-it-py~=4.0",
-    "mdit-py-plugins~=0.5",
+    "markdown-it-py~=4.2",
+    "mdit-py-plugins~=0.6",
     "pyyaml",
     "sphinx>=8,<10",
 ]
@@ -88,8 +88,8 @@ mypy = [
     "mypy==1.19.1",
     "types-urllib3",
     "sphinx~=8.2",
-    "markdown-it-py~=4.0",
-    "mdit-py-plugins~=0.5.0",
+    "markdown-it-py~=4.2",
+    "mdit-py-plugins~=0.6.0",
 ]
 ruff = ["ruff==0.14.11"]