✨ NEW: Add block math parsing/rendering

Author: chrisjsewell

README.md

@@ -13,6 +13,14 @@ it is more performant, handles backslash ``\\`` escaping properly, and allows fo
 
 ## Usage
 
+Options:
+
+- `allow_space`: Parse inline math when there is space after/before the opening/closing `$`, e.g. `$ a $`
+- `allow_digits`: Parse inline math when there is a digit before/after the opening/closing `$`, e.g. `1$` or `$2`
+- `double_inline`: Search for double-dollar math within inline contexts
+- `allow_labels`: Capture math blocks with label suffix, e.g. `$$a=1$$ (eq1)`
+- `labelNormalizer`: Function to normalize the label, by default replaces whitespace with `-` (to align with [HTML5 ids](https://html.spec.whatwg.org/multipage/dom.html#global-attributes:the-id-attribute-2))
+
 You should "bring your own" math render, provided as an option to the plugin.
 This function should take the string plus (optional) options, and return a string.
 For example, below the [KaTeX](https://github.com/Khan/KaTeX) render is used.
@@ -25,13 +33,16 @@ import MarkdownIt from "markdown-it"
 import dollarmathPlugin from "markdown-it-dollarmath"
 
 const mdit = MarkdownIt().use(dollarmathPlugin, {
-      allow_space: true,
-      allow_digits: true,
-      double_inline: true,
-      allow_labels: true,
-      renderer: renderToString,
-      optionsInline: { throwOnError: false, displayMode: false },
-      optionsBlock: { throwOnError: false, displayMode: true }
+    allow_space: true,
+    allow_digits: true,
+    double_inline: true,
+    allow_labels: true,
+    labelNormalizer: (label: string) => {
+        return label.replace(/[\s]+/g, "-")
+    }
+    renderer: renderToString,
+    optionsInline: { throwOnError: false, displayMode: false },
+    optionsBlock: { throwOnError: false, displayMode: true }
 })
 const text = mdit.render("$a = 1$")
 ```

docs/index.html

@@ -32,16 +32,27 @@ <h1>markdown-it-dollarmath</h1>
           Simply write in the text box below, then click away, and the text will be
           rendered.
         </p>
-        <textarea id="inputtext" class="inputtext" rows="6">
-# Title
-
+        <textarea id="inputtext" class="inputtext" rows="15">
 Inline math: $a=1$
 
-Inline display math: $$b=2$$</textarea
+Inline display math: $$b=2$$
+
+Block math:
+
+$$
+c=3
+$$
+
+Block math with label:
+
+$$
+d=4
+$$ (label)</textarea
         >
         <div id="renderer" class="rendered"></div>
       </div>
     </div>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
     <script>
       // get elements
       var inputText = document.getElementById("inputtext")

package.json

@@ -41,6 +41,9 @@
     "node": ">=12",
     "npm": ">=6"
   },
+  "peerDependencies": {
+    "markdown-it": "12.x"
+  },
   "devDependencies": {
     "@rollup/plugin-babel": "^5.3.0",
     "@rollup/plugin-commonjs": "^19.0.0",

src/index.ts

@@ -1,17 +1,19 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import type MarkdownIt from "markdown-it/lib"
-// import type StateBlock from "markdown-it/lib/rules_block/state_block"
+import type StateBlock from "markdown-it/lib/rules_block/state_block"
 import type StateInline from "markdown-it/lib/rules_inline/state_inline"
 
 export interface IOptions {
-  // Capture math blocks with label suffix, e.g. `$$a=1$$ (eq1)`
-  allow_labels?: boolean
   // Parse inline math when there is space after/before the opening/closing `$`, e.g. `$ a $`
   allow_space?: boolean
   // Parse inline math when there is a digit before/after the opening/closing `$`, e.g. `1$` or `$2`
   allow_digits?: boolean
   // Search for double-dollar math within inline contexts
   double_inline?: boolean
+  // Capture math blocks with label suffix, e.g. `$$a=1$$ (eq1)`
+  allow_labels?: boolean
+  // function to normalize the label, by default replaces whitespace with `-`
+  labelNormalizer?: (label: string) => string
   // The render function for math content
   renderer?: (content: string, options?: { [key: string]: any }) => string
   // options to parse to the render function, for inline math
@@ -21,10 +23,13 @@ export interface IOptions {
 }
 
 const OptionDefaults: IOptions = {
-  allow_labels: true,
   allow_space: true,
   allow_digits: true,
-  double_inline: true
+  double_inline: true,
+  allow_labels: true,
+  labelNormalizer: (label: string) => {
+    return label.replace(/[\s]+/g, "-")
+  }
 }
 
 /**
@@ -34,31 +39,70 @@ const OptionDefaults: IOptions = {
 export default function dollarmath_plugin(md: MarkdownIt, options?: IOptions): void {
   const fullOptions = { ...OptionDefaults, ...options }
   md.inline.ruler.before("escape", "math_inline", math_inline_dollar(fullOptions))
-  // md.block.ruler.before("fence", "math_block", math_block_dollar(fullOptions))
+  md.block.ruler.before("fence", "math_block", math_block_dollar(fullOptions))
 
   const renderer = fullOptions?.renderer
 
   if (renderer) {
     md.renderer.rules["math_inline"] = (tokens, idx) => {
       const content = tokens[idx].content
-      const renderOptions =
-        tokens[idx].markup === "$$"
-          ? fullOptions?.optionsBlock
-          : fullOptions?.optionsInline
       let res: string
       try {
-        res = renderer(content, renderOptions)
+        res = renderer(content, fullOptions?.optionsInline)
+      } catch (err) {
+        res = md.utils.escapeHtml(`${content}:${err.message}`)
+      }
+      return res
+    }
+    md.renderer.rules["math_inline_double"] = (tokens, idx) => {
+      const content = tokens[idx].content
+      let res: string
+      try {
+        res = renderer(content, fullOptions?.optionsBlock)
       } catch (err) {
         res = md.utils.escapeHtml(`${content}:${err.message}`)
       }
       return res
     }
+    md.renderer.rules["math_block"] = (tokens, idx) => {
+      const content = tokens[idx].content
+      let res: string
+      try {
+        res = renderer(content, fullOptions?.optionsBlock)
+      } catch (err) {
+        res = md.utils.escapeHtml(`${content}:${err.message}`)
+      }
+      return res
+    }
+    md.renderer.rules["math_block_label"] = (tokens, idx) => {
+      const content = tokens[idx].content
+      const label = tokens[idx].info
+      let res: string
+      try {
+        res = renderer(content, fullOptions?.optionsBlock)
+      } catch (err) {
+        res = md.utils.escapeHtml(`${content}:${err.message}`)
+      }
+      return (
+        res +
+        `\n<a href="#${label}" class="mathlabel" title="Permalink to this equation">¶</a>\n`
+      )
+    }
   } else {
-    // basic renderer for testing
+    // basic renderers for testing
     md.renderer.rules["math_inline"] = (tokens, idx) => {
+      return `<eq>${tokens[idx].content}</eq>`
+    }
+    md.renderer.rules["math_inline_double"] = (tokens, idx) => {
+      return `<eqn>${tokens[idx].content}</eqn>`
+    }
+    md.renderer.rules["math_block"] = (tokens, idx) => {
+      return `<section>\n<eqn>${tokens[idx].content}</eqn>\n</section>\n`
+    }
+    md.renderer.rules["math_block_label"] = (tokens, idx) => {
       const content = tokens[idx].content
-      const tag = tokens[idx].markup === "$$" ? "eqn" : "eq"
-      return `<${tag}>${content}</${tag}>`
+      const label = tokens[idx].info
+      return `<section>\n<eqn>${content}</eqn>\n<span class="eqno">(${label})</span>\n</section>\n`
     }
   }
 }
@@ -181,7 +225,11 @@ function math_inline_dollar(
       return false
     }
     if (!silent) {
-      const token = state.push("math_inline", "math", 0)
+      const token = state.push(
+        is_double ? "math_inline_double" : "math_inline",
+        "math",
+        0
+      )
       token.content = text
       token.markup = is_double ? "$$" : "$"
     }
@@ -190,3 +238,113 @@ function math_inline_dollar(
   }
   return math_inline_dollar_rule
 }
+
+/** Match a trailing label for a math block */
+function matchLabel(lineText: string, end: number): { label?: string; end: number } {
+  // reverse the line and match
+  const eqnoMatch = lineText
+    .split("")
+    .reverse()
+    .join("")
+    .match(/^\s*\)(?<label>[^)$\r\n]+?)\(\s*\${2}/)
+  if (eqnoMatch && eqnoMatch.groups) {
+    const label = eqnoMatch.groups["label"].split("").reverse().join("")
+    end = end - ((eqnoMatch.index || 0) + eqnoMatch[0].length)
+    return { label, end }
+  }
+  return { end }
+}
+
+/** Generate inline dollar rule */
+function math_block_dollar(
+  options: IOptions
+): (state: StateBlock, startLine: number, endLine: number, silent: boolean) => boolean {
+  /** Block dollar rule */
+  function math_block_dollar_rule(
+    state: StateBlock,
+    startLine: number,
+    endLine: number,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    silent: boolean
+  ): boolean {
+    let haveEndMarker = false
+    const startPos = state.bMarks[startLine] + state.tShift[startLine]
+    let 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.src.charCodeAt(startPos) != 0x24 ||
+      state.src.charCodeAt(startPos + 1) != 0x24
+    ) {
+      return false
+    }
+    // search for end of block
+    let nextLine = startLine
+    let label: undefined | string = undefined
+    // search for end of block on same line
+    let lineText = state.src.slice(startPos, end)
+    if (lineText.trim().length > 3) {
+      if (lineText.trim().endsWith("$$")) {
+        haveEndMarker = true
+        end = end - 2 - (lineText.length - lineText.trim().length)
+      } else if (options.allow_labels) {
+        const output = matchLabel(lineText, end)
+        if (output.label !== undefined) {
+          haveEndMarker = true
+          label = output.label
+          end = output.end
+        }
+      }
+    }
+
+    // search for end of block on subsequent line
+    let start: number
+    if (!haveEndMarker) {
+      while (nextLine + 1 < endLine) {
+        nextLine += 1
+        start = state.bMarks[nextLine] + state.tShift[nextLine]
+        end = state.eMarks[nextLine]
+        if (end - start < 2) {
+          continue
+        }
+        lineText = state.src.slice(start, end)
+        if (lineText.trim().endsWith("$$")) {
+          haveEndMarker = true
+          end = end - 2 - (lineText.length - lineText.trim().length)
+          break
+        }
+        if (options.allow_labels) {
+          const output = matchLabel(lineText, end)
+          if (output.label !== undefined) {
+            haveEndMarker = true
+            label = output.label
+            end = output.end
+            break
+          }
+        }
+      }
+    }
+    if (!haveEndMarker) {
+      return false
+    }
+
+    state.line = nextLine + (haveEndMarker ? 1 : 0)
+
+    const token = state.push(label ? "math_block_label" : "math_block", "math", 0)
+    token.block = true
+    token.content = state.src.slice(startPos + 2, end)
+    token.markup = "$$"
+    token.map = [startLine, state.line]
+    if (label) {
+      token.info = options.labelNormalizer ? options.labelNormalizer(label) : label
+    }
+    return true
+  }
+  return math_block_dollar_rule
+}

tests/fixtures.spec.ts

@@ -28,6 +28,7 @@ describe("Parses basic", () => {
       allow_labels: true
     })
     const rendered = mdit.render(text)
+    // console.log(rendered)
     it(name, () => expect(rendered.trim()).toEqual(expected.trim()))
   })