# ox-typst

**Repository Path**: dylanyang00/ox-typst

## Basic Information

- **Project Name**: ox-typst
- **Description**: Org-mode to Typst exporter.
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-29
- **Last Updated**: 2026-02-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

#+title: ox-typst.el - Typst Back-End for Org Export Engine
#+language: en

#+html: <a href="https://melpa.org/#/ox-typst"><img alt="MELPA" src="https://melpa.org/packages/ox-typst-badge.svg"/></a>

Org-mode to Typst exporter.

* Install

The package is available trough Melpa.

#+BEGIN_SRC elisp
  (use-package ox-typst
    :after org)
#+END_SRC

** Recipe

For packages which can use recipes (e.g. Elpaca), the following snippet can be
used.

#+BEGIN_SRC elisp
  (use-package ox-typst
    :after org
    :ensure (ox-typst :host github :repo "jmpunkt/ox-typst"))
#+END_SRC

* Usage

If you use =org-export-dispatch=, then the Typst exporter is
available with the =y= prefix.

* Insert Typst Code

Typst code can be directly used within org-mode by using the
=#+TYPST:=. The provided string is not escaped by the exporter and is
put directly into the output file.

#+BEGIN_SRC org
,#+TYPST: #set page(paper: "a4")
#+END_SRC

Alternatively use an export block.

#+BEGIN_SRC org
,#+BEGIN_EXPORT typst
#set page(paper: "a4")
,#+END_EXPORT
#+END_SRC


* Themes

Use Typst rules to change the appearance of your document. Include
these rules at the top level of the document or above the target
element. It might be useful to create a file containing Typst rules
and include them like below.

#+BEGIN_SRC org
,#+INCLUDE: "./my-theme.typ" export typst
#+END_SRC

Alternatively, rules can be put into an export block ([[*Insert Typst Code][Insert Typst Code]]).

* Cite

Typst supports citing and bibliography by default.

#+BEGIN_SRC org
,#+BIBLIOGRAPHY: ./test.bib
,#+print_bibliography: :title Custom Bibliography Title
,#+CITE_EXPORT: typst apa
#+END_SRC

Supported styles are listed [[https://typst.app/docs/reference/model/bibliography/][here]]. The second argument (in this case
=apa=) is stringified and put into the =bibliography= function as the
style argument (like =bibliography("./test.bib", style: "apa")=).

* Math

Org-mode provides a built-in syntax for LaTeX math. However, Typst uses a
different syntax for math. The syntax of these two modes is incompatible.

As a user you have two options: use LaTeX syntax and convert it, or use Typst
syntax. By setting =org-typst-from-latex-fragment= and
=org-typst-from-latex-environment= you can control how the Org elements are
translated. For now, you have to choose between either of them. Mixing them
throughout the document is not possible.

For Typst syntax it is best to set these to =#'org-typst-from-latex-with-naive=.

#+BEGIN_SRC elisp
  (setq org-typst-from-latex-environment #'org-typst-from-latex-with-naive
        org-typst-from-latex-fragment #'org-typst-from-latex-with-naive)
#+END_SRC

When you are using the LaTeX syntax, you will need Pandoc to convert the syntax
to Typst.

#+BEGIN_SRC elisp
  (setq org-typst-from-latex-environment #'org-typst-from-latex-with-pandoc
        org-typst-from-latex-fragment #'org-typst-from-latex-with-pandoc)
#+END_SRC

If none of these methods work for you, then you can always provide your own
translation functions.

You can also take a look at the files in =tests/math/= to get an idea on how to
use this functionality. Notice, that in order to use =BIND= you have to enable
it in Org.

#+BEGIN_SRC elisp
  (setq org-export-allow-bind-keywords t)
#+END_SRC

* Examples

Take a look at =test/test.org= to get an idea how to use the different
org-mode statements with Typst. For real examples look in the
=examples= folder.

** Writing a Letter

If you want to write a letter using a third party package
(e.g. https://github.com/Sematre/typst-letter-pro), then take a look
at =examples/letter.org=.

** Tests

If you want more examples, maybe look into the tests. The tests contain small
Org snippets and their Typst representation.

* Development

** Tests

The tests contain small Org snippets and their Typst output. Changing the
exporter requires to re-run the exporter on all Org files. One should manually
check if the output matches the expectation. If the output matches the
expectation, the newly generated files become the new golden output.

*** Generate

#+BEGIN_SRC org
emacs --batch -l tests/test.el -f org-typst-test-generate
#+END_SRC

*** Run

#+BEGIN_SRC org
emacs --batch -l tests/test.el -f org-typst-test-run
#+END_SRC

*** With Emacs

It is also possible to use these functions inside Emacs. Navigate to the
=tests/test.el= file and run =eval-buffer=. The =ox-typst.el= file is
automatically re-loaded from the current Git repository when evaluating the test
buffer.