✨ NEW: Add dollarmath plugin (#38)

`dollarmath` is an improved version of `texmath`, for `$`/`$$` enclosed math only.
 It is more performant, handles `\` escaping properly and allows for more configuration.

It is implemented in a more "markdown-it" way; primarily iterating through the source character, rather than using regexes.
This is easier to understand, actually more performant (according to the benchmark tests), and allows for greater control over options like allowing internal spaces (which texmath hardcodes).

Author: chrisjsewell

benchmarking/bench_plugins.py

@@ -6,6 +6,7 @@
     amsmath,
     container,
     deflist,
+    dollarmath,
     footnote,
     front_matter,
     texmath,
@@ -67,3 +68,9 @@ def test_front_matter(benchmark, parser, spec_text):
 def test_texmath(benchmark, parser, spec_text):
     parser.use(texmath.texmath_plugin)
     benchmark(parser.render, spec_text)
+
+
+@pytest.mark.benchmark(group="plugins")
+def test_dollarmath(benchmark, parser, spec_text):
+    parser.use(dollarmath.dollarmath_plugin)
+    benchmark(parser.render, spec_text)

docs/contributing.md

@@ -66,7 +66,7 @@ For documentation build tests:
 
 1. Does it already exist as JavaScript implementation ([see npm](https://www.npmjs.com/search?q=keywords:markdown-it-plugin))?
    Where possible try to port directly from that.
-   It is ususually better to modify existing code, instead of writing all from scratch.
+   It is usually better to modify existing code, instead of writing all from scratch.
 2. Try to find the right place for your plugin rule:
   - Will it conflict with existing markup (by priority)?
     - If yes - you need to write an inline or block rule.

docs/plugins.md

@@ -62,6 +62,9 @@ Other plugins are then available *via* the `markdown_it.extensions` package:
     $\alpha = \frac{1}{2}$
     ```
 
+- `dollarmath` is an improved version of `texmath`, for `$`/`$$` enclosed math only.
+  It is more performant, handles `\` escaping properly and allows for more configuration.
+
 - `amsmath` also parses TeX math equations, but without the surrounding delimiters and only for top-level [amsmath](https://ctan.org/pkg/amsmath) environments:
 
     ```latex

markdown_it/extensions/dollarmath/__init__.py

@@ -0,0 +1 @@
+from .index import dollarmath_plugin  # noqa F401

markdown_it/extensions/dollarmath/index.py

@@ -0,0 +1,238 @@
+import re
+
+from markdown_it import MarkdownIt
+from markdown_it.rules_inline import StateInline
+from markdown_it.rules_block import StateBlock
+from markdown_it.common.utils import isWhiteSpace
+
+
+def dollarmath_plugin(
+    md: MarkdownIt, allow_labels=True, allow_space=True, allow_digits=True
+):
+    """Plugin for parsing dollar enclosed math, e.g. ``$a=1$``.
+
+    :param allow_labels: Capture math blocks with label suffix, e.g. ``$$a=1$$ (eq1)``
+    :param allow_space: Parse inline math when there is space
+        after/before the opening/closing ``$``, e.g. ``$ a $``
+    :param allow_digits: Parse inline math when there is a digit
+        before/after the opening/closing ``$``, e.g. ``1$`` or ``$2``.
+        This is useful when also using currency.
+    """
+
+    md.inline.ruler.before(
+        "escape", "math_inline", math_inline_dollar(allow_space, allow_digits)
+    )
+    md.add_render_rule("math_inline", render_math_inline)
+
+    md.block.ruler.before("fence", "math_block", math_block_dollar(allow_labels))
+    md.add_render_rule("math_block", render_math_block)
+    md.add_render_rule("math_block_eqno", render_math_block_eqno)
+
+
+def render_math_inline(self, tokens, idx, options, env):
+    return "<eq>{0}</eq>".format(tokens[idx].content)
+
+
+def render_math_block(self, tokens, idx, options, env):
+    return "<section>\n<eqn>{0}</eqn>\n</section>\n".format(tokens[idx].content)
+
+
+def render_math_block_eqno(self, tokens, idx, options, env):
+    return '<section>\n<eqn>{0}</eqn>\n<span class="eqno">({1})</span>\n</section>\n'.format(
+        tokens[idx].content, tokens[idx].info
+    )
+
+
+def is_escaped(state: StateInline, back_pos: int, mod: int = 0):
+    # count how many \ are before the current position
+    backslashes = 0
+    while back_pos >= 0:
+        back_pos = back_pos - 1
+        if state.srcCharCode[back_pos] == 0x5C:  # /* \ */
+            backslashes += 1
+        else:
+            break
+
+    if not backslashes:
+        return
+
+    # if an odd number of \ then ignore
+    if (backslashes % 2) != mod:
+        return True
+
+    return False
+
+
+def math_inline_dollar(allow_space=True, allow_digits=True):
+    def _math_inline_dollar(state: StateInline, silent: bool):
+
+        # TODO options:
+        # even/odd backslash escaping
+        # allow $$ blocks
+
+        if state.srcCharCode[state.pos] != 0x24:  # /* $ */
+            return False
+
+        if not allow_space:
+            # whitespace not allowed straight after opening $
+            try:
+                if isWhiteSpace(state.srcCharCode[state.pos + 1]):
+                    return False
+            except IndexError:
+                return False
+
+        if not allow_digits:
+            # digit not allowed straight before opening $
+            try:
+                if state.src[state.pos - 1].isdigit():
+                    return False
+            except IndexError:
+                pass
+
+        if is_escaped(state, state.pos):
+            return False
+
+        # find closing $
+        pos = state.pos + 1
+        found_closing = False
+        while True:
+            try:
+                end = state.srcCharCode.index(0x24, pos)
+            except ValueError:
+                return False
+
+            if is_escaped(state, end):
+                pos = end + 1
+            else:
+                found_closing = True
+                break
+
+        if not found_closing:
+            return False
+
+        if not allow_space:
+            # whitespace not allowed straight before closing $
+            try:
+                if isWhiteSpace(state.srcCharCode[end - 1]):
+                    return False
+            except IndexError:
+                return False
+
+        if not allow_digits:
+            # digit not allowed straight after closing $
+            try:
+                if state.src[end + 1].isdigit():
+                    return False
+            except IndexError:
+                pass
+
+        text = state.src[state.pos + 1 : end]
+
+        # ignore empty
+        if not text:
+            return False
+
+        if not silent:
+            token = state.push("math_inline", "math", 0)
+            token.content = text
+            token.markup = "$"
+
+        state.pos = end + 1
+
+        return True
+
+    return _math_inline_dollar
+
+
+# reversed end of block dollar equation, with equation label
+DOLLAR_EQNO_REV = re.compile(r"^\s*\)([^)$\r\n]+?)\(\s*\${2}")
+
+
+def math_block_dollar(allow_labels=True):
+    def _math_block_dollar(
+        state: StateBlock, startLine: int, endLine: int, silent: bool
+    ):
+
+        # TODO internal backslash escaping
+
+        haveEndMarker = False
+        startPos = state.bMarks[startLine] + state.tShift[startLine]
+        end = state.eMarks[startLine]
+
+        # if it's indented more than 3 spaces, it should be a code block
+        if state.sCount[startLine] - state.blkIndent >= 4:
+            return False
+
+        if startPos + 2 > end:
+            return False
+
+        if (
+            state.srcCharCode[startPos] != 0x24
+            or state.srcCharCode[startPos + 1] != 0x24
+        ):  # /* $ */
+            return False
+
+        # search for end of block
+        nextLine = startLine
+        label = None
+
+        # search for end of block on same line
+        lineText = state.src[startPos:end]
+        if len(lineText.strip()) > 3:
+            lineText = state.src[startPos:end]
+            if lineText.strip().endswith("$$"):
+                haveEndMarker = True
+                end = end - 2 - (len(lineText) - len(lineText.strip()))
+            elif allow_labels:
+                # reverse the line and match
+                eqnoMatch = DOLLAR_EQNO_REV.match(lineText[::-1])
+                if eqnoMatch:
+                    haveEndMarker = True
+                    label = eqnoMatch.group(1)[::-1]
+                    end = end - eqnoMatch.end()
+
+        # search for end of block on subsequent line
+        if not haveEndMarker:
+            while True:
+                nextLine += 1
+                if nextLine >= endLine:
+                    break
+
+                start = state.bMarks[nextLine] + state.tShift[nextLine]
+                end = state.eMarks[nextLine]
+
+                if end - start < 2:
+                    continue
+
+                lineText = state.src[start:end]
+
+                if lineText.strip().endswith("$$"):
+                    haveEndMarker = True
+                    end = end - 2 - (len(lineText) - len(lineText.strip()))
+                    break
+
+                # reverse the line and match
+                if allow_labels:
+                    eqnoMatch = DOLLAR_EQNO_REV.match(lineText[::-1])
+                    if eqnoMatch:
+                        haveEndMarker = True
+                        label = eqnoMatch.group(1)[::-1]
+                        end = end - eqnoMatch.end()
+                        break
+
+        if not haveEndMarker:
+            return False
+
+        state.line = nextLine + (1 if haveEndMarker else 0)
+
+        token = state.push("math_block_eqno" if label else "math_block", "math", 0)
+        token.block = True
+        token.content = state.src[startPos + 2 : end]
+        token.markup = "$$"
+        token.map = [startLine, state.line]
+        if label:
+            token.info = label
+
+        return True
+
+    return _math_block_dollar

setup.py

@@ -51,12 +51,12 @@ def get_version():
             "psutil",
         ],
         "rtd": [
-            "sphinx>=2,<4",
-            "pyyaml",
-            "sphinx_book_theme",
             "myst-nb",
-            "sphinx-copybutton",
+            "sphinx_book_theme",
             "sphinx-panels~=0.4.0",
+            "sphinx-copybutton",
+            "sphinx>=2,<4",
+            "pyyaml",
         ],
         "compare": [
             "commonmark~=0.9.1",