ox-typst.el - Typst Back-End for Org Export Engine

Org-mode to Typst exporter.

Install

The package is available trough Melpa.

(use-package ox-typst
  :after org)

Recipe

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

(use-package ox-typst
  :after org
  :ensure (ox-typst :host github :repo "jmpunkt/ox-typst"))

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.

#+TYPST: #set page(paper: "a4")

Alternatively use an export block.

#+BEGIN_EXPORT typst
#set page(paper: "a4")
#+END_EXPORT

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.

#+INCLUDE: "./my-theme.typ" export typst

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

Cite

Typst supports citing and bibliography by default.

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

Supported styles are listed 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.

(setq org-typst-from-latex-environment #'org-typst-from-latex-with-naive
      org-typst-from-latex-fragment #'org-typst-from-latex-with-naive)

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

(setq org-typst-from-latex-environment #'org-typst-from-latex-with-pandoc
      org-typst-from-latex-fragment #'org-typst-from-latex-with-pandoc)

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.

(setq org-export-allow-bind-keywords t)

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

emacs --batch -l tests/test.el -f org-typst-test-generate

Run

emacs --batch -l tests/test.el -f org-typst-test-run

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.