# @typstream/html-compat

> A Typst prelude and stylesheet that keep grids, alignment, shapes, placement and drawings in Typst's HTML export.

Source: https://typstream.vercel.app/docs/reference/html-compat

Typst 0.15.1's HTML export drops the layout elements it can't express, and the text inside them. `#grid[…]`,
`#align(center)[…]`, `#rect[…]`, `#place(…)`, `#stack`, `#columns`, `#pad`, the transforms and `layout` all come out
empty, with a warning such as "grid was ignored during HTML export". `@typstream/html-compat` is a Typst prelude that
maps each of them to HTML (or, for drawings, to an inline SVG), plus the CSS for that HTML.

## When to use it

Use it whenever you render the HTML target. Models use grids, alignment and boxes all the time, and without the prelude
that content disappears from the HTML. The `typstream` package's `<Typstream>` adds it by default (`htmlCompat={false}`
turns it off); with `@typstream/react`, `@typstream/dom` or `@typstream/engine`, pass the `htmlCompat` plugin yourself.

The prelude only acts when `target()` is `"html"`, so the same preamble leaves paged output byte-identical. You can keep
it on for both targets. [Render targets](/docs/concepts/render-targets) compares the two.

## Install

```npm
npm install @typstream/html-compat
```

## Example

```tsx
import { htmlCompat } from "@typstream/html-compat";
import { Typstream } from "@typstream/react";

<Typstream plugins={[htmlCompat]} source={text} />;
```

The plugin mounts the prelude, adds the preamble that applies it, lets the prelude's HTML through the sanitizer, and
adds its stylesheet to the renderer. With html-compat, this document keeps its layout in the HTML target:

```typst
#align(center)[*Fractions at a glance*]

#grid(
  columns: (1fr, 1fr),
  gutter: 12pt,
  rect(width: 100%, fill: blue.lighten(85%), radius: 4pt, inset: 10pt)[
    *Proper* \ The top is smaller: $3/4$
  ],
  rect(width: 100%, fill: orange.lighten(80%), radius: 4pt, inset: 10pt)[
    *Improper* \ The top is larger: $7/4$
  ],
)
```

Without the prelude, Typst's HTML export would contain none of this text.

## What it does

It writes the layout Typst gives a document on pages, so the HTML target looks like the paged view: with
`@typstream/dom`'s renderer (which lays the HTML out on pages) and Typst's fonts (`registerTypstFonts`, which the
`typstream` package and `mountTypstream`'s `fonts` option do for you), switching a document between the targets changes
nothing you can see. The engine puts its layout profile before HTML compiles too, and the prelude reads it: text edges,
paragraph and heading spacing, table insets.

| Element | HTML |
| --- | --- |
| Text | Size, colour, font, weight, style, tracking, word spacing and baseline shift as inline styles; lengths resolved as Typst resolves them. Paragraphs and blocks carry their text size, so their spacing is in it, as Typst's. |
| Spacing | Paragraph, block and heading spacing collapse as Typst's flow collapses them (a block's own `above`/`below` beats paragraph spacing; `v` adds to the stronger; weak and fractional spacing replace it; a tight list after a paragraph, without a blank line, is attached to it). First-line indents. |
| `grid`, `table` | A CSS grid with cells placed as Typst places them (spans, explicit `x`/`y`, gutters), fills, strokes, insets and alignment, functions of `(x, y)` included. Tables are ARIA tables (`role="table"`, rows, cells, column headers), their header repeated on each page they go on to. |
| `align` | Aligned text is an aligned paragraph; blocks move the same way. Vertical alignment places a block in the room its page leaves. |
| `block`, `box` | `div.ts-block` / `span.ts-box` with width, height, fill, stroke, inset, radius and baseline. Strokes are drawn on the edge and take no room. |
| `rect`, `square`, `circle`, `ellipse` | `div.ts-shape` with the same properties. |
| `stack`, `columns`, `colbreak`, `pad` | Flexbox; columns that fill as Typst's do (no balancing); padding. |
| `place` | Absolutely positioned against the nearest box, block or shape; `float: true` stays in flow. |
| `v`, `h` | Fixed gaps. `v(1fr)` takes what its page leaves, `h(1fr)` what its line leaves. |
| `pagebreak` | A page break on the renderer's pages; weak ones only where the page isn't empty. |
| `move`, `rotate`, `scale`, `skew` | CSS transforms. `hide` is `visibility: hidden`. `repeat` repeats its body, clipped to the box. |
| `line` | A rule when horizontal; otherwise drawn. |
| `curve`, `polygon`, angled lines; boxes and blocks that hold them; boxes and blocks made only of `place`d pieces (diagrams, CeTZ canvases); equations with `cancel` | Inline SVG in a `.ts-frame` with `role="img"` and the text as `aria-label` (`aria-hidden` when it has no text). |
| Equations | Typst's drawing (inline ones cut where Typst breaks a line, each piece in its line as Typst places it), with the MathML for screen readers. Numbered display equations carry their number. |
| Lists, enums, terms | Typst's marker column, indents and gaps; patterns (`"a)"`, `"i."`) as written. |
| `outline` | Entries with their prefix, a row of dots and the page number, which the renderer writes once it has laid out the pages. |
| `set page(...)` | The page's size, margins, fill, header and footer, for the renderer's pages (on each block's source anchor). `counter(page).final()` reads the page count the renderer gives back. |
| `layout(f)` | Calls `f` with the page's text area. |

Inside a box (an inline element), the prelude writes `span.ts-b` instead of `div`: a `<div>` there would make the
browser close the paragraph and move everything after it out.

## Known gaps

- **Drawn content** (`.ts-frame`) is SVG: its text is in `aria-label`, not selectable. A drawing without text is hidden
  from assistive technology (`aria-hidden`), since there is nothing to read out.
- **fletcher 0.5.8** diagrams stay empty in HTML. Its CeTZ 0.3.4 canvas calls `layout` inside `context`, within the
  package, where neither the prelude's `layout` nor its drawing detection reaches. They render in the paged target.
  CeTZ 0.5 canvases (cetz, cetz-plot, alchemist) become SVG.

## Fonts

The stylesheet sets text in Typst's own fonts (Libertinus Serif, DejaVu Sans Mono for code, the engine's script fonts
for Arabic, Bengali and Devanagari) under the names `registerTypstFonts` registers them by, with the layout profile's
line box as their ascent and descent: lines are then as tall as Typst's and their baselines where Typst puts them. The
`typstream` package registers them; with `@typstream/react` or `@typstream/dom`, pass the engine's fonts (from
`@typstream/engine-wasm/fonts`) as `fonts`, and New Computer Modern Math as `mathFont` for MathML.

## API

| Export | What it is |
| --- | --- |
| [`htmlCompat`](#htmlcompat) | The plugin: prelude file, preamble, sanitizer allowances, stylesheet. |
| [`htmlCompatCss`](#htmlcompatcss) | The stylesheet for the prelude's HTML. |
| [`htmlCompatPreamble`](#htmlcompatpreamble) | Typst that imports and applies the prelude. |
| [`htmlCompatSource`](#htmlcompatsource) | The prelude's Typst source. |
| [`HTML_COMPAT_PATH`](#html_compat_path) | Where the prelude is mounted: `"/@typstream/html-compat.typ"`. |
| [`KNOWN_HTML_WARNINGS`](#known_html_warnings) | Warnings the prelude can't prevent. |

### htmlCompat

```ts
const htmlCompat: TypstreamPlugin;
```

html-compat as a typstream plugin, with key `"html-compat"`:

| Facet | Value |
| --- | --- |
| `engine.files` | `{ [HTML_COMPAT_PATH]: htmlCompatSource }` |
| `engine.preamble` | `htmlCompatPreamble` |
| `sanitize` | Allows `div`, `span` and `svg`; `class`, `style`, `role` and `aria-label` on `div` and `span`; `class` on `ol`. |
| `stylesheets` | `[htmlCompatCss]` |

`typstream`'s `<Typstream>` puts it first, before the plugins you pass. See [Plugins](/docs/concepts/plugins).

### htmlCompatCss

```ts
const htmlCompatCss: string;
```

The stylesheet for the prelude's HTML, plus Typst-like defaults for tables and math. Its rules are scoped to an element
with class `typstream` (the renderer's root) and have zero specificity (`:where`), so your own rules win. The plugin
carries it; use it directly when you render the engine's HTML yourself, for example
`<div class="typstream">` with `<style>` holding this text.

### htmlCompatPreamble

```ts
const htmlCompatPreamble: string;
// '#import "/@typstream/html-compat.typ": html-compat, layout\n#show: html-compat\n'
```

Typst to put before a document: imports the prelude and applies it with `#show: html-compat`. It also replaces
`layout`, which HTML export would drop, with one that reports a fixed text width in HTML. The rules act only on the HTML
target, so the same preamble is safe for paged output.

### htmlCompatSource

```ts
const htmlCompatSource: string;
```

The prelude's Typst source. Mount it at `HTML_COMPAT_PATH`.

### HTML_COMPAT_PATH

```ts
const HTML_COMPAT_PATH = "/@typstream/html-compat.typ";
```

Where the engine mounts the prelude in its virtual file system. Without a plugin-aware layer, for example with
`@typstream/engine-wasm` directly, mount it and prepend the preamble yourself:

```ts
import { HTML_COMPAT_PATH, htmlCompatPreamble, htmlCompatSource } from "@typstream/html-compat";

engine.set_source(HTML_COMPAT_PATH, htmlCompatSource);
engine.set_source("/main.typ", htmlCompatPreamble + documentText); // shift diagnostic spans by the preamble's length
const { html } = engine.compile_html();
```

With `@typstream/node`, pass the same pair as options:
`{ files: { [HTML_COMPAT_PATH]: htmlCompatSource }, preamble: htmlCompatPreamble }`.

### KNOWN_HTML_WARNINGS

```ts
const KNOWN_HTML_WARNINGS: readonly string[]; // ["page set rule was ignored during HTML export"]
```

Warnings the prelude can't prevent, as message substrings. Filter them out when you show HTML-target diagnostics, or
count them as expected in tests.

```ts
const shown = diagnostics.filter((d) => !KNOWN_HTML_WARNINGS.some((w) => d.message.includes(w)));
```

## See also

- [Render targets](/docs/concepts/render-targets): HTML versus paged output.
- [Theming](/docs/guides/theming): styling the HTML target.
- [Typst packages](/docs/guides/typst-packages): CeTZ and the other packages in HTML.
- [Compatibility](/docs/resources/compatibility): what renders where.
- [@typstream/universe](/docs/reference/universe): the packages whose drawings become SVG.
