0
# remark-math
1
2
remark-math is a unified remark plugin that extends markdown parsing and serialization to support mathematical expressions using LaTeX-style syntax with dollar delimiters ($..$ for inline and $$...$$ for block math). It integrates seamlessly with the unified ecosystem, particularly remark-rehype for HTML transformation, converting math nodes into properly structured HTML elements with appropriate CSS classes for downstream rendering by KaTeX, MathJax, or other math rendering engines.
3
4
## Package Information
5
6
- **Package Name**: remark-math
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Module)
9
- **Installation**: `npm install remark-math`
10
11
## Core Imports
12
13
```javascript
14
import remarkMath from 'remark-math';
15
```
16
17
For TypeScript projects:
18
19
```typescript
20
import remarkMath from 'remark-math';
21
// Note: Options type is available via JSDoc but not as named export
22
```
23
24
For CommonJS environments (though package is ES Module only):
25
26
```javascript
27
const remarkMath = require('remark-math').default;
28
```
29
30
## Basic Usage
31
32
```javascript
33
import rehypeKatex from 'rehype-katex';
34
import rehypeStringify from 'rehype-stringify';
35
import remarkMath from 'remark-math';
36
import remarkParse from 'remark-parse';
37
import remarkRehype from 'remark-rehype';
38
import {unified} from 'unified';
39
40
const processor = unified()
41
.use(remarkParse)
42
.use(remarkMath)
43
.use(remarkRehype)
44
.use(rehypeKatex)
45
.use(rehypeStringify);
46
47
const markdown = `
48
Lift ($C_L$) can be determined by the following equation:
49
50
$$
51
L = \\frac{1}{2} \\rho v^2 S C_L
52
$$
53
`;
54
55
const result = await processor.process(markdown);
56
console.log(String(result));
57
```
58
59
## Architecture
60
61
remark-math follows the unified plugin architecture:
62
63
- **Micromark Extension**: Uses `micromark-extension-math` for low-level parsing
64
- **MDAST Utilities**: Uses `mdast-util-math` for AST transformation
65
- **Node Types**: Creates `inlineMath` and `math` nodes in the MDAST syntax tree
66
- **HTML Integration**: Adds hast properties for remark-rehype conversion to HTML
67
- **Lazy Evaluation**: Math expressions are parsed but not rendered until HTML conversion
68
69
## Capabilities
70
71
### Math Plugin Function
72
73
The main plugin function that adds math support to unified processors.
74
75
```javascript { .api }
76
/**
77
* Add support for math expressions in markdown
78
* @param {Options | null | undefined} [options] - Configuration options
79
* @returns {undefined} - Returns nothing, modifies processor in place
80
*/
81
function remarkMath(options?: Options): undefined;
82
```
83
84
**Usage Example:**
85
86
```javascript
87
import remarkMath from 'remark-math';
88
import {unified} from 'unified';
89
import remarkParse from 'remark-parse';
90
91
const processor = unified()
92
.use(remarkParse)
93
.use(remarkMath, { singleDollarTextMath: false });
94
```
95
96
### Configuration Options
97
98
```javascript { .api }
99
interface Options {
100
/**
101
* Whether to support text math (inline) with a single dollar
102
* Single dollars work in Pandoc but often interfere with normal dollars in text
103
* @default true
104
*/
105
singleDollarTextMath?: boolean;
106
}
107
```
108
109
**Configuration Examples:**
110
111
```javascript
112
// Default behavior - single dollar inline math enabled
113
.use(remarkMath)
114
115
// Disable single dollar inline math (only $$ works for inline)
116
.use(remarkMath, { singleDollarTextMath: false })
117
```
118
119
## Syntax Support
120
121
### Inline Math
122
123
- **Single Dollar**: `$expression$` (configurable, enabled by default)
124
- **Double Dollar**: `$$expression$$` (always supported)
125
126
```markdown
127
The formula $E = mc^2$ shows mass-energy equivalence.
128
```
129
130
### Block Math
131
132
- **Fenced Format**: `$$\nexpression\n$$` (on separate lines)
133
- **Indented Support**: Up to 3 spaces of indentation allowed
134
135
```markdown
136
$$
137
\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}
138
$$
139
```
140
141
### Escape Sequences
142
143
- **Escaped Dollars**: `\\$` prevents math parsing
144
- **Within Code**: Dollar signs inside `code` blocks are ignored
145
146
```markdown
147
The price is \\$5.99 (not math)
148
`$variable` in code (not math)
149
```
150
151
## HTML Output
152
153
When used with remark-rehype, math nodes are converted to HTML with semantic CSS classes:
154
155
### Inline Math HTML
156
157
```html
158
<code class="language-math math-inline">E = mc^2</code>
159
```
160
161
### Block Math HTML
162
163
```html
164
<pre><code class="language-math math-display">\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}</code></pre>
165
```
166
167
These HTML structures are designed to work with:
168
- **KaTeX**: For client-side math rendering
169
- **MathJax**: For server-side or client-side rendering
170
- **Custom renderers**: Any system that processes `.language-math` classes
171
172
## Error Handling
173
174
remark-math handles malformed math gracefully:
175
176
- **Unclosed delimiters**: Treated as regular text
177
- **Empty expressions**: `$$` with no content ignored
178
- **Nested delimiters**: Inner delimiters escaped automatically
179
- **Invalid LaTeX**: Passed through to renderer (KaTeX/MathJax handles errors)
180
181
## Syntax Tree Nodes
182
183
The plugin creates two new MDAST node types:
184
185
### InlineMath Node
186
187
```javascript { .api }
188
interface InlineMath {
189
type: 'inlineMath';
190
value: string;
191
data?: {
192
hName: 'code';
193
hProperties: {
194
className: ['language-math', 'math-inline'];
195
};
196
hChildren: Array<{ type: 'text'; value: string }>;
197
};
198
}
199
```
200
201
### Math Node (Block)
202
203
```javascript { .api }
204
interface Math {
205
type: 'math';
206
value: string;
207
meta: null;
208
data?: {
209
hName: 'pre';
210
hChildren: Array<{
211
type: 'element';
212
tagName: 'code';
213
properties: {
214
className: ['language-math', 'math-display'];
215
};
216
children: Array<{ type: 'text'; value: string }>;
217
}>;
218
};
219
}
220
```