Typst Preview
Quarto Wizard compiles the Typst block under the cursor and shows the image beside the editor. The preview uses the Typst binary that ships inside Quarto, so it needs no other program.
Where the Preview Appears
quartoWizard.typstPreview.surface is a list of surfaces. Name one or both to show them at the same time.
panelshows the image in a panel beside the editor. The panel follows the cursor while it is open, and it scrolls, so a tall image is never cut.hovershows the image when the pointer rests on a block. A hover cannot scroll, so the image is scaled down toquartoWizard.typstPreview.maxHeight.
An empty list shows no image, and offers no code lens.
There is no preview inside the text of the document. The editor gives an extension no way to make a line taller. An image drawn after a block covers the lines below it.
Quarto Wizard: Preview Typst Block opens the panel whatever the list holds. The one exception is an empty list, where the command names the setting instead of opening anything.
The Three Kinds of Block
Three fences are spelled almost the same way and behave differently. The code lens above each block says which kind it is.
| Fence | What Quarto does with it | What the preview compiles |
|---|---|---|
```typst |
Highlights it, and never executes it. | The body, under the preview’s own page setup and colours. |
```{=typst} |
Passes it to the Typst output untouched. | The body, under every raw block above it in the document. |
```{typst} |
Executes it through the typst-render extension. | The body, under the options and the colours of that extension. |
A {typst} cell needs typst-render installed in the project. Without it the preview says so and shows nothing. A cell compiled with guessed options shows an image the render does not produce, which is worse than no image at all.
The other two kinds need no extension.
Inline Forms
An inline span takes the same three kinds a fence takes.
`{typst} #calc.pi` is a cell, which the typst-render extension renders to an image. An inline cell reads the global options only. It carries no //| option line, because there is no line above it to hold one.
`#calc.pi`{.typst} is plain code, the inline counterpart of a ```typst block. Quarto styles it and nothing renders it, so the preview needs no extension and applies no option of a cell.
`#a`{=typst} is a raw passthrough, the inline counterpart of a ```{=typst} block. It is passed to the Typst output untouched, and the prose around it is not compiled.
An inline unit is shown in the panel and in a hover, the same surfaces a block uses. It carries no code lens, since a code lens needs a line of its own above a block, and an inline span has none.
Colours
A plain block and a raw block take their colours from quartoWizard.typstPreview.foreground and quartoWizard.typstPreview.background. Both accept three forms. auto follows the editor theme, none writes no colour, and a Typst colour expression is written as it stands.
A {typst} cell keeps the colour contract of typst-render instead, so the image matches the render rather than the editor. A cell that resolves a colour from a brand needs a side of the brand, and the preview follows the editor theme. The filter itself always takes the light side, so this is a deliberate difference. A brand-mode in the document wins over the theme. Quarto Wizard: Switch Typst Preview Brand Mode wins over both. The side you select holds until you select the other one, or until you refresh the preview. The panel header always names the side in force.
Paths
The preview sends the block to Typst through standard input. A path inside the block therefore resolves against the compile root, and not against the file that holds the block.
The preview uses the root that a render uses. For a {typst} cell, the root is the root value under extensions.typst-render. Its default is the directory of the document. A value that starts with / resolves from the project root. A plain block and a raw block always use the directory of the document.
A {typst} cell also compiles with the font-path, the package-path and the input values of the extension. A font path or a package path that starts with / resolves from the project root. Every other value stays relative, and the compile runs from the project root.
Opening a File an Option Names
A file: option and a preamble: option name a file. Hold Ctrl, or Cmd on macOS, and select the value to open that file in the editor. The link appears only when the file is there.
The two options accept the same paths as the preview. A value that starts with / resolves from the project root. Every other value resolves from the directory of the document. A preamble: entry that does not end with .typ is inline Typst code, so it is not a link.
file: is a cell option alone. preamble: also works in the front matter of a document, and in _quarto.yml or _metadata.yml under typst-render.
When a path in a document leads to no file, the editor shows a warning on the value. A relative path in a configuration file gets no warning. Every document that reads the file resolves the path from its own directory, so the file itself cannot say where the path leads.
Commands
| Command | What it does |
|---|---|
| Preview Typst Block | Compiles the block under the cursor and shows it in the panel. |
| Refresh Typst Preview | Compiles the preview again, and forgets the image, the metadata files and the brand mode you selected. |
| Switch Typst Preview Brand Mode | Shows the other side of the brand of a {typst} cell. |
| Copy Typst Preview Source | Copies the exact source the preview compiled to the clipboard. |
The commands reference lists the identifier of each one.
Copy Typst Preview Source is what makes a failure reportable. Paste the source into a file, run typst compile on it, and the failure is reproduced outside Visual Studio Code.
Settings
The configuration reference describes every setting. All of them are read for each folder, so a multi-root workspace can hold a different answer per folder.
What the Preview Does Not Do
The preview is an authoring aid, and it is not a render. Two differences are known and are stated beside the image when they apply.
- A raw block reaches Typst through the document template during a render. The template contributes imports, show rules and set directives that the preview cannot apply, so a block that depends on them looks different.
- The preview compiles one block on its own. A plain block that uses a value from another block therefore fails.
These are out of scope for this version.
- The
typst_define()payload of the R and Python helpers. It lives in metadata that a Quarto engine produces during a render, which the preview cannot see. output: asis, whose cell inherits the page of the document being rendered.pages, and any output of more than one page. The preview shows the first page.- Native
format: html. The preview always compiles to SVG, whateverformatsays, and the panel header says so when the format is something else.
When the Preview Is Not Offered
The preview runs a compiler over the content of the workspace, so it is off in an untrusted workspace. It is also off when Quarto is absent, or when the Quarto installation ships no Typst binary. In each case the extension says so once and offers no surface. The Quarto Wizard log records the path of every attempt.