# rehype-typst

**[rehype](https://github.com/rehypejs/rehype)** plugin to render elements with a `language-math` class with
[Typst](https://github.com/typst/typst).

## Contents

- [rehype-typst](#rehype-typst)
  - [Contents](#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(rehypeTypst[, options])`](#unifieduserehypetypst-options)
          - [Returns](#returns)
  - [Markdown](#markdown)
  - [HTML](#html)

## What is this?

This package is a [unified](https://unifiedjs.com/explore/package/unified/) ([rehype](https://github.com/rehypejs/rehype)) plugin to render math.
You can add classes to HTML elements, use fenced code in markdown, or combine
with [remark-math](https://github.com/remarkjs/remark-math) for a `$C$` syntax extension.

## When should I use this?

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

## Install

This package is [ESM only](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
In Node.js (version 16+), install with [npm](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager):

```sh
npm install @myriaddreamin/rehype-typst
```

## Use

Say our document `input.html` contains:

```html
<p>
  Lift(<code class="language-math">L</code>) can be determined by Lift Coefficient
  (<code class="language-math">C_L</code>) like the following equation.
</p>
<pre><code class="language-math">
  L = 1/2 rho v^2 S C_L
</code></pre>
```

…and our module `example.js` contains:

```js
import rehypeTypst from '@myriaddreamin/rehype-typst'
import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import {read, write} from 'to-vfile'
import {unified} from 'unified'

const file = await unified()
  .use(rehypeParse, {fragment: true})
  .use(rehypeTypst)
  .use(rehypeStringify)
  .process(await read('input.html'))

file.basename = 'output.html'
await write(file)
```

…then running `node example.js` creates an `output.html` and open `output.html` in a browser to see the rendered math.

## API

This package exports no identifiers.
The default export is `rehypeTypst`.

### `unified().use(rehypeTypst[, options])`

Render elements with a `language-math` (or `math-display`, `math-inline`)
class with [Typst](https://github.com/typst/typst).

<!-- ###### Parameters

*   `options` ([`Options`][api-options])
    — configuration -->

###### Returns

Transform ([`Transformer`][unified-transformer]).

<!-- ### `Options`

Configuration (TypeScript type). -->

<!-- ###### Type

```ts
import {KatexOptions} from 'katex'

type Options = Omit<KatexOptions, 'displayMode' | 'throwOnError'>
```

See [*Options* on `katex.org`][katex-options] for more info. -->

## Markdown

This plugin supports the syntax extension enabled by
[remark-math](https://github.com/remarkjs/remark-math).
It also supports math generated by using fenced code:

````markdown
```math
C_L
```
````

## HTML

The content of any element with a `language-math`, `math-inline`, or
`math-display` class is transformed.
The elements are replaced by what Typst renders.
Either a `math-display` class or using `<pre><code class="language-math">` will
result in “display” math: math that is a centered block on its own line.

<!-- Definitions -->

[unified-transformer]: https://github.com/unifiedjs/unified#transformer