Typst projects

Oleafly comes with Typst 0.15.1 and the Tinymist 0.15.8 language server, so a new Typst project compiles with nothing to install. This page covers what you can change: which Typst a project uses, where its packages and fonts come from, and how a single source builds more than one PDF. For syntax and the toolbar, start with Write in Typst.

Typst versions

Open Settings → Engines → Typst. The first card is Typst (built in), the version that ships with the app. If a typst is already installed on your computer, on your PATH, in Homebrew’s folder or in ~/.cargo/bin, a second card shows it as Typst on this computer. Projects that pin that exact version can compile with it.

Below them, Versions lists Typst 0.11 to 0.15, newest first. Each row gives the release date, the download size, where the copy comes from (Built in, Downloaded or System) and, once installed, the Tinymist release it uses.

• Install downloads that version. Oleafly tries its own mirror first and GitHub second, and checks the archive and the program inside it against SHA-256 checksums built into the app. A file that doesn’t match is thrown away, and a failed or cancelled install leaves nothing behind. Downloads live in ~/.oleafly/toolchains/typst/.
• The round button at the left of an installed row makes that version the default.
• Remove deletes a downloaded version. The default can’t be removed, so pick another default first.

The default version and project pins

New Typst projects pin the default version. So do projects made from a template, imported projects and linked folders. A pin is stored in the project’s project.json as a version number, not a path, so it still works after you move the project or open it on another computer.

Changing the default later doesn’t move existing projects. That is deliberate: a pinned paper keeps the same line breaks and page count when Oleafly ships a newer Typst.

To change one project’s version, open the arrow beside Recompile and look under Typst version (this project). Default follows the version chosen in Settings and clears the pin. The other entries are the versions installed on this computer, marked [built in] or [system] where that applies. To use a version that isn’t listed, install it in Settings first.

When a pinned version is missing

If you open a project that pins a version this computer doesn’t have, Oleafly won’t quietly build it with a different Typst. The compile stops with “Typst 0.13.1 is not installed”, and the preview offers two buttons:

• Download Typst 0.13.1 installs the pinned version and compiles again. It appears when the version is one Oleafly offers.
• Use Typst 0.15.1, named after your default version, clears the pin and compiles again with the default.

The compile menu marks the pin [not installed] until you choose one of them.

Try a newer version before switching

With a Typst project open, the Typst tab in Settings shows Try a newer version whenever a newer Typst is installed. Choose Check with Typst 0.15.1 (or whichever version it names). Oleafly builds the project twice in temporary folders, once with the project’s current version and once with the newer one. Nothing in your project changes.

The report shows whether each build succeeded, its page count, and its errors and warnings. It tells you if the page count changes. New in Typst 0.15.1 lists messages that only the newer version reports, and No longer reported by Typst 0.15.1 lists the ones that go away. Click a message to open its file at that line.

If you like what you see, Switch to Typst 0.15.1 pins the project to the newer version. Check again reruns both builds after you fix something.

The language server follows the version

Tinymist powers completion, hover help, rename and formatting in Typst files (see Code intelligence). Each Typst minor version has its own Tinymist release, and a project talks to the one that matches its Typst version.

The built-in Tinymist covers Typst 0.15. When you open a project pinned to an older line, Oleafly downloads the matching Tinymist in the background, with the same checksum check, and the status reads “Downloading Tinymist 0.13.30 to match this project’s Typst version.” If the download fails, Oleafly tries again later. When Settings finds Tinymist downloads that no installed Typst needs any more, it offers Remove unused language server downloads.

What each version can do

Older versions exist so that projects started on them keep building the same way. Some features depend on what the Typst version itself supports:

Feature	0.11	0.12	0.13	0.14 and later
Project fonts only	No	Yes	Yes	Yes
Reproducible build	No	Yes	Yes	Yes
Page ranges in PNG and SVG export	No	Yes	Yes	Yes
PDF/A	No	PDF/A-2b	PDF/A-2b, PDF/A-3b	All PDF/A levels Typst offers
PDF/UA-1	No	No	No	Yes
HTML export, and Word or Markdown export through Typst’s HTML	No	No	Yes	Yes
Source and PDF sync	No	No	Yes	Yes
Tagged PDF on every compile	No	No	No	Yes

The font picker can say where each font comes from on Typst 0.15 and later. When a setting can’t apply to the version a project uses, the compile menu marks it Needs a newer Typst.

Packages from Typst Universe

Choose Typst packages, the package icon at the right end of the Typst toolbar. Search Typst Universe by name, keyword or category. Each package shows its latest version, and a package that needs a newer Typst than the project uses says so: “Needs Typst 0.14.0. This project uses Typst 0.13.1.”

Insert import writes the #import line at the top of the open Typst file. Copy import puts it on the clipboard instead.

Typst downloads a @preview package the first time a compile imports it and keeps it in a cache that every project shares. The package list is cached too. Offline, the dialog shows the last list it fetched, with its date.

Newer releases

When an import names an older release than the one on Typst Universe, its version number is underlined with a hint such as “cetz 0.4.2 is available. This import uses 0.3.4.” The hint card offers Update to 0.4.2, which changes the version number in the import. Read the package’s changelog before you accept it, because a new release can change how the package is called. Hovering over an import also offers Open on Typst Universe.

Keep packages inside the project

Under Project packages in the same dialog, Vendor packages into project copies every package the project imports into a typst-packages folder at the top of the project. It also copies the packages those packages import, and turns on Use packages from the project folder.

From then on Typst looks in typst-packages first. A vendored project compiles offline and on any computer, and the folder can go into Git with your source. A package you haven’t vendored still comes from the shared cache.

If a package isn’t in the cache yet, the dialog names it: “These packages aren’t in the package cache: …”. Compile once while online, then vendor again.

Offline mode

With Offline mode on in Settings → General, Typst can’t download anything. Every package has to be in the shared cache or in typst-packages already. If one isn’t, the compile fails and the message names the package, so you know what to fetch the next time you’re online.

Fonts

Typst finds fonts in three places: the fonts built into Typst, the fonts installed on your computer, and font folders inside the project. Put font files in a folder named fonts at the top of the project, and both the compiler and the language server pick them up. Extra folders can be listed under typst.font_paths in project.json. Folders outside the project are ignored.

Under Fonts (this project) in the compile menu, Use system fonts is the default. Project fonts only stops Typst from reading the fonts installed on this computer. The PDF then comes out the same on every machine, and if the document asks for a font the project doesn’t include, you find out on your own computer instead of a co-author’s.

To choose a body font, open Document settings, the sliders icon on the Typst toolbar, and click Body font. The list shows every family Typst can find with the project’s current font settings. On Typst 0.15 and later each family carries a Project, System or Built in label. Pick one and choose Apply, and Oleafly writes it into the document’s #set rules.

Build variants and sys.inputs

A build variant is a named set of values your document reads through sys.inputs. Use variants when one source needs to produce different PDFs, such as an anonymous review copy and a camera-ready copy, or a draft with a watermark.

The document decides what each value does. Values always arrive as text:

#let draft = sys.inputs.at("draft", default: "false") == "true"

#if draft [*Draft. Do not circulate.*]

To set up a variant:

1. Open Document settings and scroll to Build variants.
2. Choose Add variant and name it, for example review.
3. Choose Add value, then enter draft under Name and true under Value.
4. Choose Apply.
5. Open the compile menu. Variant (this project) now lists review. Pick it and compile.

No variant builds without any variant values. The variant you pick is remembered on this computer only, so a co-author can build a different one from the same project. The variants themselves are saved in project.json. Exports use the selected variant too.

Values that every build should get go under typst.inputs in project.json. When a variant sets a value with the same name, the variant wins.

Reproducible builds

Under Build (this project) in the compile menu, Reproducible build makes the same sources give the same PDF on any computer. It uses only project fonts and Typst’s built-in fonts, and it dates the PDF to the last Git commit. A project that isn’t a Git repository gets a fixed date of 1 January 1970.

This matters when a PDF has to match a checksum, for an archive deposit or a comparison in CI. It needs Typst 0.12 or later. While it’s on, Use system fonts is unavailable. Standard build is the default.

Live preview with Auto compile

Set Auto compile to On in the compile menu. In a Typst project, Oleafly then keeps one Typst process running. The open file saves itself a moment after you stop typing, Typst compiles it, and the preview reloads at the same scroll position. There is no separate live preview setting: Auto compile is the live preview.

While Typst starts, the menu shows “Starting Typst”. If it stops after repeated errors, the menu says so, and your next edit starts it again. Stop compilation ends the process, and the next edit starts it again too. LaTeX and Markdown projects handle Auto compile differently; see Compiling.

Build from the command line

oleaflyc, Oleafly’s command-line tool, builds projects without opening the app. For now it’s built from the desktop source code and doesn’t ship with the app.

For a Typst project, oleaflyc build and oleaflyc watch read project.json and use the same settings as the app: the pinned version, vendored packages, font folders, the system fonts switch, inputs and reproducible builds.

• --variant review builds a variant. A name the project doesn’t define stops the build, and the message lists the variants it does have.
• --offline blocks package downloads, like Offline mode in the app.
• A pinned project builds only with that exact Typst. The CLI looks at OLEAFLY_TYPST, then the versions the app downloaded, then the typst beside the CLI, then your PATH. If none reports the pinned version, the build stops before Typst runs and tells you how to install it.
• A project without a pin uses OLEAFLY_TYPST, the bundled Typst or the one on your PATH, in that order. It doesn’t read the default version from Settings.
• oleaflyc doctor lists every Typst it found and the settings a build would use. It fails when the pinned version is missing.

If a setting can’t apply to the Typst being used, the build prints a note, for example that Typst 0.11.1 can’t ignore system fonts. Errors in the terminal include Typst’s own hints.

Convert a LaTeX project to Typst

Open the LaTeX project, press ⌘K (Ctrl+K) and run Convert to a Typst project. Give the new project a name and choose Convert. The LaTeX project stays exactly as it was. Oleafly builds a separate Typst project from it:

• Pandoc converts the text, math, figures and tables. If Pandoc isn’t set up yet, Oleafly sets it up first.
• Each file brought in with \input, \include or \subfile becomes its own .typ file.
• BibTeX files are copied unchanged.
• Typst compiles the new project to check it.

The report then says whether the project compiles and counts what was converted: source files, figures, tables, display equations, cross-references, formulas the math converter repaired, and copied files, along with the bibliography style it chose. Needs attention lists what to fix by hand, such as a missing include or image, an image format Typst can’t show, math the converter couldn’t handle, a BibTeX style with no Typst match, or a label on one line of a multi-line equation, which now points at the whole equation. Compile errors and warnings link to their file and line.

Choose Open the Typst project to switch to it. The new project pins your default Typst version. While Oleafly stays open, Show the Typst conversion report in the command palette brings the report back.

To convert a single file instead of a whole project, use LaTeX to Typst on the Tools page.

Related pages

• Write in Typst for the toolbar and a first document.
• Compiling for logs, the compile menu and offline mode.
• Export and convert a project for PNG, SVG, HTML, PDF/A and PDF/UA.
• Preflight checks for the checks that read Typst sources.