[English](#en) | [中文](#zh)
---
[](https://www.npmjs.com/package/@webc.site/math)
[](https://x.com/iwebcsite)
[](https://webc-site.bsky.social)
# @webc.site/math : The world's smallest and fastest web Markdown formula renderer
- [1. Features](#1-features)
- [2. Usage](#2-usage)
- [Compilation Examples](#compilation-examples)
- [Render TeX Formulas Directly](#render-tex-formulas-directly)
- [Replace Formulas in Markdown Text](#replace-formulas-in-markdown-text)
- [Font and CSS Configuration](#font-and-css-configuration)
- [Importing the Math Font](#importing-the-math-font)
- [Option 1: Via CDN (Recommended)](#option-1-via-cdn-recommended)
- [Option 2: Self-hosting Font Files](#option-2-self-hosting-font-files)
- [CSS Styling Configuration](#css-styling-configuration)
- [Font Family Fallback Chain](#font-family-fallback-chain)
- [Block Formula Layout Optimization](#block-formula-layout-optimization)
- [3. Plugins](#3-plugins)
- [3.1 markdown-it](#31-markdown-it)
- [3.2 marked](#32-marked)
- [3.3 remark](#33-remark)
- [4. Design](#4-design)
- [5. Tech Stack](#5-tech-stack)
- [6. Code Structure](#6-code-structure)
- [7. Historical Background](#7-historical-background)
## 1. Features
This project compiles LaTeX math formulas into browser-native MathML Core markup. Through compile-time conversion, it bypasses client-side layout engines to achieve zero-overhead formula rendering.
Key Features:
- **High Performance**: Compiles TeX formulas directly to native MathML. Processing speed exceeds 300,000 operations per second, 3 times faster than KaTeX and 40 times faster than MathJax.
- **Lightweight**: Core package size is 8.95 KB (4.62 KB gzipped) with zero external dependencies.
- **Zero Runtime Overhead**: Relies entirely on the browser's native engine for layout, eliminating client-side JavaScript formatting libraries.
- **Robust Fault Tolerance**: Catches syntax errors (such as unclosed braces) and reverts to raw TeX string output to prevent application crashes.
- **High Compatibility**: Generates standard MathML tags suitable for Server-Side Rendering (SSR), Static Site Generation (SSG), and Client-Side Rendering (CSR).
## 2. Usage
### Compilation Examples
#### Render TeX Formulas Directly
```javascript
import mathml from "@webc.site/math";
// Second parameter set to true renders block style
const html = mathml("e^{i\\pi} + 1 = 0", true);
```
#### Replace Formulas in Markdown Text
```javascript
import mdMath from "@webc.site/math/md.js";
import compile from "@webc.site/math";
const html = mdMath("Euler's identity: $$e^{i\\pi} + 1 = 0$$", compile);
```
### Font and CSS Configuration
MathML layout relies on OpenType Math fonts containing dedicated mathematical metrics (the `MATH` table) to correctly handle radical scaling, delimiter stretching (e.g., parentheses, braces), fraction line thickness, and sub/superscript alignments.
The classic TeX math font **Latin Modern Math** (derived from Donald Knuth's Computer Modern family) is recommended.
#### Importing the Math Font
##### Option 1: Via CDN (Recommended)
Import the Latin Modern Math font stylesheet from the `18s` font package (which registers the font family name as `m`):
In CSS:
```css
@import url("https://registry.npmmirror.com/18s/0.2.24/files/m.css");
```
Or in HTML `
`:
```html
```
To include the body text font (`t`) and monospace code font (`c`) along with the math font, import the complete stylesheet:
```html
```
##### Option 2: Self-hosting Font Files
Download the Latin Modern Math WOFF2 font file and declare `@font-face`:
```css
@font-face {
font-family: "Latin Modern Math";
src: url("/fonts/latinmodern-math.woff2") format("woff2");
font-style: normal;
font-display: swap;
}
```
#### CSS Styling Configuration
##### Font Family Fallback Chain
Declare the font stack and inherit text color for `