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.
• Drop-in command behavior for org-latex-preview, including its prefix arguments and the standard C-c C-x C-l binding.
• 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 now uses Typst:

Input	Action
C-c C-x C-l	Toggle formula at point
C-c C-x C-l	Preview the active region
C-u C-c C-x C-l	Clear the current section
C-u C-u C-c C-x C-l	Preview the whole buffer
C-u C-u C-u ...	Clear the whole 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 can clear them too when called outside the minor-mode command remapping.

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.