example

` with [MathJax][]. This package includes three plugins, split out because MathJax targets have a -big memory and size footprint: SVG, CHTML, and browser: +big memory and bundle size footprint: SVG, CHTML, and browser: ###### SVG -Render math as [SVG][mathjax-svg] (`import rehypeMathJaxSvg from -'rehype-mathjax/svg.js'`, default). +Render math as [SVG][mathjax-svg] +(`import rehypeMathjaxSvg from 'rehype-mathjax/svg.js'`, default). About 566kb minzipped. ###### CHTML -Render math as [CHTML][mathjax-chtml] (`import rehypeMathJaxChtml from -'rehype-mathjax/chtml.js'`). +Render math as [CHTML][mathjax-chtml] +(`import rehypeMathjaxChtml from 'rehype-mathjax/chtml.js'`). About 154kb minzipped. Needs a `fontURL` to be passed. ###### Browser -Tiny wrapper to render MathJax client-side (`import rehypeMathJaxBrowser from -'rehype-mathjax/browser.js'`). +Tiny wrapper that expects MathJax to do work client side +(`import rehypeMathjaxBrowser from 'rehype-mathjax/browser.js'`). About 1kb minzipped. -Uses `options.displayMath` (default: `['\\[', '\\]']`) for display, and +Uses `options.displayMath` (default: `['\\[', '\\]']`) for display math and `options.inlineMath` (default: `['\$', '\$']`) for inline math. You need to load MathJax on the client yourself and start it with corresponding @@ -135,19 +179,96 @@ The browser plugin uses the first delimiter pair in `tex.displayMath` and These options are passed to the [CommonHTML output processor][mathjax-chtml-options]. Passing `fontURL` is required! +For example: + +```js + // … + .use(rehypeMathjaxChtml, { + chtml: { + fontURL: 'https://cdn.jsdelivr.net/npm/mathjax@3/components/output/chtml/fonts/woff-v2' + } + }) + // … +``` #### `options.svg` These options are passed to the [SVG output processor][mathjax-svg-options]. +## CSS + +The HTML produced by MathJax does not require any extra CSS to render correctly. + +## Syntax tree + +This plugin transforms elements with a class name of either `math-inline` and/or +`math-display`. + +## Types + +This package is fully typed with [TypeScript][]. +An extra `Options` type is exported, which models the accepted options. + +## Compatibility + +Projects maintained by the unified collective are compatible with all maintained +versions of Node.js. +As of now, that is Node.js 12.20+, 14.14+, and 16.0+. +Our projects sometimes work with older versions, but this is not guaranteed. + +This plugin works with unified version 6+ and rehype version 4+. + ## Security -Use of `rehype-mathjax` renders user content with [MathJax][], so any -vulnerability in MathJax can open you to a [cross-site scripting (XSS)][xss] +Using `rehype-mathjax` should be safe assuming that you trust MathJax. +Any vulnerability in it could open you to a [cross-site scripting (XSS)][xss] attack. - Always be wary of user input and use [`rehype-sanitize`][rehype-sanitize]. +When you don’t trust user content but do trust MathKax, you can allow the +classes added by `remark-math` while disallowing anything else in the +`rehype-sanitize` schema, and run `rehype-katex` afterwards. +Like so: + +```js +import rehypeSanitize, {defaultSchema} from 'rehype-stringify' + +const mathSanitizeSchema = { + ...defaultSchema, + attributes: { + ...defaultSchema.attributes, + div: [ + ...defaultSchema.attributes.div, + ['className', 'math', 'math-display'] + ], + span: [ + ['className', 'math', 'math-inline'] + ] + } +} + +// … + +unified() + // … + .use(rehypeSanitize, mathSanitizeSchema) + .use(rehypeMathjax) + // … +``` + +## Related + +* [`rehype-katex`][rehype-katex] + — same but with KaTeX +* [`rehype-highlight`](https://github.com/rehypejs/rehype-highlight) + — highlight code blocks +* [`rehype-autolink-headings`](https://github.com/rehypejs/rehype-autolink-headings) + — add links to headings +* [`rehype-sanitize`](https://github.com/rehypejs/rehype-sanitize) + — sanitize HTML +* [`rehype-document`](https://github.com/rehypejs/rehype-document) + — wrap a document around the tree + ## Contribute See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways @@ -192,6 +313,8 @@ abide by its terms. [npm]: https://docs.npmjs.com/cli/install +[skypack]: https://www.skypack.dev + [health]: https://github.com/remarkjs/.github [contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md @@ -206,8 +329,12 @@ abide by its terms. [rehype]: https://github.com/rehypejs/rehype +[unified]: https://github.com/unifiedjs/unified + [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting +[typescript]: https://www.typescriptlang.org + [rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize [mathjax]: https://mathjax.org/ @@ -223,3 +350,9 @@ abide by its terms. [mathjax-svg-options]: http://docs.mathjax.org/en/latest/options/output/svg.html [mathjax-chtml-options]: http://docs.mathjax.org/en/latest/options/output/chtml.html + +[katex]: https://github.com/Khan/KaTeX + +[remark-math]: ../remark-math + +[rehype-katex]: ../rehype-katex diff --git a/packages/rehype-mathjax/svg.js b/packages/rehype-mathjax/svg.js index 23fc64a..dd16ab8 100644 --- a/packages/rehype-mathjax/svg.js +++ b/packages/rehype-mathjax/svg.js @@ -1,6 +1,4 @@ /** - * @typedef {import('hast').Root} Root - * @typedef {import('mathjax-full/js/output/svg.js').SVG} SVG_ * @typedef {import('./lib/create-plugin.js').Options} Options */ diff --git a/packages/remark-math/readme.md b/packages/remark-math/readme.md index 6849090..cbf8291 100644 --- a/packages/remark-math/readme.md +++ b/packages/remark-math/readme.md @@ -8,43 +8,87 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -[**remark**][remark] plugin to parse and stringify math. - -## Important! - -This plugin is affected by the new parser in remark -([`micromark`](https://github.com/micromark/micromark), -see [`remarkjs/remark#536`](https://github.com/remarkjs/remark/pull/536)). -Use version 3 while you’re still on remark 12. -Use version 4 for remark 13+. +**[remark][]** plugin to support math (`$C_L$`). + +## Contents + +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`unified().use(remarkMath[, options])`](#unifieduseremarkmath-options) +* [Syntax](#syntax) +* [HTML](#html) +* [Syntax tree](#syntax-tree) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Related](#related) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin to add support for math. +You can use this to add support for parsing and serializing this syntax +extension. + +**unified** is a project that transforms content with abstract syntax trees +(ASTs). +**remark** adds support for markdown to unified. +**mdast** is the markdown AST that remark uses. +**micromark** is the markdown parser we use. +This is a remark plugin that adds support for the math syntax and AST to remark. + +## When should I use this? + +This project is useful when you want to support math in markdown. +Extending markdown with a syntax extension makes the markdown less portable. +LaTeX equations are also quite hard. +But this mechanism works well when you want authors, that have some LaTeX +experience, to be able to embed rich diagrams of math in scientific text. ## Install -This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): -Node 12+ is needed to use it and it must be `import`ed instead of `require`d. - -[npm][]: +This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). +In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: ```sh npm install remark-math ``` +In Deno with [Skypack][]: + +```js +import remarkMath from 'https://cdn.skypack.dev/remark-math@5?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + ## Use -Say we have the following file, `example.md`: +Say we have the following file `example.md`: ```markdown -Lift($L$) can be determined by Lift Coefficient ($C_L$) like the following equation. +Lift($L$) can be determined by Lift Coefficient ($C_L$) like the following +equation. $$ L = \frac{1}{2} \rho v^2 S C_L $$ ``` -And our module, `example.js`, looks as follows: +And our module `example.js` looks as follows: ```js -import {readSync} from 'to-vfile' +import {read} from 'to-vfile' import {unified} from 'unified' import remarkParse from 'remark-parse' import remarkMath from 'remark-math' @@ -52,25 +96,26 @@ import remarkRehype from 'remark-rehype' import rehypeKatex from 'rehype-katex' import rehypeStringify from 'rehype-stringify' -const file = readSync('example.md') - -unified() - .use(remarkParse) - .use(remarkMath) - .use(remarkRehype) - .use(rehypeKatex) - .use(rehypeStringify) - .process(file) - .then((file) => { - console.log(String(file)) - }) +main() + +async function main() { + const file = await unified() + .use(remarkParse) + .use(remarkMath) + .use(remarkRehype) + .use(rehypeKatex) + .use(rehypeStringify) + .process(await read('example.md')) + + console.log(String(file)) +} ``` -Now, running `node example` yields: +Now running `node example.js` yields: ```html -

Lift( $L$ ) can be determined by Lift Coefficient ( $C_L$ ) like the following equation.

L = \frac{1}{2} \rho v^2 S C_L

Lift( $\dots$ ) can be determined by Lift Coefficient ( $\dots$ ) like the following equation.

\dots

``` ## API @@ -80,16 +125,12 @@ The default export is `remarkMath`. ### `unified().use(remarkMath[, options])` -Parse and stringify math. - -Get’s useful when combined with [`rehype-katex`][rehype-katex] or -[`rehype-mathjax`][rehype-mathjax]. - -See [`micromark/micromark-extension-math`][extension-math] for more info on what -syntax is supported. +Plugin to support math. ##### `options` +Configuration (optional). + ###### `options.singleDollarTextMath` Whether to support math (text) with a single dollar (`boolean`, default: @@ -97,21 +138,81 @@ Whether to support math (text) with a single dollar (`boolean`, default: Single dollars work in Pandoc and many other places, but often interfere with “normal” dollars in text. -#### Notes +## Syntax + +This plugin applies a micromark extensions to parse the syntax. +See its readme for parse details: + +* [`micromark-extension-math`](https://github.com/micromark/micromark-extension-math#syntax) + +> 👉 **Note**: `$math$` works similar to `` `code` ``. +> That means escapes don’t work inside math but you can use more dollars around +> the math instead: `$$\raisebox{0.25em}{$\frac a b$}$$` -##### Escaping +## HTML -Markdown escapes don’t work in math, similar to code, but you can use more -dollars around the math instead: `$$\raisebox{0.25em}{$\frac -a b$}$$` +This plugin integrates with [`remark-rehype`][remark-rehype]. +When mdast (markdown AST) is turned into hast (the HTML AST) the math nodes +are turned into `

L