org-typst-preview

Asynchronous native Typst math previews for Org mode, using the interface you already know from org-latex-preview.

Why

Typst and LaTeX should be able to coexist in one Org document without guessing which language a $...$ fragment contains. This package therefore uses unambiguous custom boundaries while keeping Org’s familiar preview commands, key bindings, colors, cache location, and image overlay conventions. The renderer itself is an asynchronous Typst-to-SVG pipeline.

Write native Typst:

Inline math: #(sum_(i=1)^n i#).

Display math uses square boundaries:

#[
  sum_(i=1)^n i = (n(n+1))/2
#]

Features

• Native Typst math inside #(...#) and #[...#] boundaries.
• LaTeX $...$ fragments remain untouched and can coexist in the same file.
• Shared C-c C-x C-l binding for Typst and LaTeX, preserving org-latex-preview behavior and prefix arguments.
• Fully asynchronous rendering with a configurable concurrency limit.
• Content-addressed SVG cache and coalescing of identical in-flight jobs.
• Stale-result protection when a formula changes before compilation finishes.
• Foreground, background, and scale inherited from org-format-latex-options.
• Cache location inherited from org-preview-latex-image-directory.
• Optional idle auto-preview mode.
• The latest Typst compiler error is kept in a dedicated diagnostics buffer.
• Temporary source files are created next to local Org files, allowing relative imports in org-typst-preview-preamble, and removed after compilation.

Requirements

• Emacs 30.1 or newer.
• The Typst CLI available on exec-path.
• Emacs built with SVG image support.

Installation

straight.el

(use-package org-typst-preview
  :straight (:host github :repo "roife/org-typst-preview")
  :after org
  :hook (org-mode . org-typst-preview-mode))

With automatic re-rendering after edits:

(use-package org-typst-preview
  :straight (:host github :repo "roife/org-typst-preview")
  :after org
  :hook (org-mode . org-typst-preview-auto-mode))

package-vc

On Emacs 29 or newer:

(unless (package-installed-p 'org-typst-preview)
  (package-vc-install
   '(org-typst-preview
     :url "https://github.com/roife/org-typst-preview")))

Usage

Enable org-typst-preview-mode in an Org buffer. The usual Org command previews both Typst and LaTeX. At point, it uses the renderer for that formula; region, section, and whole-buffer requests handle both languages:

Input	Action
C-c C-x C-l	Toggle Typst or LaTeX at point
C-c C-x C-l	Preview region or section
C-u C-c C-x C-l	Clear region or section
C-u C-u C-c C-x C-l	Preview both in the buffer
C-u C-u C-u ...	Clear both in the buffer

The following commands are also available:

• M-x org-typst-preview
• M-x org-typst-preview-clear
• M-x org-typst-preview-refresh-buffer
• M-x org-typst-preview-show-errors

Completed previews use Org’s org-latex-overlay type. Consequently, org-clear-latex-preview clears both kinds of preview and is not remapped by the minor mode. Use org-typst-preview-clear to clear only Typst previews.

Configuration

The package deliberately reuses these Org settings:

;; Used when the package-specific options below are nil.
(plist-put org-format-latex-options :scale 1.2)
(setq org-preview-latex-image-directory
      (expand-file-name "org/formulas/" user-emacs-directory))

Package-specific options include:

(setq org-typst-preview-max-processes 4
      ;; nil means inherit Org's :scale option.
      org-typst-preview-scale nil
      org-typst-preview-font-size 11.0
      ;; nil means reuse org-preview-latex-image-directory.
      org-typst-preview-image-directory nil
      org-typst-preview-preamble
      "#import \"@preview/physica:0.9.5\": *")

When a relative file is imported by the preamble, it is resolved relative to the Org buffer directory because temporary Typst source files are created there.

Delimiters

Parentheses select an inline formula. Square brackets select a display formula. Write only the Typst math body inside them; the package adds Typst’s native dollar delimiters before compilation:

Inline: #(integral_0^1 x^2 dif x#)

Block:

#[
  integral_0^1 x^2 dif x = 1/3
#]

The complete boundary pairs are:

Kind	Open	Close
Inline	#(	#)
Display	#[	#]

Prefix an opening boundary with a backslash when it should remain literal: \#(not a formula#). Boundaries inside Org source, example, export, code, verbatim, comment, property, and fixed-width content are ignored.

Export

When org-typst-preview-mode is active, Typst export is handled automatically. Before a Typst backend parses its temporary export buffer, inline boundaries become Typst export snippets and display boundaries become Typst export blocks. The original Org buffer is never modified. This works with ox-typst and does not depend on its LaTeX conversion setting.

Other export backends keep the custom boundaries unchanged. Set org-typst-preview-export-to-typst to nil to disable the transformation.

Security

Previewing invokes a local compiler. The package refuses to run when Org marks content as untrusted. Setting org-typst-preview-when-risky to non-nil opts out of that protection.

Development

Run the unit and compiler integration tests with:

make check

Integration tests are skipped when the Typst executable is unavailable.

License

GPL-3.0-or-later.