@typstream/html-compat
A Typst prelude and stylesheet that keep grids, alignment, shapes, placement and drawings in Typst's HTML export.
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 compares the two.
Install
npm install @typstream/html-compatExample
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:
#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 placed 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 inaria-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
layoutinsidecontext, within the package, where neither the prelude'slayoutnor 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 | The plugin: prelude file, preamble, sanitizer allowances, stylesheet. |
htmlCompatCss | The stylesheet for the prelude's HTML. |
htmlCompatPreamble | Typst that imports and applies the prelude. |
htmlCompatSource | The prelude's Typst source. |
HTML_COMPAT_PATH | Where the prelude is mounted: "/@typstream/html-compat.typ". |
KNOWN_HTML_WARNINGS | Warnings the prelude can't prevent. |
htmlCompat
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.
htmlCompatCss
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
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
const htmlCompatSource: string;The prelude's Typst source. Mount it at HTML_COMPAT_PATH.
HTML_COMPAT_PATH
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:
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
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.
const shown = diagnostics.filter((d) => !KNOWN_HTML_WARNINGS.some((w) => d.message.includes(w)));See also
- Render targets: HTML versus paged output.
- Theming: styling the HTML target.
- Typst packages: CeTZ and the other packages in HTML.
- Compatibility: what renders where.
- @typstream/universe: the packages whose drawings become SVG.
Edu vocabulary
Every function and template in @typstream/edu (@typstream/edu:0.1.0), with its signature, parameters and a live example.
@typstream/universe
The Typst Universe packages typstream allows by default (CeTZ, fletcher, cetz-plot, physica, unify, chemformula, alchemist), vendored with integrity hashes as a plugin.