Render LaTeX math in Markdown Embed without a client-side flash

[kof]

Problem

Authors publishing mathematics, physics, and other technical content cannot render LaTeX equations through Markdown Embed without adding a separate client-side KaTeX or MathJax integration.

That workaround adds JavaScript, renders formulas after the page has loaded, and can produce a visible flash or layout shift. It also makes Content Engine Markdown behave differently from the Markdown editor preview and the server-rendered page.

Markdown Embed already parses Markdown with micromark, including GitHub Flavored Markdown and YAML frontmatter. The micromark ecosystem provides math syntax and KaTeX-backed HTML serialization, but supporting it safely and efficiently is broader than enabling one parser extension.

Desired outcome

Let authors write inline and display math in Markdown and have Webstudio render accessible equations in the Builder preview, canvas, and initial published HTML.

A visitor should receive rendered equations in the server response without waiting for a client-side auto-render pass. The feature should work when Markdown is entered directly or bound dynamically from Content Engine data.

Product scope

• Support an explicitly documented Markdown math syntax for inline and display equations.
• Render the same equation semantics in the Markdown asset preview, Markdown Embed on the canvas, published SSR routes, and static exports.
• Support Markdown bodies loaded dynamically through Content Engine resources.
• Produce accessible output with an appropriate text, LaTeX, or MathML representation.
• Provide predictable handling for invalid or unsupported expressions.
• Make the required presentation styles available without requiring every author to configure an external script.
• Document syntax, limitations, styling, accessibility, and performance behavior.

Constraints

• Equations must be present in the initial published HTML; a client-only rendering pass is not sufficient.
• Raw Markdown HTML must not gain new executable-markup or arbitrary-style capabilities as a side effect of allowing generated math markup.
• Keep KaTeX or another TeX renderer in an untrusted mode. User-authored Markdown must not enable arbitrary URLs, commands, HTML, scripts, or unsafe extensions.
• Preserve existing GFM, frontmatter, heading IDs, embeds, image optimization, URL sanitization, and Markdown styling behavior.
• Do not load remote runtime scripts, styles, or fonts by default.
• Invalid math must not abort rendering of the complete Markdown document or published page.
• Builder preview and published rendering must not silently use different parsers, options, macro sets, or sanitization rules.
• Avoid adding a large math runtime to every site or every page that does not render math.

Known tradeoffs

Rendering format

micromark-extension-math can serialize through KaTeX. KaTeX's default output contains visual HTML plus MathML for accessibility. That gives consistent typography, but requires KaTeX CSS, font assets, generated inline layout styles, and a carefully isolated sanitizer path.

MathML-only output avoids KaTeX's visual HTML and font package, but delegates typography and layout to native browser MathML support. Browser consistency and the supported TeX subset need to be evaluated against real technical articles.

Server rendering versus client payload

Using the math extension in the current shared Markdown renderer would put equations into SSR output and remove the visible flash. However, published pages hydrate the same Markdown component, so a direct integration also adds the KaTeX renderer to the client bundle and may parse the same Markdown again during hydration.

A directional local bundle measurement put the additional math/KaTeX JavaScript at roughly 79 KB gzip before CSS and fonts. If the product requirement is no client-side math runtime, the renderer needs a server-only or precompiled boundary rather than only a parser extension.

Sanitization

The current sanitizer removes MathML elements and KaTeX's generated layout attributes. Adding MathML tags alone is insufficient for the default KaTeX output.

Globally allowing style or every KaTeX attribute would widen what raw embedded HTML can express. Generated, trusted renderer output needs to remain distinguishable from untrusted Markdown HTML, or the selected output format must use a narrow explicit tag and attribute grammar.

Syntax compatibility

Single-dollar inline math is familiar in Pandoc and many math tools, but can reinterpret existing prose containing currency such as $10. Disabling single-dollar math avoids that ambiguity but makes authoring less familiar. The accepted dialect and escaping rules must be deliberate and documented.

Styling and assets

KaTeX HTML requires its stylesheet and several font families. Shipping all assets gives stable results but increases output and asset complexity. Native MathML is lighter but offers a different styling surface. In either case, authors need useful control over inline alignment, display spacing, overflow, font size, and color.

Acceptance criteria

• Inline and display equations use one documented syntax and render in the Markdown asset preview and Markdown Embed canvas.
• The initial HTML response for a published page contains the rendered equation; no client-side auto-render flash is visible.
• Content Engine Markdown bound to Markdown Embed renders with the same behavior as literal Markdown.
• Published SSR and static export produce equivalent semantic math output.
• The output has an accessible representation and does not expose duplicate equation text to assistive technology.
• Invalid or unsupported expressions produce a safe, understandable fallback without breaking the surrounding document.
• Untrusted TeX cannot enable arbitrary HTML, scripts, URLs, unsafe protocols, or commands.
• Supporting generated math markup does not allow equivalent tags, attributes, or inline styles through raw Markdown HTML unless they are independently safe and intended.
• Pages without math do not load math-specific CSS, fonts, or runtime code.
• The client JavaScript, CSS, font, HTML-size, SSR-time, and hydration-time impact is measured, and the accepted budgets and server/client boundary are recorded before implementation.
• Existing regression coverage for GFM, frontmatter, heading IDs, embeds, sanitization, and optimized images continues to pass.
• Regression coverage includes inline math, display math, complex expressions, invalid input, attempted unsafe commands, raw-HTML sanitizer bypasses, SSR output, hydration parity, and static export.
• User documentation explains the supported syntax, escaping, limitations, styling, accessibility, and performance behavior.

Product questions

• Is the product promise “no rendering flash,” or must published pages contain no client-side math renderer at all?
• Should the first version use native MathML, KaTeX HTML plus MathML, or another server-rendered format?
• Should single-dollar inline math be enabled, or should the syntax avoid conflicts with currency?
• Should fenced code blocks with a math language be supported in addition to dollar delimiters?
• Which TeX/LaTeX command subset, macro configuration, and strictness policy should Webstudio support?
• Should custom macros be supported? If so, are they project-level settings, frontmatter, or intentionally out of scope?
• What should visitors see when an expression is invalid: escaped source, an error marker, or the last valid output?
• Should detailed parse diagnostics appear only in Builder while published pages show a quieter fallback?
• What accessibility and copy/paste behavior should be guaranteed?
• Should equations expose selectable Markdown Embed descendants for inline math, display math, and error states?
• Which styling controls should work through Webstudio, and which renderer styles must remain internal?
• How should math CSS and fonts be delivered and deduplicated across pages while remaining self-hosted?
• Can the existing hydrated Markdown component meet the payload goal, or does math require server-only/precompiled Markdown HTML?
• Should support apply only to Markdown Embed, or to every Webstudio Markdown surface that uses the shared renderer?
• Is this capability independent of future compiled Markdown/MDX work, or should it share the artifact and server-rendering direction discussed in Support MDX-authored pages with portable Webstudio fragments #5920?
• What compatibility behavior is required for existing Markdown containing dollar signs that changes meaning after math syntax is enabled?

Related

• Support Markdown as Content Embed #3485 introduced Markdown as an embed capability.
• Support MDX-authored pages with portable Webstudio fragments #5920 discusses compiled Markdown/MDX artifacts and a server-rendered content path.
• micromark math extension: https://github.com/micromark/micromark-extension-math
• KaTeX server-side rendering: https://katex.org/docs/api.html