Getting started
``` `autolink: Some(Autolink::Enabled(true))` also links each heading to itself, as rehype-autolink-headings does after rehype-slug: an `` prepended by default, or placed by `behavior` (`Append`, `Wrap`, `Before`, `After`). Its `content` and `group` are hast as JSON. Follows [rehype-slug](https://www.npmjs.com/package/rehype-slug). | Option | Type | Default | Description | | ----------------- | ------------------ | ------- | -------------------------------------------------------------------------------------------------------- | | `prefix` | `string` | `""` | Put before each id. | | `reserveExisting` | `boolean` | `false` | Count the ids already in the document as taken, so a generated id never repeats one a link may point at. | | `ranks` | `number[] \| null` | `null` | The heading ranks, 1 to 6, that get ids; every heading when left out. | | `autolink` | `Autolink \| null` | | Link each heading with an `id` to itself, as rehype-autolink-headings does: `true`, or its options. | **`Autolink`** `html.slug`'s `autolink`: on, or on with rehype-autolink-headings' options. Takes `boolean | AutolinkOptions`. **`AutolinkOptions`** rehype-autolink-headings' options, JSON values only. | Option | Type | Default | Description | | ------------------- | --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `behavior` | `AutolinkBehavior` | | Where the link goes: in the heading first or last, around its content, or before or after it. | | `properties` | `Record`. ```rust use textlane::{Processor, html}; let output = Processor::new() .with(html::Parse { fragment: true, ..Default::default() }) .with(html::UnwrapImages) .with(html::Stringify::default()) .freeze()? .process(r#"
```
Follows [rehype-unwrap-images](https://www.npmjs.com/package/rehype-unwrap-images).
No options.
## html.math
Turns `$…$` and `$$…$$` in text into the `` and `math-display` elements `md.math` makes, for `html.katex` to render. It reads dollars by pandoc's rule, so prices stay text: an opening `$` is followed by a non-space, a closing one follows a non-space and is not followed by a digit; `\$` is a dollar sign. Links, code, scripts, form text, `math` and `svg` are left alone, or the elements `ignore` names.
```rust
use textlane::{Processor, html};
let output = Processor::new()
.with(html::Parse { fragment: true, ..Default::default() })
.with(html::Math::default())
.with(html::Stringify::default())
.freeze()?
.process(r#"Area $\pi r^2$, price $5
"#)?;
output.value
// Area \pi r^2, price $5
```
| Option | Type | Default | Description |
| ---------------------- | ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `singleDollarTextMath` | `boolean` | `true` | Let one dollar, `$a$`, form math, as well as two. |
| `ignore` | `string[] \| null` | `null` | Elements, by tag name, whose text is left alone; links, code, scripts, form text, `math` and `svg` when left out. |
| `ignoreAttributes` | `string[]` | `[]` | Attributes, such as `data-literal`, whose elements' text is left alone. |
## html.linkify
Turns bare URLs and email addresses in text into links, as GitHub's literal autolinks do: an `http`, `https` or `ftp` URL as written, a `www.` one under `https://`, an email under `mailto:`. Any other scheme, such as `javascript:`, and a bare domain, such as `index.html`, stay text. Links, code, scripts, form text, `math` and `svg` are left alone, or the elements `ignore` names, and any element with an attribute `ignoreAttributes` names.
```rust
use textlane::{Processor, html};
let output = Processor::new()
.with(html::Parse { fragment: true, ..Default::default() })
.with(html::Linkify::default())
.with(html::Stringify::default())
.freeze()?
.process(r#"See www.example.com or a@example.com
"#)?;
output.value
// See www.example.com or a@example.com
```
| Option | Type | Default | Description |
| ------------------ | ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `ignore` | `string[] \| null` | `null` | Elements, by tag name, whose text is left alone; links, code, scripts, form text, `math` and `svg` when left out. |
| `ignoreAttributes` | `string[]` | `[]` | Attributes, such as `data-literal`, whose elements' text is left alone. |
## html.gemoji
Turns gemoji shortcodes in text, `:rocket:`, into their emoji, as `md.gemoji` does in Markdown; with `accessible`, each sits in a `` labelled with its name. Text that only looks like one, `10:30:00`, stays as written.
```rust
use textlane::{Processor, html};
let output = Processor::new()
.with(html::Parse { fragment: true, ..Default::default() })
.with(html::Gemoji::default())
.with(html::Stringify::default())
.freeze()?
.process(r#"Ship it :rocket:
"#)?;
output.value
// Ship it 🚀
```
| Option | Type | Default | Description |
| ------------------ | ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `accessible` | `boolean` | `false` | Wrap each emoji in ``, labelled with its name. |
| `ignore` | `string[] \| null` | `null` | Elements, by tag name, whose text is left alone; links, code, scripts, form text, `math` and `svg` when left out. |
| `ignoreAttributes` | `string[]` | `[]` | Attributes, such as `data-literal`, whose elements' text is left alone. |
## html.pathRewrite
Rewrites the URLs in `href`, `src`, `srcset` and `poster`, or the attributes `attributes` names, as a site serves them, as `md.pathRewrite` does for Markdown: a relative URL is resolved against the file's path and made root-relative, every root-relative one goes under `base` once, and an `href` naming a file in `pages` takes that page's URL.
```rust
use textlane::{Processor, html};
let output = Processor::new()
.with(html::Parse { fragment: true, ..Default::default() })
.with(html::PathRewrite { base: Some("/docs".into()), ..Default::default() })
.with(html::Stringify::default())
.freeze()?
.process(r#"Guide"#)?;
output.value
// Guide
```
| Option | Type | Default | Description |
| ------------ | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `root` | `string \| null` | `null` | The directory URLs count from, as the file's path spells it; the path's own starting point when left out. |
| `base` | `string \| null` | `null` | The URL the site is served at, such as `/docs`, put before every root-relative URL once. |
| `pages` | `Record` | `{}` | Files, relative to `root`, to the URL of their page, such as `{"guide.html": "/guide/"}`; an `href` naming one takes it. |
| `attributes` | `string[] \| null` | `null` | The attributes whose URLs are rewritten; `href`, `src`, `srcset` and `poster` when left out. |
## html.extractToc
Stores the headings, nested by rank, as the file's `data.toc`, as @stefanprobst/rehype-extract-toc does: each `{ depth, value, id?, children? }`. Run it after `html.slug` so headings carry their ids.
```rust
use textlane::{Processor, html, md};
let output = Processor::new()
.with(md::Parse::default())
.with(md::ToHtml::default())
.with(html::Slug::default())
.with(html::ExtractToc::default())
.with(html::Stringify::default())
.freeze()?
.process("# Guide\n\n## Install")?;
output.file.data["toc"]
// [{ depth: 1, value: "Guide", id: "guide", children: [{ depth: 2, value: "Install", id: "install" }] }]
```
`skip` lists attributes that keep a heading out, such as `data-toc-hidden`; what would nest under it nests under the heading before. A `hidden` heading stays listed, which suits a heading meant for the table of contents alone.
Follows [@stefanprobst/rehype-extract-toc](https://www.npmjs.com/package/@stefanprobst/rehype-extract-toc).
| Option | Type | Default | Description |
| ------------ | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skip` | `string[]` | `[]` | Attributes, such as `data-toc-hidden`, that keep a heading out of the table of contents, or `name=value`, such as `data-toc=false`, for one value of it; what would nest under it nests under the heading before. |
| `skipInside` | `string[]` | `[]` | Elements, by tag name, whose headings stay out, such as a card's title. |
| `minDepth` | `number \| null` | `null` | The shallowest heading rank listed, 1 to 6. |
| `maxDepth` | `number \| null` | `null` | The deepest heading rank listed, 1 to 6. |
## html.highlight
Colors code blocks with TextMate grammars and themes, as Shiki does, natively.
````rust
use textlane::{Processor, html, md};
let output = Processor::new()
.with(md::Parse::default())
.with(md::ToHtml::default())
.with(html::Highlight { theme: Some("github-light".into()), ..Default::default() })
.with(html::Stringify::default())
.freeze()?
.process("```js\nlet a = 1\n```")?;
output.value
// `.
```rust
use textlane::html::{Highlight, HighlightTransformer, TransformerName};
let highlight = Highlight {
theme: Some("github-light".into()),
transformers: vec![HighlightTransformer::Name(TransformerName::NotationDiff)],
..Default::default()
};
```
A grammar's time grows with the square of a line's length, so a line of 2,000 characters or more, typically minified code, is left one plain token, as Shiki's `tokenize_max_line_length` leaves it; Shiki has no such limit by default, and `0` lifts it.
Follows [@shikijs/rehype](https://www.npmjs.com/package/@shikijs/rehype).
| Option | Type | Default | Description |
| ----------------------- | ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `themes` | `Record \| null` | `null` | The theme of each color mode, `light` first, as `{"light": …, "dark": …}`. |
| `theme` | `string \| null` | `null` | The one theme, when `themes` is not given. |
| `defaultLanguage` | `string \| null` | `null` | The language of a block that names none; such a block is left alone without it. |
| `fallbackLanguage` | `string \| null` | `null` | The language of a block naming one Shiki does not know; left alone without it. |
| `colorReplacements` | `Record` | | Colors to replace, by their lowercase spelling: a color for every theme, or a theme's name to a map of its own. |
| `addLanguageClass` | `boolean` | `false` | Add `language-` to each highlighted ``. |
| `inline` | `InlineCode \| null` | | Highlight inline code too, by how it names its language: `tailing-curly-colon` reads `` `a(){:js}` ``. |
| `metaProperty` | `string \| null` | `null` | The `` property that gets a block's meta, the text after its language; the JSON stand-in for `parseMetaString: meta => ({ [name]: meta })`. |
| `transformers` | `HighlightTransformer[]` | | The transformers of @shikijs/transformers to run, in order, by name or with options. |
| `tokenizeMaxLineLength` | `number \| null` | `null` | Lines at least this long, in UTF-16 units, are left one plain token as Shiki's own option leaves them; 2,000 when left out, where Shiki has no limit, since a grammar's time grows with the square of a line's length. `0` lifts it. |
| `lineAttributes` | `Record` | | Attributes of a block's `` or `` listing lines, `2,4-5`, each to the classes those lines get, or to `{line, pre}`, the second for the ``: `{"data-focus": {"line": "focused", "pre": "has-focused"}}`. |
| `wordAttribute` | `string \| null` | `null` | The attribute of a block's `` or `` listing words, separated by commas, marked at every place as `metaWordHighlight` marks a meta's `/word/`. |
| `lineNumberAttribute` | `string \| null` | `null` | The attribute of a block's `` or `` that numbers its lines as `renderLineNumber` does, from its value, or 1 when it is empty. |
| `skipElements` | `boolean` | `false` | Leave a block alone when its code holds elements, such as ``, which highlighting would flatten into text. |
| `keepProperties` | `boolean` | `false` | Keep the properties of a block's `` and ``, such as `data-title`, on the ones Shiki makes, merging classes; Shiki's own win where both set one. |
**`ColorReplacement`**
A replacement color, or a theme's own replacements.
Takes `string | Record`.
**`InlineCode`**
How inline code names its language.
Takes `"tailing-curly-colon" | "class"`.
**`HighlightTransformer`**
A transformer of @shikijs/transformers: its name alone, or its name and options.
Takes `TransformerName | ConfiguredTransformer`.
**`LineMark`**
The classes the lines a `lineAttributes` attribute lists get, and maybe its ``.
Takes `Classes | { line: Classes; pre?: Classes | null }`.
**`TransformerName`**
The transformers `html.highlight` runs natively.
Takes `"notationDiff" | "notationFocus" | "notationHighlight" | "notationErrorLevel" | "metaHighlight" | "metaWordHighlight" | "renderLineNumber"`.
**`ConfiguredTransformer`**
A transformer with its options, as @shikijs/transformers names them.
Takes `{ name: "notationDiff"; classLineAdd?: Classes | null; classLineRemove?: Classes | null; classActivePre?: Classes | null; classActiveCode?: Classes | null } | { name: "notationFocus"; classActiveLine?: Classes | null; classActivePre?: Classes | null; classActiveCode?: Classes | null } | { name: "notationHighlight"; classActiveLine?: Classes | null; classActivePre?: Classes | null; classActiveCode?: Classes | null } | { name: "notationErrorLevel"; classMap?: Record | null; classActivePre?: Classes | null; classActiveCode?: Classes | null } | { name: "metaHighlight"; className?: Classes | null; zeroIndexed?: boolean } | { name: "metaWordHighlight"; className?: Classes | null } | { name: "renderLineNumber"; classLineNumber?: Classes | null; start?: number | null }`.
**`Classes`**
Class names: a list, or one string of them separated by white space.
Takes `string | string[]`.
## html.katex
Renders math with KaTeX, as rehype-katex does, natively: each `$…$`, `$$…$$` and ` ```math ` that `md.math` and `md.toHtml` leave becomes KaTeX's HTML and MathML. Pages need KaTeX's stylesheet and fonts. A formula that fails to render is reported in the file's messages and shown in `errorColor`.
```rust
use textlane::{Processor, html, md};
let output = Processor::new()
.with(md::Parse::default())
.with(md::Math::default())
.with(md::ToHtml::default())
.with(html::Katex::default())
.with(html::Stringify::default())
.freeze()?
.process("Euler: $e^{i\\pi} = -1$")?;
output.value
// Euler: