typstream

@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-compat

Example

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:

idle
#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.

ElementHTML
TextSize, 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.
SpacingParagraph, 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, tableA 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.
alignAligned text is an aligned paragraph; blocks move the same way. Vertical alignment places a block in the room its page leaves.
block, boxdiv.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, ellipsediv.ts-shape with the same properties.
stack, columns, colbreak, padFlexbox; columns that fill as Typst's do (no balancing); padding.
placeAbsolutely positioned against the nearest box, block or shape; float: true stays in flow.
v, hFixed gaps. v(1fr) takes what its page leaves, h(1fr) what its line leaves.
pagebreakA page break on the renderer's pages; weak ones only where the page isn't empty.
move, rotate, scale, skewCSS transforms. hide is visibility: hidden. repeat repeats its body, clipped to the box.
lineA 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 cancelInline SVG in a .ts-frame with role="img" and the text as aria-label (aria-hidden when it has no text).
EquationsTypst'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, termsTypst's marker column, indents and gaps; patterns ("a)", "i.") as written.
outlineEntries 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

ExportWhat it is
htmlCompatThe plugin: prelude file, preamble, sanitizer allowances, stylesheet.
htmlCompatCssThe stylesheet for the prelude's HTML.
htmlCompatPreambleTypst that imports and applies the prelude.
htmlCompatSourceThe prelude's Typst source.
HTML_COMPAT_PATHWhere the prelude is mounted: "/@typstream/html-compat.typ".
KNOWN_HTML_WARNINGSWarnings the prelude can't prevent.

htmlCompat

const htmlCompat: TypstreamPlugin;

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

FacetValue
engine.files{ [HTML_COMPAT_PATH]: htmlCompatSource }
engine.preamblehtmlCompatPreamble
sanitizeAllows 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

On this page