fix(publisher): render math server-side via KaTeX

TipTap's math extension emits empty inline/block-math placeholders during
generateHTML (rendering is a view-only step). Add a math transformer that
fills those placeholders with static KaTeX HTML so formulas appear in the
published article. Pin the KaTeX CSS CDN version to the server-side katex.

Co-authored-by: Cursor <cursoragent@cursor.com>

backend/package.json

@@ -37,6 +37,7 @@
     "ai": "^6.0.158",
     "dotenv": "^17.4.1",
     "express": "^4.21.0",
+    "katex": "^0.16.45",
     "linkedom": "^0.18.12",
     "lowlight": "^3.3.0",
     "multer": "^2.1.1",

backend/src/publisher/html-renderer.ts

@@ -133,9 +133,9 @@ export async function renderArticleHTML(
   <meta name="twitter:description" content="${safeDesc}">
   ${meta.ogImage ? `<meta name="twitter:image" content="${escapeHtml(meta.ogImage)}">` : ""}
 
-  <!-- KaTeX CSS -->
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css"
-        integrity="sha384-zh0CIslj+VczCZtlzBcjt5ppRcsAmDnRem7ESsYwWwg3m/OaJ2l4x7YBZl9Kxxib"
+  <!-- KaTeX CSS (version pinned to the katex used server-side in the math transformer) -->
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.45/dist/katex.min.css"
+        integrity="sha384-exTa2AZBTSYZY6XrZeHr+SthVy0uzRopdM/I9+nd/JMLcTcklL0+cMoJGes1iO1i"
         crossorigin="anonymous">
 
   <!-- Code blocks are pre-highlighted at publish time with Shiki (dual-theme

backend/src/publisher/transformers/index.ts

@@ -18,7 +18,10 @@
  *                      remote URL into a standard `<figure><iframe src=...>`.
  *  8. HfUser         — independent; converts atomic placeholder divs into
  *                      Hugging Face user profile cards.
- *  9. Footnote       — runs last so collected texts include those inside every
+ *  9. Math           — renders the empty `data-type="inline-math"/"block-math"`
+ *                      placeholders into static KaTeX HTML. Runs before
+ *                      Footnote so math inside a footnote is captured rendered.
+ * 10. Footnote       — runs last so collected texts include those inside every
  *                      other transformed block (tables, callouts, accordions...).
  */
 import type { Transformer } from "./types.js";
@@ -30,6 +33,7 @@ import { highlightCodeTransformer } from "./highlight-code.js";
 import { htmlEmbedTransformer } from "./html-embed.js";
 import { iframeEmbedTransformer } from "./iframe-embed.js";
 import { hfUserTransformer } from "./hf-user.js";
+import { mathTransformer } from "./math.js";
 import { footnoteTransformer } from "./footnote.js";
 
 export const transformers: Transformer[] = [
@@ -41,6 +45,7 @@ export const transformers: Transformer[] = [
   htmlEmbedTransformer,
   iframeEmbedTransformer,
   hfUserTransformer,
+  mathTransformer,
   footnoteTransformer,
 ];
 

backend/src/publisher/transformers/math.ts

@@ -0,0 +1,45 @@
+import type { Transformer } from "./types.js";
+import katex from "katex";
+
+/**
+ * Renders math placeholders into static KaTeX HTML.
+ *
+ * `@tiptap/extension-mathematics` only produces empty placeholders in its
+ * static `renderHTML` (the actual KaTeX rendering lives in a client-side
+ * NodeView):
+ *   - inline: `<span data-type="inline-math" data-latex="...">`
+ *   - block:  `<div data-type="block-math" data-latex="...">`
+ *
+ * `generateHTML()` (used by the publisher) never runs the NodeView, so without
+ * this transformer the published page would contain empty, invisible math
+ * nodes. We render the `data-latex` server-side with `katex.renderToString`
+ * so the published article is fully static (the page already loads the KaTeX
+ * stylesheet; no client-side JS is required).
+ */
+const SELECTOR = '[data-type="inline-math"], [data-type="block-math"]';
+
+export const mathTransformer: Transformer = {
+  name: "math",
+  apply(document) {
+    for (const el of [...document.querySelectorAll(SELECTOR)]) {
+      const latex = el.getAttribute("data-latex") || "";
+      const displayMode = el.getAttribute("data-type") === "block-math";
+
+      if (!latex.trim()) {
+        // Nothing to render: drop the empty placeholder so it leaves no
+        // invisible gap in the published article.
+        el.remove();
+        continue;
+      }
+
+      // `throwOnError: false` makes KaTeX emit a red error node instead of
+      // throwing, mirroring the editor's behaviour and keeping publish
+      // resilient to a single malformed expression.
+      el.innerHTML = katex.renderToString(latex, {
+        displayMode,
+        throwOnError: false,
+        output: "htmlAndMathml",
+      });
+    }
+  },
+};

backend/tests/__snapshots__/html-renderer-snapshot.test.ts.snap

@@ -61,9 +61,9 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
   <meta name="twitter:description" content="A test article">
   
 
-  <!-- KaTeX CSS -->
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css"
-        integrity="sha384-zh0CIslj+VczCZtlzBcjt5ppRcsAmDnRem7ESsYwWwg3m/OaJ2l4x7YBZl9Kxxib"
+  <!-- KaTeX CSS (version pinned to the katex used server-side in the math transformer) -->
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.45/dist/katex.min.css"
+        integrity="sha384-exTa2AZBTSYZY6XrZeHr+SthVy0uzRopdM/I9+nd/JMLcTcklL0+cMoJGes1iO1i"
         crossorigin="anonymous">
 
   <!-- Code blocks are pre-highlighted at publish time with Shiki (dual-theme

backend/tests/math-transformer.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Math transformer tests.
+ *
+ * `@tiptap/extension-mathematics` only emits empty placeholders in its static
+ * `renderHTML`, so the publisher must render them server-side. These tests
+ * exercise the full publish path (renderArticleHTML) to guarantee the
+ * published article contains rendered KaTeX, never raw LaTeX or empty nodes.
+ */
+import { describe, it, expect } from "vitest";
+import { renderArticleHTML, type PublishMeta } from "../src/publisher/html-renderer.js";
+import type { PublishCSS } from "../src/publisher/index.js";
+
+const EMPTY_CSS: PublishCSS = {
+  variables: "",
+  reset: "",
+  base: "",
+  layout: "",
+  print: "",
+  editorTokens: "",
+  article: "",
+  components: "",
+  publisher: "",
+};
+
+const META: PublishMeta = {
+  title: "Math Article",
+  description: "A test article with math",
+  authors: [{ name: "Alice", affiliationIndices: [1], affiliationNames: ["MIT"] }],
+  affiliations: [{ name: "MIT" }],
+  date: "2025-01-01",
+};
+
+const doc = (content: any[]) => ({ type: "doc", content });
+
+describe("math transformer", () => {
+  it("renders an inline math placeholder into static KaTeX", async () => {
+    const json = doc([
+      {
+        type: "paragraph",
+        content: [
+          { type: "text", text: "Energy is " },
+          { type: "inlineMath", attrs: { latex: "E = mc^2" } },
+          { type: "text", text: " famously." },
+        ],
+      },
+    ]);
+    const html = await renderArticleHTML(json, META, EMPTY_CSS);
+
+    expect(html).toContain('class="katex"');
+    // KaTeX keeps the source in a MathML annotation, which is expected.
+    expect(html).toContain("E = mc^2");
+  });
+
+  it("renders a block math placeholder in display mode", async () => {
+    const json = doc([{ type: "blockMath", attrs: { latex: "\\int_0^1 x\\,dx = \\frac{1}{2}" } }]);
+    const html = await renderArticleHTML(json, META, EMPTY_CSS);
+
+    expect(html).toContain('class="katex"');
+    expect(html).toContain("katex-display");
+  });
+
+  it("does not throw on malformed LaTeX (renders an error node instead)", async () => {
+    const json = doc([
+      { type: "paragraph", content: [{ type: "inlineMath", attrs: { latex: "\\frac{" } }] },
+    ]);
+    const html = await renderArticleHTML(json, META, EMPTY_CSS);
+
+    expect(html).toContain("katex");
+  });
+
+  it("drops empty math placeholders so they leave no invisible gap", async () => {
+    const json = doc([
+      { type: "paragraph", content: [{ type: "inlineMath", attrs: { latex: "" } }] },
+    ]);
+    const html = await renderArticleHTML(json, META, EMPTY_CSS);
+
+    expect(html).not.toContain('data-type="inline-math"');
+  });
+});