Provide a handy option for custom-element renderers

Author: runarberg

README.md

@@ -101,7 +101,7 @@ use the default math renderer.
 
 ## Usage
 
-```javascript
+```js
 import markdownIt from "markdown-it";
 import markdownItMath from "markdown-it-math";
 
@@ -111,16 +111,17 @@ const options = {
   inlineClose: "$",
   blockOpen: "$$",
   blockClose: "$$",
-  defaultRendererOptions: {},
-  inlineRenderer: (src) => mathup(src, defaultRendererOptions).toString(),
-  blockRenderer: (src) =>
-    mathup({ ...defaultRendererOptions, display: "block" }).toString(),
+  defaultRendererOptions,
+  inlineCustomElement, // see below
+  inlineRenderer, // see below
+  blockCustomElement, // see below
+  blockRenderer, // see below
 };
 
 const md = markdownIt().use(markdownItMath, options);
 ```
 
-```javascript
+```js
 md.render(`
 A text $1+1=2$ with math.
 
@@ -134,11 +135,49 @@ $$
 
 (See [mathup][mathup] for reference about the default renderer).
 
+### Options
+
+- `inlineOpen`: The delimiter to start an inline math expression. Default `$`
+- `inlineClose`: The delimiter to close an inline math expression. Default `$`
+- `blockOpen`: The delimiter to start a block math expression. Default `$$`
+- `blockClose`: The delimiter to close a block math expression. Default `$$`
+- `defaultRendererOptions`:
+  The options passed into the default renderer. Ignored if you use a custom renderer. Default `{}`
+- `inlineCustomElement`:
+  Specify `"tag-name"` or `["tag-name", { some: "attrs" }]` if you want to
+  render inline expressions to a custom element. Ignored if you provide a
+  custom renderer.
+- `inlineRenderer`:
+  Provide a custom inline math renderer. Accepts the source content, the
+  parsed markdown-it token, and the markdown-it instance. Default:
+  ```js
+  import mathup from "mathup";
+  function defaultInlineRenderer(src, token, md) {
+    return mathup(src, defaultRendererOptions).toString();
+  }
+  ```
+- `blockCustomElement`:
+  Specify `"tag-name"` or `["tag-name", { some: "attrs" }]` if you want to
+  render block expressions to a custom element. Ignored if you provide a
+  custom renderer.
+- `blockRenderer`:
+  Provide a custom block math renderer. Accepts the source content, the
+  parsed markdown-it token, and the markdown-it instance. Default:
+  ```js
+  import mathup from "mathup";
+  function defaultBlockRenderer(src, token, md) {
+    return mathup(src, {
+      ...defaultRendererOptions,
+      display: "block",
+    }).toString();
+  }
+  ```
+
 ## Examples
 
 Using comma as a decimal mark
 
-```javascript
+```js
 import markdownIt from "markdown-it";
 import markdownItMath from "markdown-it-math";
 
@@ -150,9 +189,30 @@ md.render("$40,2$");
 // <p><math><mn>40,2</mn></math></p>
 ```
 
+Render to a custom `<la-tex>` element
+
+```js
+import markdownIt from "markdown-it";
+import markdownItMath from "markdown-it-math";
+
+const md = markdownIt().use(markdownItMath, {
+  inlineCustomElement: "la-tex",
+  blockCustomElement: ["la-tex", { display: "block" }],
+});
+
+md.render(String.raw`
+$\sin(2\pi)$.
+$$
+\int_{0}^{\infty} E[X]
+$$
+`);
+// <p><la-tex>\sin(2\pi)</la-tex>.</p>
+// <la-tex display="block">\int_{0}^{\infty} E[X]</la-tex>
+```
+
 Using [TeXZilla][texzilla] as renderer
 
-```javascript
+```js
 import markdownIt from "markdown-it";
 import markdownItMath from "markdown-it-math";
 import texzilla from "texzilla";
@@ -166,9 +226,9 @@ md.render("$\\sin(2\\pi)$");
 // <p><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mo lspace="0em" rspace="0em">sin</mo><mo stretchy="false">(</mo><mn>2</mn><mi>π</mi><mo stretchy="false">)</mo></mrow><annotation encoding="TeX">\sin(2\pi)</annotation></semantics></math></p>
 ```
 
-Using LaTeX style delimiters
+Using LaTeX style delimiters:
 
-```javascript
+```js
 import markdownIt from "markdown-it";
 import markdownItMath from "markdown-it-math";
 

eslint.config.js

@@ -83,7 +83,14 @@ export default [
       "no-throw-literal": "error",
       "no-unmodified-loop-condition": "error",
       "no-unused-expressions": "error",
-      "no-unused-vars": ["error", { varsIgnorePattern: "^_" }],
+      "no-unused-vars": [
+        "error",
+        {
+          varsIgnorePattern: "^_",
+          argsIgnorePattern: "^_",
+          reportUsedIgnorePattern: true,
+        },
+      ],
       "no-useless-backreference": "error",
       "no-useless-concat": "error",
       "no-useless-return": "error",

index.js

@@ -1,5 +1,6 @@
 /**
  * @typedef {import("mathup").Options} MathupOptions
+ * @typedef {import("markdown-it").default} MarkdownIt
  * @typedef {import("markdown-it/lib/parser_block.mjs").RuleBlock} RuleBlock
  * @typedef {import("markdown-it/lib/parser_inline.mjs").RuleInline} RuleInline
  * @typedef {import("markdown-it/lib/rules_block/state_block.mjs").default} StateBlock
@@ -203,11 +204,12 @@ function createBlockMathRule(open, close) {
 
     const token = state.push("math_block", "math", 0);
     token.block = true;
-    token.content =
-      (firstLine && firstLine.trim() ? `${firstLine}\n` : "") +
-      state.getLines(startLine + 1, nextLine, len, true) +
-      (lastLine && lastLine.trim() ? lastLine : "");
 
+    const firstLineContent = firstLine && firstLine.trim() ? firstLine : "";
+    const contentLines = state.getLines(startLine + 1, nextLine, len, false);
+    const lastLineContent = lastLine && lastLine.trim() ? lastLine : "";
+
+    token.content = `${firstLineContent}${firstLineContent && (contentLines || lastLineContent) ? "\n" : ""}${contentLines}${contentLines && lastLineContent ? "\n" : ""}${lastLineContent}`;
     token.map = [startLine, state.line];
     token.markup = open;
 
@@ -216,56 +218,93 @@ function createBlockMathRule(open, close) {
 }
 
 /**
- * @param {MathupOptions} [options]
+ * @typedef {string | [tag: string, attrs?: Record<string, string>]} CustomElementOption
+ * @param {CustomElementOption} customElementOption
+ * @param {MarkdownIt} md
  * @returns {(src: string) => string}
  */
-function defaultInlineRenderer(options) {
+function createCustomElementRenderer(customElementOption, md) {
+  const { escapeHtml } = md.utils;
+
+  /** @type {string} */
+  let tag;
+  let attrs = "";
+  if (typeof customElementOption === "string") {
+    tag = customElementOption;
+  } else {
+    const [tagName, attrsObj = {}] = customElementOption;
+    tag = tagName;
+
+    for (const [key, value] of Object.entries(attrsObj)) {
+      attrs += ` ${key}="${escapeHtml(value)}"`;
+    }
+  }
+
+  return (src) => `<${tag}${attrs}>${escapeHtml(src)}</${tag}>`;
+}
+
+/**
+ * @param {MathupOptions} options
+ * @param {MarkdownIt} md
+ * @returns {(src: string) => string}
+ */
+function defaultInlineRenderer(options, md) {
   if (!mathup) {
-    return (src) => `<span class="math inline">${src}</span>`;
+    return createCustomElementRenderer(["span", { class: "math inline" }], md);
   }
 
   return (src) => mathup(src, options).toString();
 }
 
 /**
- * @param {MathupOptions} [options]
+ * @param {MathupOptions} options
+ * @param {MarkdownIt} md
  * @returns {(src: string) => string}
  */
-function defaultBlockRenderer(options = {}) {
+function defaultBlockRenderer(options, md) {
   if (!mathup) {
-    return (src) => `<div class="math block">${src}</div>`;
+    return createCustomElementRenderer(["div", { class: "math block" }], md);
   }
 
-  return (src) =>
-    mathup(src.trim(), { ...options, display: "block" }).toString();
+  return (src) => mathup(src, { ...options, display: "block" }).toString();
 }
 
 /**
- * @typedef {Record<string, string>} AttrsOption
+ * @callback Renderer
+ * @param {string} src - The source content
+ * @param {Token} token - The parsed markdown-it token
+ * @param {MarkdownIt} md - The markdown-it instance
  * @typedef {object} PluginOptions
- * @property {string} [inlineOpen]
- * @property {string} [inlineClose]
- * @property {(src: string, token: Token) => string} [inlineRenderer]
- * @property {string} [blockOpen]
- * @property {string} [blockClose]
- * @property {(src: string, token: Token) => string} [blockRenderer]
- * @property {import("mathup").Options} [defaultRendererOptions]
- * @typedef {import("markdown-it").PluginWithOptions<PluginOptions>} Plugin
+ * @property {string} [inlineOpen] - Inline math open delimiter.
+ * @property {string} [inlineClose] - Inline math close delimeter.
+ * @property {CustomElementOption} [inlineCustomElement] - If you want to render to a custom element.
+ * @property {MathupOptions} [defaultRendererOptions] - The options passed into the default renderer.
+ * @property {Renderer} [inlineRenderer] - Custom renderer for inline math. Default mathup.
+ * @property {string} [blockOpen] - Block math open delimter.
+ * @property {string} [blockClose] - Block math close delimter.
+ * @property {CustomElementOption} [blockCustomElement] - If you want to render to a custom element.
+ * @property {Renderer} [blockRenderer] - Custom renderer for block math. Default mathup with display = "block".
  */
 
-/**
- * @type {Plugin}
- */
+/** @type {import("markdown-it").PluginWithOptions<PluginOptions>} */
 export default function markdownItMath(
   md,
   {
     inlineOpen = "$",
     inlineClose = "$",
     blockOpen = "$$",
     blockClose = "$$",
-    defaultRendererOptions,
-    inlineRenderer = defaultInlineRenderer(defaultRendererOptions),
-    blockRenderer = defaultBlockRenderer(defaultRendererOptions),
+    defaultRendererOptions = {},
+
+    inlineCustomElement,
+    inlineRenderer = inlineCustomElement
+      ? createCustomElementRenderer(inlineCustomElement, md)
+      : defaultInlineRenderer(defaultRendererOptions, md),
+
+    blockCustomElement,
+    blockRenderer = blockCustomElement
+      ? createCustomElementRenderer(blockCustomElement, md)
+      : defaultBlockRenderer(defaultRendererOptions, md),
   } = {},
 ) {
   const inlineMathRule = createInlineMathRule(inlineOpen, inlineClose);
@@ -277,8 +316,8 @@ export default function markdownItMath(
   });
 
   md.renderer.rules.math_inline = (tokens, idx) =>
-    inlineRenderer(tokens[idx].content, tokens[idx]);
+    inlineRenderer(tokens[idx].content, tokens[idx], md);
 
   md.renderer.rules.math_block = (tokens, idx) =>
-    `${blockRenderer(tokens[idx].content, tokens[idx])}\n`;
+    `${blockRenderer(tokens[idx].content, tokens[idx], md)}\n`;
 }

test/test.js

@@ -1,6 +1,8 @@
-import { suite, test } from "node:test";
+import assert from "node:assert/strict";
+import { mock, suite, test } from "node:test";
 
 import markdownIt from "markdown-it";
+import Token from "markdown-it/lib/token.mjs";
 import texzilla from "texzilla";
 
 import markdownItMath from "../index.js";
@@ -286,4 +288,66 @@ $$`;
       t.assert.snapshot(md.render("$$\n\\sin(2\\pi)\n$$"));
     });
   });
+
+  suite("renderer", () => {
+    test("Custom renderer", () => {
+      const md = markdownIt().use(markdownItMath, {
+        inlineRenderer: (src) => `<inline-math>${src}</inline-math>`,
+        blockRenderer: (src) => `<block-math>${src}</block-math>`,
+      });
+
+      const res = md.render("$foo$\n$$\nbar\n$$");
+
+      assert.equal(
+        res,
+        "<p><inline-math>foo</inline-math></p>\n<block-math>bar</block-math>\n",
+      );
+    });
+
+    test("Correct arguments passed into renderer", () => {
+      const inlineRenderer = mock.fn((_src, _token, _md) => "");
+      const blockRenderer = mock.fn((_src, _token, _md) => "");
+      const md = markdownIt().use(markdownItMath, {
+        inlineRenderer,
+        blockRenderer,
+      });
+
+      md.render("$foo$\n$$\nbar\n$$");
+
+      {
+        const [firstCall] = inlineRenderer.mock.calls;
+        assert.ok(firstCall);
+
+        const args = firstCall.arguments;
+
+        assert.equal(args[0], "foo");
+        assert.equal(args[1] instanceof Token, true);
+        assert.equal(args[2], md);
+      }
+      {
+        const [firstCall] = blockRenderer.mock.calls;
+        assert.ok(firstCall);
+
+        const args = firstCall.arguments;
+
+        assert.equal(args[0], "bar");
+        assert.equal(args[1] instanceof Token, true);
+        assert.equal(args[2], md);
+      }
+    });
+
+    test("customElement", () => {
+      const md = markdownIt().use(markdownItMath, {
+        inlineCustomElement: "my-el",
+        blockCustomElement: ["my-el", { some: "attr" }],
+      });
+
+      const res = md.render("$foo$\n$$\nbar\n$$");
+
+      assert.equal(
+        res,
+        '<p><my-el>foo</my-el></p>\n<my-el some="attr">bar</my-el>\n',
+      );
+    });
+  });
 });

test/test.js.snapshot

@@ -27,11 +27,11 @@ exports[`Block Math > Can span multiple lines 1`] = `
 `;
 
 exports[`Block Math > Multiline block math 1`] = `
-"<math display=\\"block\\"><mn>1</mn><mspace depth=\\"1em\\" /><mo>+</mo><mn>1</mn><mspace depth=\\"2em\\" /><mo>=</mo><mn>2</mn></math>\\n"
+"<math display=\\"block\\"><mspace depth=\\"1em\\" /><mspace width=\\"0.35ex\\" /><mn>1</mn><mspace depth=\\"1em\\" /><mo>+</mo><mn>1</mn><mspace depth=\\"2em\\" /><mo>=</mo><mn>2</mn><mspace depth=\\"1em\\" /></math>\\n"
 `;
 
 exports[`Block Math > Multiline math that might look like an unordered list 1`] = `
-"<math display=\\"block\\"><mn>1</mn><mspace depth=\\"2em\\" /><mo>+</mo><mn>1</mn><mspace depth=\\"1em\\" /><mo>+</mo><mn>1</mn><mspace depth=\\"2em\\" /><mo>=</mo><mn>3</mn></math>\\n"
+"<math display=\\"block\\"><mspace width=\\"0.35ex\\" /><mn>1</mn><mspace depth=\\"2em\\" /><mo>+</mo><mn>1</mn><mspace depth=\\"1em\\" /><mo>+</mo><mn>1</mn><mspace depth=\\"2em\\" /><mo>=</mo><mn>3</mn></math>\\n"
 `;
 
 exports[`Block Math > Paragraph breaks around delims are not required 1`] = `
@@ -111,7 +111,7 @@ exports[`Options > Thick dollar delims 1`] = `
 `;
 
 exports[`Options > Use TexZilla as renderer > block 1`] = `
-"<math display=\\"block\\" xmlns=\\"http://www.w3.org/1998/Math/MathML\\"><semantics><mrow><mo lspace=\\"0em\\" rspace=\\"0em\\">sin</mo><mo stretchy=\\"false\\">(</mo><mn>2</mn><mi>π</mi><mo stretchy=\\"false\\">)</mo></mrow><annotation encoding=\\"TeX\\">\\\\sin(2\\\\pi)\\n</annotation></semantics></math>\\n"
+"<math display=\\"block\\" xmlns=\\"http://www.w3.org/1998/Math/MathML\\"><semantics><mrow><mo lspace=\\"0em\\" rspace=\\"0em\\">sin</mo><mo stretchy=\\"false\\">(</mo><mn>2</mn><mi>π</mi><mo stretchy=\\"false\\">)</mo></mrow><annotation encoding=\\"TeX\\">\\\\sin(2\\\\pi)</annotation></semantics></math>\\n"
 `;
 
 exports[`Options > Use TexZilla as renderer > inline 1`] = `