Installation

The easiest way to install Rheo is using cargo-binstall. Install it, and then run:

cargo binstall rheo

Alternatively, you can build Rheo from crates.io, the Rust language’s package manager. If you don’t already have Rust/cargo, you will need to install those first. Open your terminal, and run the following command:

cargo install rheo --locked

Rheo is packaged as a standalone binary, and doesn’t require any version of Typst on your system. (Note that even if you already have Typst on your system, Rheo will use its own embedded version of the compiler.) Refer to Rheo’s source code for more information and installation options.

Firing up

With Rheo we can produce a static site, a PDF, and an EPUB from a Typst document. Let’s create a directory with a single Typst file in it:

mkdir project_uno
touch project_uno/index.typ

As one of Rheo’s outputs is a static site, the landing page will default to one named ‘index’. (If this file doesn’t exist, Rheo will present you with a basic listing of all the other files in the site.) Let’s put some Typst in the index.typ file:

project_uno/index.typ

= Project uno

Project uno is a writing project.

Rheo aims to keep out of your way as much as possible, and doesn’t require that you add any special syntax or metadata to your files to work. This single Typst file is all we need to get started. Provided you’ve already installed Rheo on your system, we can compile the project. You can tell Rheo to compile a folder by pointing the compile command at it:

rheo compile project_uno

This command produces a build subdirectory inside the base directory which contains a PDF, an EPUB, and a static site (HTML and CSS). Your project folder should now look something like this:

.
├── build
│   ├── epub
│   │   └── project_uno.epub
│   ├── html
│   │   ├── index.html
│   │   └── style.css
│   └── pdf
│       └── index.pdf
└── index.typ

It’s a little tiring to have to run the compile command every time we make a change, though. Let’s spin up a development server to see live changes across all output formats as we edit the source:

rheo watch project_uno --open

The --open flag here indicates that we’d like to open the output using our system’s default applications. Provided you have an EPUB reader on your system (if you don’t, we recommend installing Bene), you should now have a PDF, an EPUB, and a website in front of you. As simple as that!

Scaling up

Let’s kill that process (with Ctrl-C). Rheo compiles documents from across your project directory towards EPUB, PDF, and HTML simultaneously, whereas the Typst compiler typically takes just one Typst file and produces one kind of output.³ Let’s add a couple of files to our project and link between them:

project_uno/about.typ

= About

Project uno is an incredible writing project that will transform the way we understand the world.
If you want to be involved, see the #link(<contact>)[Contact page].

project_uno/contact.typ

#let email = "myemail@mydomain.com"
= Contact

To learn more about project uno, email me at #link("mailto:" + email)[#email]

And let’s also link to the two new pages on the index page:

project_uno/index.typ

= Project uno

Project uno is a writing project.

- #link(<about>)[About]
- #link(<contact>)[Contact]

Now let’s run Rheo again, but this time let’s only build the HTML and EPUB outputs:

rheo watch project_uno --html --epub --open

Note how the relative links are working across both the HTML and the EPUB. Relative linking is one of the key features in Rheo that enables you to build richer static sites and EPUBs beyond using just Typst. All of Typst’s other features such as variables are fair game, too, as Rheo just uses Typst’s compiler under the hood.

Adding a config

One issue with the EPUB that is currently being produced is that the index.typ section shows up last, after about.typ and contact.typ. This is because Rheo builds a project’s spine by scanning content_dir and ordering files alphabetically by default, and index sorts after about and contact. This is probably not what we want, as the index page acts as a sort of table of contents in our writing project currently.

Since the spine follows file names, we can fix the order by renaming the files so the alphabetical scan already matches our intended reading order:

mv project_uno/index.typ project_uno/00-index.typ
mv project_uno/about.typ project_uno/01-about.typ
mv project_uno/contact.typ project_uno/02-contact.typ

Renaming a file changes its handle too — Rheo derives a handle from the file’s name — so update the cross-links to match:

project_uno/00-index.typ

= Project uno

Project uno is a writing project.

- #link(<01-about>)[About]
- #link(<02-contact>)[Contact]

project_uno/01-about.typ

= About

Project uno is an incredible writing project that will transform the way we understand the world.
If you want to be involved, see the #link(<02-contact>)[Contact page].

Now let’s add a rheo.toml config at the base of the project directory to give the EPUB and PDF outputs a proper title:

project_uno/rheo.toml

version = "0.4.0"

[epub.spine]
title = "Project Uno"

[pdf.spine]
title = "Project Uno"

Let’s run the watch command again, this time with all outputs like the first time:

rheo watch project_uno --open

Great! Renaming the files fixed the order for both the EPUB and the PDF in one go — the PDF output, like EPUB, combines every source file in its spine into a single document, following the same directory-scan order.

Before we run this again, let’s also clean the outputs in the build directory:

rheo clean project_uno
rheo watch project_uno --open

Now we have a fully featured writing project, with nice-looking and orderly outputs in PDF, EPUB, and in HTML!

Footnotes