Choose a document engine
Understand how LaTeX, Typst, Markdown, Quarto, and Calepin documents become a PDF, and choose the compiler your project needs.
An engine turns your source into the document people read. Choose the document language when you create a project. For a LaTeX project, you can also choose which LaTeX compiler runs the build.
Choose a language
Section titled “Choose a language”| Your work | Start with | How it becomes a PDF |
|---|---|---|
A journal submission, an established thesis class, or an existing .tex project | LaTeX | Tectonic, or a compiler run through latexmk |
| A new paper, report, or resume with concise typesetting syntax | Typst | The built-in Typst 0.15.1, or another Typst version the project pins |
| A prose draft, notes, or a document you want to export to several formats | Markdown | Pandoc converts the source to LaTeX; Tectonic produces the PDF |
| An analysis report, article, or slide deck whose R, Python, or Julia code produces its results | Quarto | Quarto renders .qmd or .Rmd files to a PDF, a web page, or slides |
| A Typst document with code chunks | Calepin | Calepin runs the code, then the built-in Typst builds the PDF |
The choice determines the editor toolbar, source syntax, and available export formats. Changing a LaTeX compiler does not translate the document into Typst or Markdown. To move a LaTeX project to Typst, convert it into a new Typst project.
Tectonic
Section titled “Tectonic”Use Tectonic for a straightforward LaTeX setup. It comes with Oleafly, downloads the TeX packages a build needs, and caches them for later builds. Start here when your template does not require a particular compiler.
Compile once while online before traveling. A cached project can compile offline; a new package may still need a download. Enable Settings → General → Offline mode to tell Tectonic to use its cache.
pdfLaTeX
Section titled “pdfLaTeX”Choose pdfLaTeX when a publisher or existing project specifies it. It follows the traditional LaTeX workflow and is a useful match for older classes and package combinations. It needs a TeX distribution with latexmk installed.
XeLaTeX
Section titled “XeLaTeX”Choose XeLaTeX for a project that asks for it, particularly one using fontspec, OpenType fonts, or multilingual text. Make sure the fonts named by the source are installed or included with the project. It also runs through latexmk.
LuaLaTeX
Section titled “LuaLaTeX”Choose LuaLaTeX for a template that requires it, Lua-based typesetting, or Oleafly’s tagged-PDF workflow. Tagged PDFs carry document structure that assistive technology can use. Run the preflight checks to inspect the result; the compiler choice alone does not establish the quality of the tags.
Oleafly ships Typst 0.15.1. Create a Typst project, write in .typ files, and click Recompile. There is no TeX installation to set up.
Settings → Engines → Typst can also install Typst 0.11 to 0.15 and use a Typst already installed on your computer. Each project pins its own version, so a paper keeps its layout when Oleafly moves to a newer Typst. Typst downloads packages from Typst Universe the first time a document imports them, and Offline mode limits it to packages already cached or kept in the project.
Typst has its own syntax, packages, and font handling. Typst projects covers versions, packages, fonts, and build variants. The Typst writing guide has a complete starting document and the toolbar controls.
Markdown
Section titled “Markdown”Markdown uses Pandoc to prepare a typeset document and Tectonic to build its PDF. Open Settings → Engines → Markdown to install Pandoc when it is missing. Then open your Markdown project and compile it.
Use Markdown writing for headings, lists, math, and the visual editor. The export guide explains which output formats the project offers.
Quarto
Section titled “Quarto”Quarto turns .qmd and .Rmd documents into a PDF, a web page, or slides. Oleafly uses the Quarto on your computer when it finds one. If there isn’t one, open Settings → Engines → Quarto and select Download Quarto 1.10.19. The button also shows the download’s size. Oleafly checks the download before it unpacks it and keeps the copy in its own app folder. If you compile before Quarto is there, the preview offers to install it on the spot, or Open engine settings.
The first format the document declares decides what you get:
pdf,typst, andbeamerbuild a PDF.format: typstneeds no TeX installation.pdfandbeamergo through LaTeX, so install TinyTeX from Settings → Engines → LaTeX if you don’t have TeX yet.html,revealjs, anddashboardbuild a web page. Select Open in browser in the preview to see it.
When the document declares no format, Oleafly looks for one in _quarto.yml or _metadata.yml, in the document’s folder and the folders above it up to the project’s root. With no format anywhere, Quarto builds a web page. An .Rmd file that names an R Markdown output:, such as pdf_document, gets the matching Quarto format.
The code runs in the R, Python, or Julia already on your computer. Oleafly never installs them, and Languages in the same settings tab shows the ones it found. Python code also needs Jupyter in that Python. Export offers DOCX and HTML, both rendered by Quarto. The New project dialog has two Quarto templates: Quarto article, a PDF built through Typst, and Quarto slides, a reveal.js deck.
Calepin
Section titled “Calepin”Calepin runs the code in a Typst document and puts the results in the PDF. A Calepin document is a .typ file that imports /.calepin/calepin.typ. Start one from the Calepin report template, or open the arrow beside Recompile in a Typst project and choose Calepin under Engine (this project).
Install it from Settings → Engines → Calepin the same way as Quarto, with Download Calepin 0.0.61. Calepin builds with the Typst that comes with Oleafly. A chunk whose language isn’t installed shows a short note, and the rest of the document still builds. Export offers HTML, rendered by Calepin.
Allow code in a project
Section titled “Allow code in a project”Code in a Quarto or Calepin document runs with your permissions, so it stays off in each project until you allow it. After a compile that needed code, a banner above the editor says that code is off and offers Allow code in this project. You can also open the arrow beside Recompile and choose Run code on this computer under Code (this computer). Off turns it back off. Allow code only if you trust every file in the project.
The choice applies to this computer only. It isn’t saved in the project, and changing the project’s engine turns code off again. In a shared project, Oleafly asks once more, because anyone who can edit the project can change its code.
While code is off:
- Quarto shows each chunk’s code without running it. Filters, shortcodes,
_extensions, pre-render and post-render scripts, and inline R code run code even then, so a document that uses them doesn’t compile until you allow code. - Calepin can’t skip code. Oleafly builds the PDF with plain Typst from the results Calepin stored the last time it ran. If there are none, the compile stops and asks you to allow code.
A folder you open in place also has to be trusted before Quarto or Calepin can compile it. Source and PDF sync isn’t available for either engine.
Set a default for new projects
Section titled “Set a default for new projects”Open Settings → Engines → LaTeX and choose Default compile engine: Tectonic (built in) or latexmk (system TeX). Every LaTeX project you make after that starts on it:
- A blank project or a template from the New project dialog, and a research project.
- An imported ZIP, folder, arXiv paper, or GitHub repository.
- A document you convert into a LaTeX project, such as a Word file or a PDF.
The engine is written into the project’s project.json, so a coauthor who opens the project compiles it the same way. An imported project that names pdfLaTeX, XeLaTeX, or LuaLaTeX keeps that compiler when it lands on latexmk. An existing project’s saved compiler remains its own choice.
A folder you open in place with no engine of its own follows the default once you trust it. Until then it shows and compiles on Tectonic. Oleafly writes nothing into the folder either way.
For Typst, open Settings → Engines → Typst and choose the default version. New Typst projects pin the version that is the default when you create them. Changing the default later does not move existing projects.
Change the current project’s compiler
Section titled “Change the current project’s compiler”Open the arrow beside Recompile in the project toolbar. In a LaTeX project, choose Tectonic, Auto, pdfLaTeX, XeLaTeX, or LuaLaTeX under Compiler (this project), then compile. Read the log if a template needs a package or font that the selected installation does not have.
In a Typst project, the same menu has Typst version (this project) instead. Pick an installed version, or Default to follow Settings. Its Engine (this project) group switches the document between Typst and Calepin.
Detect an existing TeX distribution
Section titled “Detect an existing TeX distribution”Open Settings → Engines → LaTeX and review the detected toolchain. Oleafly checks for a complete compiler setup, including latexmk and the supporting tools. A partial system installation does not take priority over a working managed installation.
Install managed TinyTeX
Section titled “Install managed TinyTeX”Use the install control in the LaTeX engine settings if you need a traditional compiler and do not have one. Oleafly downloads its own TinyTeX installation under ~/.oleafly/tinytex; administrator access is not required. Allow roughly 250 MB for the initial download and additional space for packages.
Manage packages
Section titled “Manage packages”The package list in LaTeX engine settings lets you filter packages, inspect descriptions, and add or remove them. Tagging badges identify packages that need extra attention when producing a tagged PDF. These controls manage the TeX distribution used by latexmk; Tectonic has a separate cache.