‼️ BREAKING: Remove dollarmath from default myst_enable_extensions

docs/syntax/optional.md

@@ -95,8 +95,8 @@ and you will neeed to suppress the `myst.strikethrough` warning
 
 Math is parsed by adding to the `myst_enable_extensions` list option, in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html) one or both of:
 
-- `"dollarmath"` (added by default) for parsing of dollar `$` and `$$` encapsulated math.
-- `"amsmath"` (off by default) for direct parsing of [amsmath LaTeX environments](https://ctan.org/pkg/amsmath).
+- `"dollarmath"` for parsing of dollar `$` and `$$` encapsulated math.
+- `"amsmath"` for direct parsing of [amsmath LaTeX environments](https://ctan.org/pkg/amsmath).
 
 These options enable their respective Markdown parser plugins, as detailed in the [markdown-it plugin guide](markdown_it:md/plugins).
 
@@ -106,7 +106,7 @@ These options enable their respective Markdown parser plugins, as detailed in th
 
 ### Dollar delimited math
 
-Enabling dollar math will parse the following syntax:
+Enabling `dollarmath` will parse the following syntax:
 
 - Inline math: `$...$`
 - Display (block) math: `$$...$$`
@@ -235,7 +235,7 @@ See [the extended syntax option](syntax/amsmath).
 ### Mathjax and math parsing
 
 When building HTML using the [sphinx.ext.mathjax](https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax) extension (enabled by default),
-Myst-Parser injects the `tex2jax_ignore` (MathJax v2) and  `mathjax_ignore` (MathJax v3) classes in to the top-level section of each MyST document, and adds the following default MathJax configuration:
+If `dollarmath` is enabled, Myst-Parser injects the `tex2jax_ignore` (MathJax v2) and  `mathjax_ignore` (MathJax v3) classes in to the top-level section of each MyST document, and adds the following default MathJax configuration:
 
 MathJax version 2 (see [the tex2jax preprocessor](https://docs.mathjax.org/en/v2.7-latest/options/preprocessors/tex2jax.html#configure-tex2jax):
 

docs/syntax/syntax.md

@@ -368,9 +368,6 @@ header-rows: 1
 * - Type
   - MyST
   - reStructuredText
-* - Math shortcuts
-  - `$x^2$`
-  - N/A
 * - Front matter
   - ```md
     ---

myst_parser/docutils_renderer.py

@@ -595,10 +595,12 @@ def render_fence(self, token: SyntaxTreeNode) -> None:
 
     @property
     def blocks_mathjax_processing(self) -> bool:
-        """Only add mathjax ignore classes if using sphinx and myst_update_mathjax is True."""
+        """Only add mathjax ignore classes if using sphinx,
+        and using the ``dollarmath`` extension, and ``myst_update_mathjax=True``.
+        """
         return (
             self.sphinx_env is not None
-            and "myst_update_mathjax" in self.sphinx_env.config
+            and "dollarmath" in self.md_config.enable_extensions
             and self.md_config.update_mathjax
         )
 
@@ -985,6 +987,17 @@ def render_math_block(self, token: SyntaxTreeNode) -> None:
         self.add_line_and_source_path(node, token)
         self.current_node.append(node)
 
+    def render_amsmath(self, token: SyntaxTreeNode) -> None:
+        # note docutils does not currently support the nowrap attribute
+        # or equation numbering, so this is overridden in the sphinx renderer
+        node = nodes.math_block(
+            token.content, token.content, nowrap=True, classes=["amsmath"]
+        )
+        if token.meta["numbered"] != "*":
+            node["numbered"] = True
+        self.add_line_and_source_path(node, token)
+        self.current_node.append(node)
+
     def render_footnote_ref(self, token: SyntaxTreeNode) -> None:
         """Footnote references are added as auto-numbered,
         .i.e. `[^a]` is read as rST `[#a]_`

myst_parser/main.py

@@ -49,7 +49,7 @@ class MdParserConfig:
         metadata={"help": "Use strict Github Flavoured Markdown parser"},
     )
     enable_extensions: Sequence[str] = attr.ib(
-        factory=lambda: ["dollarmath"], metadata={"help": "Enable extensions"}
+        factory=list, metadata={"help": "Enable extensions"}
     )
 
     linkify_fuzzy_links: bool = attr.ib(

myst_parser/mathjax.py

@@ -51,6 +51,8 @@ def override_mathjax(app: Sphinx):
             None,
         )
 
+    if "dollarmath" not in app.config["myst_enable_extensions"]:
+        return
     if not app.env.myst_config.update_mathjax:  # type: ignore[attr-defined]
         return
 

myst_parser/sphinx_renderer.py

@@ -186,6 +186,7 @@ def _random_label(self) -> str:
         return str(uuid4())
 
     def render_amsmath(self, token: SyntaxTreeNode) -> None:
+        """Renderer for the amsmath extension."""
         # environment = token.meta["environment"]
         content = token.content
 

setup.cfg

@@ -79,7 +79,7 @@ testing =
     pytest>=6,<7
     pytest-cov
     pytest-regressions
-    pytest-param-files~=0.3.3
+    pytest-param-files~=0.3.4
 
 [flake8]
 max-line-length = 100

tests/test_renderers/fixtures/docutil_syntax_elements.md

@@ -307,56 +307,6 @@ Nested Enumrated List:
                         c
 .
 
---------------------------
-Inline Math:
-.
-$foo$
-.
-<document source="notset">
-    <paragraph>
-        <math>
-            foo
-.
-
---------------------------
-Inline Math, multi-line:
-.
-a $foo
-bar$ b
-.
-<document source="notset">
-    <paragraph>
-        a
-        <math>
-            foo
-            bar
-         b
-.
-
---------------------------
-Inline Math, multi-line with line break (invalid):
-.
-a $foo
-
-bar$ b
-.
-<document source="notset">
-    <paragraph>
-        a $foo
-    <paragraph>
-        bar$ b
-.
-
---------------------------
-Math Block:
-.
-$$foo$$
-.
-<document source="notset">
-    <math_block nowrap="False" number="True" xml:space="preserve">
-        foo
-.
-
 --------------------------
 Sphinx Role containing backtick:
 .

tests/test_renderers/fixtures/docutil_syntax_extensions.txt

@@ -0,0 +1,139 @@
+[dollarmath] --myst-enable-extensions=dollarmath
+.
+$foo$
+
+a $foo
+bar$ b
+
+$$foo$$
+
+$$
+a = 1
+$$
+.
+<document source="<string>">
+    <paragraph>
+        <math>
+            foo
+    <paragraph>
+        a
+        <math>
+            foo
+            bar
+         b
+    <math_block nowrap="False" number="True" xml:space="preserve">
+        foo
+    <math_block nowrap="False" number="True" xml:space="preserve">
+
+        a = 1
+.
+
+[amsmath] --myst-enable-extensions=amsmath
+.
+\begin{equation} a \end{equation}
+
+\begin{equation}
+a
+\end{equation}
+
+\begin{equation*}
+a
+\end{equation*}
+.
+<document source="<string>">
+    <math_block classes="amsmath" nowrap="True" numbered="True" xml:space="preserve">
+        \begin{equation} a \end{equation}
+    <math_block classes="amsmath" nowrap="True" numbered="True" xml:space="preserve">
+        \begin{equation}
+        a
+        \end{equation}
+    <math_block classes="amsmath" nowrap="True" xml:space="preserve">
+        \begin{equation*}
+        a
+        \end{equation*}
+.
+
+[deflist] --myst-enable-extensions=deflist
+.
+term
+: definition
+.
+<document source="<string>">
+    <definition_list classes="simple myst">
+        <definition_list_item>
+            <term>
+                term
+            <definition>
+                <paragraph>
+                    definition
+.
+
+[fieldlist] --myst-enable-extensions=fieldlist
+.
+:name: value
+.
+<document source="<string>">
+    <docinfo>
+        <field classes="name">
+            <field_name>
+                name
+            <field_body>
+                <paragraph>
+                    value
+.
+
+[colon_fence] --myst-enable-extensions=colon_fence
+.
+:::{note}
+content
+:::
+.
+<document source="<string>">
+    <note>
+        <paragraph>
+            content
+.
+
+[replacements] --myst-enable-extensions=replacements
+.
+(c) (C) (r) (R) (tm) (TM) (p) (P) +- ...
+.
+<document source="<string>">
+    <paragraph>
+        © © ® ® ™ ™ § § ± …
+.
+
+[strikethrough] --myst-enable-extensions=strikethrough
+.
+~~foo~~
+.
+<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>
+        foo
+        <raw format="html" xml:space="preserve">
+            </s>
+.
+
+[tasklist] --myst-enable-extensions=tasklist
+.
+- [ ] foo
+- [x] bar
+.
+<document source="<string>">
+    <bullet_list bullet="-" 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">
+                 foo
+        <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">
+                 bar
+.

tests/test_renderers/fixtures/dollarmath.md

@@ -0,0 +1,81 @@
+--------------------------
+Inline Math:
+.
+$foo$
+.
+<document source="notset">
+    <paragraph>
+        <math>
+            foo
+.
+
+--------------------------
+Inline Math, multi-line:
+.
+a $foo
+bar$ b
+.
+<document source="notset">
+    <paragraph>
+        a
+        <math>
+            foo
+            bar
+         b
+.
+
+--------------------------
+Inline Math, multi-line with line break (invalid):
+.
+a $foo
+
+bar$ b
+.
+<document source="notset">
+    <paragraph>
+        a $foo
+    <paragraph>
+        bar$ b
+.
+
+--------------------------
+Math Block:
+.
+$$foo$$
+.
+<document source="notset">
+    <math_block nowrap="False" number="True" xml:space="preserve">
+        foo
+.
+
+--------------------------
+Math Block With Equation Label:
+.
+$$foo$$ (abc)
+.
+<document source="notset">
+    <target ids="equation-abc">
+    <math_block docname="mock_docname" label="abc" nowrap="False" number="1" xml:space="preserve">
+        foo
+.
+
+--------------------------
+Math Block multiple:
+.
+$$
+a = 1
+$$
+
+$$
+b = 2
+$$ (a)
+.
+<document source="notset">
+    <math_block nowrap="False" number="True" xml:space="preserve">
+
+        a = 1
+    <target ids="equation-a">
+    <math_block docname="mock_docname" label="a" nowrap="False" number="1" xml:space="preserve">
+
+        b = 2
+.