tessl/npm-katex

Fast math typesetting for the web.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Auto-Rendering

Name: tessl/npm-katex
Author: tessl

Automatic math detection and rendering within HTML elements, supporting configurable delimiters and preprocessing for seamless integration into web pages.

Import

import renderMathInElement from "katex/contrib/auto-render";

For CommonJS:

const renderMathInElement = require("katex/contrib/auto-render");

Capabilities

Render Math in Element

Automatically finds and renders math expressions within an HTML element using configurable delimiters.

/**
 * Automatically renders math within an HTML element
 * @param element - DOM element to search for math expressions
 * @param options - Auto-rendering configuration options
 */
function renderMathInElement(element: Element, options?: AutoRenderOptions): void;

interface AutoRenderOptions extends KatexOptions {
  /** Math delimiter configurations */
  delimiters?: DelimiterConfig[];
  /** HTML tags to ignore during processing */
  ignoredTags?: string[];
  /** CSS classes to ignore during processing */
  ignoredClasses?: string[];
  /** Error callback function */
  errorCallback?: (msg: string, err: Error) => void;
  /** Preprocessing function for math strings */
  preProcess?: (math: string) => string;
}

interface DelimiterConfig {
  /** Opening delimiter */
  left: string;
  /** Closing delimiter */
  right: string;
  /** Whether to render in display mode */
  display: boolean;
}

Usage Examples:

import katex from "katex";
import renderMathInElement from "katex/contrib/auto-render";

// Basic auto-rendering
const container = document.getElementById("content");
renderMathInElement(container);

// Custom configuration
renderMathInElement(container, {
  delimiters: [
    { left: "$$", right: "$$", display: true },
    { left: "$", right: "$", display: false },
    { left: "\\(", right: "\\)", display: false },
    { left: "\\[", right: "\\]", display: true }
  ],
  ignoredTags: ["script", "noscript", "style", "textarea", "pre", "code"],
  ignoredClasses: ["no-math", "skip-math"],
  throwOnError: false
});

// With preprocessing
renderMathInElement(container, {
  preProcess: (math) => {
    // Replace custom syntax
    return math.replace(/\[vec\]/g, "\\vec");
  },
  errorCallback: (msg, err) => {
    console.warn("Math rendering error:", msg, err);
  }
});

Default Delimiters

The default delimiter configuration includes:

const defaultDelimiters: DelimiterConfig[] = [
  { left: "$$", right: "$$", display: true },
  { left: "\\(", right: "\\)", display: false },
  { left: "\\[", right: "\\]", display: true },
  
  // AMS environments
  { left: "\\begin{equation}", right: "\\end{equation}", display: true },
  { left: "\\begin{align}", right: "\\end{align}", display: true },
  { left: "\\begin{alignat}", right: "\\end{alignat}", display: true },
  { left: "\\begin{gather}", right: "\\end{gather}", display: true },
  { left: "\\begin{CD}", right: "\\end{CD}", display: true }
];

Content Processing

Auto-render processes text nodes and handles:

Delimiter Detection: Finds math expressions using configured delimiters
Tag Filtering: Skips specified HTML tags (default: script, noscript, style, textarea, pre, code, option)
Class Filtering: Skips elements with specified CSS classes
Text Node Concatenation: Handles large text nodes split by browsers
Error Handling: Continues processing on errors with configurable callbacks

HTML Example:

<div id="content">
  <p>The quadratic formula is \\(x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}\\).</p>
  <p>Display math: $$\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}$$</p>
  <code class="no-math">\\(this will be ignored\\)</code>
</div>

<script>
import renderMathInElement from "katex/contrib/auto-render";
renderMathInElement(document.getElementById("content"), {
  ignoredClasses: ["no-math"]
});
</script>

Integration with Frameworks

Auto-render works with modern frameworks:

// React useEffect
useEffect(() => {
  renderMathInElement(containerRef.current);
}, [content]);

// Vue mounted hook
mounted() {
  renderMathInElement(this.$el);
}

// Angular ngAfterViewInit
ngAfterViewInit() {
  renderMathInElement(this.elementRef.nativeElement);
}