From f013b06d45c7bd4187fc0537c0eef042e37cefe1 Mon Sep 17 00:00:00 2001 From: Lachlan Kermode Date: Tue, 30 Dec 2025 17:36:22 +0100 Subject: [PATCH 01/19] Updates git submodules to latest --- examples/fcl_site | 2 +- examples/rheo_docs | 2 +- .../ref/examples/fcl_site/epub/fcl_site.metadata.json | 2 +- tests/ref/examples/fcl_site/html/index.html | 4 ++-- .../ref/examples/fcl_site/pdf/fcl_site.metadata.json | 2 +- .../examples/rheo_docs/epub/rheo_docs.metadata.json | 3 +-- tests/ref/examples/rheo_docs/html/build-dir.html | 7 ++++--- tests/ref/examples/rheo_docs/html/content-dir.html | 5 +++-- tests/ref/examples/rheo_docs/html/custom-css.html | 7 ++++--- tests/ref/examples/rheo_docs/html/formats.html | 7 ++++--- .../ref/examples/rheo_docs/html/getting-started.html | 9 +++++---- tests/ref/examples/rheo_docs/html/index.html | 7 ++++--- .../ref/examples/rheo_docs/html/relative-linking.html | 7 ++++--- tests/ref/examples/rheo_docs/html/rheotoml.html | 5 +++-- tests/ref/examples/rheo_docs/html/spines.html | 11 ++++++----- .../examples/rheo_docs/html/what-and-why-is-rheo.html | 7 ++++--- .../examples/rheo_docs/pdf/rheo_docs.metadata.json | 2 +- 17 files changed, 49 insertions(+), 40 deletions(-) diff --git a/examples/fcl_site b/examples/fcl_site index 32d0eed..68c1651 160000 --- a/examples/fcl_site +++ b/examples/fcl_site @@ -1 +1 @@ -Subproject commit 32d0eedc1da172487d42e0e6079d269c5f01d330 +Subproject commit 68c16514dd086e4da7e06da89d8d583ca286652a diff --git a/examples/rheo_docs b/examples/rheo_docs index 8d67839..d457c12 160000 --- a/examples/rheo_docs +++ b/examples/rheo_docs @@ -1 +1 @@ -Subproject commit 8d67839d38dc2ce5940418674f3c1bb403dbf8c5 +Subproject commit d457c12e48df26361e12154b9987a9f3a5086e4d diff --git a/tests/ref/examples/fcl_site/epub/fcl_site.metadata.json b/tests/ref/examples/fcl_site/epub/fcl_site.metadata.json index 94677e2..1c9abbd 100644 --- a/tests/ref/examples/fcl_site/epub/fcl_site.metadata.json +++ b/tests/ref/examples/fcl_site/epub/fcl_site.metadata.json @@ -1,6 +1,6 @@ { "filetype": "epub", - "file_size": 1307334, + "file_size": 1307445, "title": "The Free Computing Lab", "language": "en", "spine_files": [ diff --git a/tests/ref/examples/fcl_site/html/index.html b/tests/ref/examples/fcl_site/html/index.html index 60daabd..750a254 100644 --- a/tests/ref/examples/fcl_site/html/index.html +++ b/tests/ref/examples/fcl_site/html/index.html @@ -4,7 +4,8 @@ -

The free computing lab researches the nature of computing freedom. Our research aims to demonstrate the role that the computer could and should play in a society where freedom is flourishing rather than deprecated, and to cultivate a critically grounded practice of software production, development, and maintenance. See our GitHub page for code and more information.

+

The free computing lab researches the nature of computing freedom. Our research aims to demonstrate the role that the computer could and should play in a society where freedom is flourishing rather than deprecated, and to cultivate a critically grounded practice of software production, development, and maintenance.

+

See our GitHub page for code and more information. You can also join our Zulip to ask questions and follow our research, or drop us a note at hi@ohrg.org.

Our research projects include:

-

Relative linking is what allows Rheo to produce fully functinoal static sites. It is also a feature that you can use to help you organize large writing projects. (Note that the Typst import keyword works as you would expect in Rheo, and so can also/still be used as a mechanism to modularize projects.)

+

Relative linking is what allows Rheo to produce fully functional static sites. It is also a feature that you can use to help you organize large writing projects. (Note that the Typst import keyword works as you would expect in Rheo, and so can also/still be used as a mechanism to modularize projects.)

← Getting started Rheo.toml →
← Previous Next →
diff --git a/tests/ref/examples/rheo_docs/html/rheotoml.html b/tests/ref/examples/rheo_docs/html/rheotoml.html index 37c8225..5fba0b0 100644 --- a/tests/ref/examples/rheo_docs/html/rheotoml.html +++ b/tests/ref/examples/rheo_docs/html/rheotoml.html @@ -12,7 +12,7 @@
diff --git a/tests/ref/examples/rheo_docs/html/spines.html b/tests/ref/examples/rheo_docs/html/spines.html index 9e81826..03b3a18 100644 --- a/tests/ref/examples/rheo_docs/html/spines.html +++ b/tests/ref/examples/rheo_docs/html/spines.html @@ -12,7 +12,7 @@
diff --git a/tests/ref/examples/rheo_docs/html/style.metadata.json b/tests/ref/examples/rheo_docs/html/style.metadata.json index 77508c4..7cfcff7 100644 --- a/tests/ref/examples/rheo_docs/html/style.metadata.json +++ b/tests/ref/examples/rheo_docs/html/style.metadata.json @@ -1,6 +1,6 @@ { "filetype": "css", - "file_size": 10205, + "file_size": 10339, "path": "src/css/style.css", - "hash": "baf8566046bbdeac383ecc05d7baa4f1891dfe776a3c95e02f583d87d45025e4" + "hash": "941a9bc8b4b6f672fa89dcfa54f2426ea7a804d5c9dc4023cdfeeefe9102eb8d" } \ No newline at end of file diff --git a/tests/ref/examples/rheo_docs/html/what-and-why-is-rheo.html b/tests/ref/examples/rheo_docs/html/why-is-rheo.html similarity index 97% rename from tests/ref/examples/rheo_docs/html/what-and-why-is-rheo.html rename to tests/ref/examples/rheo_docs/html/why-is-rheo.html index 64d4706..ca8dba4 100644 --- a/tests/ref/examples/rheo_docs/html/what-and-why-is-rheo.html +++ b/tests/ref/examples/rheo_docs/html/why-is-rheo.html @@ -1,7 +1,7 @@ - What and why is Rheo? | Rheo + Why Rheo? | Rheo
@@ -12,7 +12,7 @@
-

What and why is Rheo?

+

Why do we need Rheo?

Rheo (ree-oh) is an open source typesetting and static site engine for Typst. It is a typesetting engine because it produces typeset digital documents such as PDF and EPUB, and a static site engine because it produces websites that don’t require communication with a custom backend server, but rather are self-sufficient sets of files that can be natively opened a browser (static sites). Most static site engines these days employ Markdown, a markup format that is approachable and pretty generic, allowing folks who are not familiar with or otherwise don’t want to deal directly with the required file formats of the web— HTML, CSS, and Javascript— to write blog posts and other content which can then be pumped into a static site.

As useful as it is, Markdown has its ambiguities. For one, there isn’t a standardized syntax for citations or footnotes. Though extensions exist that can produce these, they are not supported in the core Markdown syntax, meaning that it’s not really Markdown and can’t be relied upon to work in all contexts that support Markdown. Markdown is great when using hypertext (hyperlinks, images, etc). It’s not so great when it comes to things like tables, figures, and math.

Typst is a markup language that integrates with plain text, like Markdown, making it easy to adopt and joyful to write. Unlike Markdown, however, it is also a Turing-complete programming language with a modern type system, meaning that it is possible (though not necessary) to express sophisticated conditional logic controlling where and how text is rendered. Typst has a concrete and concise syntax for footnotes and citations, and can express visual constructs such as tables, figures, colors, and mathematical formulas. It was developed as a modern alternative to LaTeX, Leslie Lamport’s legendary 1980s addition to Donald Knuth’s original ‘78 Tex typesetting system. For the past 40 years, LaTeX has been the most expressive way to produce pdf documents, rendering it the de facto standard for academic and scientific publication. In the past few years, Typst has become the most promising and powerful alternative to LaTeX due to its maintainers’ effort to build out a reliable PDF compilation toolchain.

In 2025, Typst added experimental support for HTML compilation. Though there are still many features in Typst that will only produce meaningful output in the PDF toolchain, the HTML toolchain now supports all of the essential features for academic documents in the humanities: text decoration, headings, hyperlinks, footnotes, and citations.1 This makes it an extremely good replacement for Markdown as a markup language in a static site engine, and so: enter Rheo.

Rheo is a CLI (command line interface) that produces PDF, HTML, and EPUB simultaneously from a folder of Typst documents. It is a static site engine because it can produce a fully valid website: all it needs is a folder containing valid Typst. Rheo also provides mechanisms to combine multiple Typst files into a unified EPUB or PDF, making it a tool that improves the experience of writing books, dissertations, or any other long-form text in Typst. On the other side of the same coin, Rheo allows you to produce an offline version of a website such as a blog written in Typst through its PDF/EPUB toolchain.

-

Rheo allows you to compile multiple Typst files that link to each other into a single output, adding what is needed (relative linking) in order to make Typst an ideal markup language for writing static sites. Typst is the most elegant and flexible way to typeset PDF documents today; Rheo extends Typst’s capabilities, allowing you to additionally typeset EPUBs and generate static sites from the same source.2 Naturally, this blog post was written with Typst, and this site was made with Rheo. If you’re already convinced, feel free to jump ahead to Getting Started to download Rheo on your system and get building.

+

Rheo allows you to compile multiple Typst files that link to each other into a single output, adding what is needed (relative linking) in order to make Typst an ideal markup language for writing static sites. Typst is the most elegant and flexible way to typeset PDF documents today; Rheo extends Typst’s capabilities, allowing you to additionally typeset EPUBs and generate static sites from the same source.2 Naturally, this blog post was written with Typst, and this site was made with Rheo. If you’re already convinced, feel free to jump ahead to Getting Started to download Rheo on your system and get building.

The philosophy of Rheo

Rheo is a prefix or combining form in English that originates from the Greek word rheos (ῥέος), meaning flow, stream, or current. Rheo flows Typst documents into a number of concurrent output formats in PDF, HTML, and EPUB. But other meanings lurk beneath the surface of this basic idea. Sarah Pourciau has argued that the oceanic is a deep-rooted metaphor in computing, as all computation at some level seeks solid space in a sea of digital noise (Pourciau 2022). From Alan Turing’s partial solution to David Hilbert’s Entscheidungsproblem in the universal machine, to Claude Shannon’s information theory, to Leslie Lamport’s ordering of events in a distributed system, the key issue at hand is how to carve out clarity from uncertainty and confusion. Writing has played a magisterial role in calming the storm of imprecise thought. Long before computation arrived on the scene, the written word has served as the steward of reason, in the Western world and beyond, from Mesopotamian cunieform to Twitter. Nota bene (‘Take note’): that writing can also herald chaos and confusion doesn’t invalidate its capacity for spreading sensibility.

Rheo is a tool that facilitates the production and publication of documents following from the original vision of the Internet as a mechanism for lively and reasonably unfettered academic exchange, rather than the densely commercial space of platform capitalism that it has become. It should not be so difficult, given the extraordinary capacities of software and hardware today, to make a piece of writing publically available in a plain and pleasant format. That there exist digital humanities initiatives measured in months and years to bring books to the web as basic websites is a clear sign that something has gone awry.3

diff --git a/tests/ref/examples/rheo_docs/pdf/rheo_docs.metadata.json b/tests/ref/examples/rheo_docs/pdf/rheo_docs.metadata.json index 94f88ac..73b1219 100644 --- a/tests/ref/examples/rheo_docs/pdf/rheo_docs.metadata.json +++ b/tests/ref/examples/rheo_docs/pdf/rheo_docs.metadata.json @@ -1,5 +1,5 @@ { "filetype": "pdf", - "file_size": 72674, - "page_count": 4 + "file_size": 103470, + "page_count": 5 } \ No newline at end of file diff --git a/tests/ref/examples/target_function/epub/target_function.metadata.json b/tests/ref/examples/target_function/epub/target_function.metadata.json new file mode 100644 index 0000000..9c28db3 --- /dev/null +++ b/tests/ref/examples/target_function/epub/target_function.metadata.json @@ -0,0 +1,10 @@ +{ + "filetype": "epub", + "file_size": 2918, + "title": "main.xhtml", + "language": "en", + "spine_files": [ + "main.xhtml" + ], + "has_nav": true +} \ No newline at end of file diff --git a/tests/ref/examples/target_function/html/main.html b/tests/ref/examples/target_function/html/main.html new file mode 100644 index 0000000..1eb6897 --- /dev/null +++ b/tests/ref/examples/target_function/html/main.html @@ -0,0 +1,13 @@ + + + + + +

Target Function Test

+

This test verifies that the target() function returns format-specific values.

+

Current format: html

+

Conditional Content

+

HTML-specific content: This appears only in HTML output

+ + + \ No newline at end of file diff --git a/tests/ref/examples/target_function/html/style.metadata.json b/tests/ref/examples/target_function/html/style.metadata.json new file mode 100644 index 0000000..dbd27db --- /dev/null +++ b/tests/ref/examples/target_function/html/style.metadata.json @@ -0,0 +1,6 @@ +{ + "filetype": "css", + "file_size": 2603, + "path": "src/css/style.css", + "hash": "02d37b0efd17dd8c8570eb1e3a71db78cde94f9de017e354aca839b6134ca93e" +} \ No newline at end of file diff --git a/tests/ref/examples/target_function/pdf/main.metadata.json b/tests/ref/examples/target_function/pdf/main.metadata.json new file mode 100644 index 0000000..0af7160 --- /dev/null +++ b/tests/ref/examples/target_function/pdf/main.metadata.json @@ -0,0 +1,5 @@ +{ + "filetype": "pdf", + "file_size": 3086, + "page_count": 1 +} \ No newline at end of file From 5e172f8c9cc24114b39abbb7e4741e3071e1b2dc Mon Sep 17 00:00:00 2001 From: Lachlan Kermode Date: Tue, 13 Jan 2026 16:01:47 +0100 Subject: [PATCH 04/19] Updates git submodules to latest --- examples/rheo_docs | 2 +- tests/ref/examples/rheo_docs/epub/rheo_docs.metadata.json | 2 +- tests/ref/examples/rheo_docs/html/build-dir.html | 2 +- tests/ref/examples/rheo_docs/html/content-dir.html | 2 +- tests/ref/examples/rheo_docs/html/custom-css.html | 2 +- tests/ref/examples/rheo_docs/html/faq.html | 2 +- tests/ref/examples/rheo_docs/html/formats.html | 2 +- tests/ref/examples/rheo_docs/html/getting-started.html | 2 +- tests/ref/examples/rheo_docs/html/index.html | 2 +- tests/ref/examples/rheo_docs/html/relative-linking.html | 2 +- tests/ref/examples/rheo_docs/html/rheotoml.html | 2 +- tests/ref/examples/rheo_docs/html/spines.html | 2 +- tests/ref/examples/rheo_docs/html/why-is-rheo.html | 2 +- tests/ref/examples/rheo_docs/pdf/rheo_docs.metadata.json | 2 +- 14 files changed, 14 insertions(+), 14 deletions(-) diff --git a/examples/rheo_docs b/examples/rheo_docs index 2a69b1b..5a165e2 160000 --- a/examples/rheo_docs +++ b/examples/rheo_docs @@ -1 +1 @@ -Subproject commit 2a69b1b3a45fdcd853fd4a3f57477af2f5bc9ec5 +Subproject commit 5a165e247c93dd575b9c31f63ace26f01f63dea4 diff --git a/tests/ref/examples/rheo_docs/epub/rheo_docs.metadata.json b/tests/ref/examples/rheo_docs/epub/rheo_docs.metadata.json index 12070db..70fe121 100644 --- a/tests/ref/examples/rheo_docs/epub/rheo_docs.metadata.json +++ b/tests/ref/examples/rheo_docs/epub/rheo_docs.metadata.json @@ -1,6 +1,6 @@ { "filetype": "epub", - "file_size": 131337, + "file_size": 149233, "title": "Rheo Manual", "language": "en", "spine_files": [ diff --git a/tests/ref/examples/rheo_docs/html/build-dir.html b/tests/ref/examples/rheo_docs/html/build-dir.html index 15b0c40..d85726a 100644 --- a/tests/ref/examples/rheo_docs/html/build-dir.html +++ b/tests/ref/examples/rheo_docs/html/build-dir.html @@ -6,7 +6,7 @@
-

Rheo

+

Rheo