Skip to content

Commit dd3075a

Browse files
wooormwooorm
committed
Refactor docs
1 parent f173346 commit dd3075a

File tree

9 files changed

+521
-367
lines changed

9 files changed

+521
-367
lines changed

‎packages/rehype-katex/lib/index.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
*/
99

1010
/**
11-
* @typedef {Omit<KatexOptions, 'throwOnError'>} Options
11+
* @typedef {Omit<KatexOptions, 'displayMode' | 'throwOnError'>} Options
1212
*/
1313

1414
import {fromHtmlIsomorphic} from 'hast-util-from-html-isomorphic'
@@ -22,8 +22,8 @@ const emptyOptions = {}
2222
const emptyClasses = []
2323

2424
/**
25-
* Plugin to transform `<span class=math-inline>` and `<div class=math-display>`
26-
* with KaTeX.
25+
* Render elements with a `language-math` (or `math-display`, `math-inline`)
26+
* class with KaTeX.
2727
*
2828
* @param {Readonly<Options> | null | undefined} [options]
2929
* Configuration (optional).

‎packages/rehype-katex/readme.md

Lines changed: 138 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@
88
[![Backers][backers-badge]][collective]
99
[![Chat][chat-badge]][chat]
1010

11-
**[rehype][]** plugin to render `<span class=math-inline>` and
12-
`<div class=math-display>` with [KaTeX][].
11+
**[rehype][]** plugin to render elements with a `language-math` class with
12+
[KaTeX][].
1313

1414
## Contents
1515

@@ -19,8 +19,10 @@
1919
* [Use](#use)
2020
* [API](#api)
2121
* [`unified().use(rehypeKatex[, options])`](#unifieduserehypekatex-options)
22+
* [`Options`](#options)
23+
* [Markdown](#markdown)
24+
* [HTML](#html)
2225
* [CSS](#css)
23-
* [Syntax tree](#syntax-tree)
2426
* [Types](#types)
2527
* [Compatibility](#compatibility)
2628
* [Security](#security)
@@ -31,27 +33,21 @@
3133
## What is this?
3234

3335
This package is a [unified][] ([rehype][]) plugin to render math.
34-
You can combine it with [`remark-math`][remark-math] for math in markdown or add
35-
`math-inline` and `math-display` classes in HTML.
36-
37-
**unified** is a project that transforms content with abstract syntax trees
38-
(ASTs).
39-
**rehype** adds support for HTML to unified.
40-
**hast** is the HTML AST that rehype uses.
41-
This is a rehype plugin that transforms hast.
36+
You can add classes to HTML elements, use fenced code in markdown, or combine
37+
with [`remark-math`][remark-math] for a `$C$` syntax extension.
4238

4339
## When should I use this?
4440

4541
This project is useful as it renders math with KaTeX at compile time, which
4642
means that there is no client side JavaScript needed.
4743

48-
A different plugin, [`rehype-mathjax`][rehype-mathjax], is similar but uses
49-
[MathJax][] instead.
44+
A different plugin, [`rehype-mathjax`][rehype-mathjax], does the same but with
45+
[MathJax][].
5046

5147
## Install
5248

53-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
54-
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
49+
This package is [ESM only][esm].
50+
In Node.js (version 16+), install with [npm][]:
5551

5652
```sh
5753
npm install rehype-katex
@@ -73,76 +69,117 @@ In browsers with [`esm.sh`][esmsh]:
7369

7470
## Use
7571

76-
Say we have the following file `example.html`:
72+
Say our document `input.html` contains:
7773

7874
```html
7975
<p>
80-
Lift(<code class="language-math math-inline">L</span>) can be determined by Lift Coefficient
81-
(<code class="language-math math-inline">C_L</span>) like the following equation.
76+
Lift(<code class="language-math">L</code>) can be determined by Lift Coefficient
77+
(<code class="language-math">C_L</code>) like the following equation.
8278
</p>
83-
84-
<div class="math math-display">
79+
<pre><code class="language-math">
8580
L = \frac{1}{2} \rho v^2 S C_L
86-
</div>
81+
</code></pre>
8782
```
8883

89-
And our module `example.js` looks as follows:
84+
…and our module `example.js` contains:
9085

9186
```js
92-
import {read} from 'to-vfile'
93-
import {unified} from 'unified'
94-
import rehypeParse from 'rehype-parse'
95-
import rehypeKatex from 'rehype-katex'
9687
import rehypeDocument from 'rehype-document'
88+
import rehypeKatex from 'rehype-katex'
89+
import rehypeParse from 'rehype-parse'
9790
import rehypeStringify from 'rehype-stringify'
91+
import {read, write} from 'to-vfile'
92+
import {unified} from 'unified'
9893

9994
const file = await unified()
10095
.use(rehypeParse, {fragment: true})
101-
.use(rehypeKatex)
10296
.use(rehypeDocument, {
103-
css: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css'
97+
// Get the latest one from: <https://katex.org/docs/browser>.
98+
css: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css'
10499
})
100+
.use(rehypeKatex)
105101
.use(rehypeStringify)
106-
.process(await read('example.html'))
102+
.process(await read('input.html'))
107103

108-
console.log(String(file))
104+
file.basename = 'output.html'
105+
await write(file)
109106
```
110107

111-
Now running `node example.js` yields:
108+
…then running `node example.js` creates an `output.html` with:
112109

113110
```html
114111
<!doctype html>
115112
<html lang="en">
116113
<head>
117114
<meta charset="utf-8">
118-
<title>example</title>
119-
<meta name="viewport" content="width=device-width, initial-scale=1">
120-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected].0/dist/katex.min.css">
115+
<title>input</title>
116+
<meta content="width=device-width, initial-scale=1" name="viewport">
117+
<link href="https://cdn.jsdelivr.net/npm/[email protected].8/dist/katex.min.css" rel="stylesheet">
121118
</head>
122119
<body>
123120
<p>
124-
Lift(<code class="language-math math-inline"><span class="katex">…</span></span>) can be determined by Lift Coefficient
125-
(<code class="language-math math-inline"><span class="katex">…</span></span>) like the following equation.
121+
Lift(<span class="katex"><!--…--></span>) can be determined by Lift Coefficient
122+
(<span class="katex"><!--…--></span>) like the following equation.
126123
</p>
127-
<div class="math math-display"><span class="katex-display">…</span></div>
124+
<span class="katex-display"><!--…--></span>
128125
</body>
129126
</html>
130127
```
131128

129+
…open `output.html` in a browser to see the rendered math.
130+
132131
## API
133132

134133
This package exports no identifiers.
135-
The default export is `rehypeKatex`.
134+
The default export is [`rehypeKatex`][api-rehype-katex].
136135

137136
### `unified().use(rehypeKatex[, options])`
138137

139-
Transform `<span class="math-inline">` and `<div class="math-display">` with
140-
[KaTeX][].
138+
Render elements with a `language-math` (or `math-display`, `math-inline`)
139+
class with [KaTeX][].
141140

142-
##### `options`
141+
###### Parameters
142+
143+
* `options` ([`Options`][api-options])
144+
— configuration
145+
146+
###### Returns
147+
148+
Transform ([`Transformer`][unified-transformer]).
149+
150+
### `Options`
151+
152+
Configuration (TypeScript type).
153+
154+
###### Type
155+
156+
```ts
157+
import {KatexOptions} from 'katex'
158+
159+
type Options = Omit<KatexOptions, 'displayMode' | 'throwOnError'>
160+
```
161+
162+
See [*Options* on `katex.org`][katex-options] for more info.
163+
164+
## Markdown
165+
166+
This plugin supports the syntax extension enabled by
167+
[`remark-math`][remark-math].
168+
It also supports math generated by using fenced code:
169+
170+
````markdown
171+
```math
172+
C_L
173+
```
174+
````
143175
144-
Configuration (optional).
145-
All options, except for `displayMode`, are passed to [KaTeX][katex-options].
176+
## HTML
177+
178+
The content of any element with a `language-math`, `math-inline`, or
179+
`math-display` class is transformed.
180+
The elements are replaced by what KaTeX renders.
181+
Either a `math-display` class or using `<pre><code class="language-math">` will
182+
result in “display” math: math that is a centered block on its own line.
146183
147184
## CSS
148185
@@ -152,66 +189,63 @@ style it properly.
152189
At the time of writing, the last version is:
153190
154191
```html
155-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-Xi8rHCmBmhbuyyhbI88391ZKP2dmfnOl4rT9ZfRI7mLTdk1wblIUnrIq35nqwEvC" crossorigin="anonymous">
192+
<!-- Get the latest one from: https://katex.org/docs/browser -->
193+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css">
156194
```
157195
158-
<!-- To update the above, read the note in the monorepo readme. -->
159-
160-
## Syntax tree
161-
162-
This plugin transforms elements with a class name of either `math-inline` and/or
163-
`math-display`.
164-
165196
## Types
166197
167198
This package is fully typed with [TypeScript][].
168-
An extra `Options` type is exported, which models the accepted options.
199+
It exports the additional type [`Options`][api-options].
169200
170201
## Compatibility
171202
172-
Projects maintained by the unified collective are compatible with all maintained
203+
Projects maintained by the unified collective are compatible with maintained
173204
versions of Node.js.
174-
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
175-
Our projects sometimes work with older versions, but this is not guaranteed.
205+
206+
When we cut a new major release, we drop support for unmaintained versions of
207+
Node.
208+
This means we try to keep the current release line, `rehype-katex@^7`,
209+
compatible with Node.js 16.
176210
177211
This plugin works with unified version 6+ and rehype version 4+.
178212
179213
## Security
180214
181-
Using `rehype-katex` should be safe assuming that you trust KaTeX.
182-
Any vulnerability in it could open you to a [cross-site scripting (XSS)][xss]
183-
attack.
184-
Always be wary of user input and use [`rehype-sanitize`][rehype-sanitize].
215+
Assuming you trust KaTeX, using `rehype-katex` is safe.
216+
A vulnerability in it could open you to a
217+
[cross-site scripting (XSS)][wiki-xss] attack.
218+
Be wary of user input and use [`rehype-sanitize`][rehype-sanitize].
185219
186-
When you don’t trust user content but do trust KaTeX, you can allow the classes
187-
added by `remark-math` while disallowing anything else in the `rehype-sanitize`
188-
schema, and run `rehype-katex` afterwards.
189-
Like so:
220+
When you don’t trust user content but do trust KaTeX, run `rehype-katex`
221+
*after* `rehype-sanitize`:
190222
191223
```js
224+
import rehypeKatex from 'rehype-katex'
192225
import rehypeSanitize, {defaultSchema} from 'rehype-sanitize'
226+
import rehypeStringify from 'rehype-stringify'
227+
import remarkMath from 'remark-math'
228+
import remarkParse from 'remark-parse'
229+
import remarkRehype from 'remark-rehype'
230+
import {unified} from 'unified'
193231

194-
const mathSanitizeSchema = {
195-
...defaultSchema,
196-
attributes: {
197-
...defaultSchema.attributes,
198-
div: [
199-
...defaultSchema.attributes.div,
200-
['className', 'math', 'math-display']
201-
],
202-
span: [
203-
['className', 'math', 'math-inline']
204-
]
205-
}
206-
}
207-
208-
// …
209-
210-
unified()
211-
// …
212-
.use(rehypeSanitize, mathSanitizeSchema)
232+
const file = await unified()
233+
.use(remarkParse)
234+
.use(remarkMath)
235+
.use(remarkRehype)
236+
.use(rehypeSanitize, {
237+
...defaultSchema,
238+
attributes: {
239+
...defaultSchema.attributes,
240+
// The `language-*` regex is allowed by default.
241+
code: [['className', /^language-./, 'math-inline', 'math-display']]
242+
}
243+
})
213244
.use(rehypeKatex)
214-
// …
245+
.use(rehypeStringify)
246+
.process('$C$')
247+
248+
console.log(String(file))
215249
```
216250
217251
## Related
@@ -255,9 +289,9 @@ abide by its terms.
255289
256290
[downloads]: https://www.npmjs.com/package/rehype-katex
257291
258-
[size-badge]: https://img.shields.io/bundlephobia/minzip/rehype-katex.svg
292+
[size-badge]: https://img.shields.io/bundlejs/size/rehype-katex
259293
260-
[size]: https://bundlephobia.com/result?p=rehype-katex
294+
[size]: https://bundlejs.com/?q=rehype-katex
261295
262296
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
263297
@@ -271,36 +305,44 @@ abide by its terms.
271305
272306
[npm]: https://docs.npmjs.com/cli/install
273307
308+
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
309+
274310
[esmsh]: https://esm.sh
275311
276312
[health]: https://github.com/remarkjs/.github
277313
278-
[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md
314+
[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
279315
280-
[support]: https://github.com/remarkjs/.github/blob/HEAD/support.md
316+
[support]: https://github.com/remarkjs/.github/blob/main/support.md
281317
282-
[coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md
318+
[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
283319
284320
[license]: https://github.com/remarkjs/remark-math/blob/main/license
285321
286322
[author]: https://rokt33r.github.io
287323
288-
[unified]: https://github.com/unifiedjs/unified
324+
[katex]: https://github.com/Khan/KaTeX
325+
326+
[katex-options]: https://katex.org/docs/options.html
289327
290328
[rehype]: https://github.com/rehypejs/rehype
291329
292-
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
330+
[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
293331
294-
[typescript]: https://www.typescriptlang.org
332+
[unified]: https://github.com/unifiedjs/unified
295333
296-
[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
334+
[unified-transformer]: https://github.com/unifiedjs/unified#transformer
297335
298-
[katex]: https://github.com/Khan/KaTeX
336+
[typescript]: https://www.typescriptlang.org
299337
300-
[katex-options]: https://katex.org/docs/options.html
338+
[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
301339
302340
[mathjax]: https://www.mathjax.org
303341
304-
[remark-math]: ../remark-math
342+
[remark-math]: ../remark-math/
343+
344+
[rehype-mathjax]: ../rehype-mathjax/
345+
346+
[api-options]: #options
305347
306-
[rehype-mathjax]: ../rehype-mathjax
348+
[api-rehype-katex]: #unifieduserehypekatex-options

0 commit comments

Comments
 (0)