Spines

A spine in Rheo is the backbone or ‘table of contents’ of Typst source files that should be compiled to an output format. It takes its name from the EPUB specification, in which the spine articulates—or reticulates— the set and order of chapters included.

Directory-scan default

With no configuration at all, the spine is built from content_dir’s own directory structure:

• Every .typ file is included, ordered alphabetically within each directory level.
• A subdirectory with a landing file — index.typ, or a file named after the directory itself (e.g. chapters/chapters.typ) — becomes a group with its own page and handle.
• A subdirectory without a landing file becomes a group node with no page or handle of its own, its title derived from the directory name.
• A leading numeric prefix on a directory or section name orders it among its siblings but is stripped from the displayed title: 01-intro/ → “Intro”. The raw name, prefix included, is kept in the handle. Files are not prettified this way — a file’s title comes from its own content, not its filename.

This default is enough for most projects: name your files and folders in the order you want them read, and the spine follows.

[spine] exclude

To omit files or folders from the scan without moving them out of content_dir, list glob patterns (relative to content_dir) under [spine] exclude:

[spine]
exclude = ["drafts/**", "TODO.typ"]

Excluded paths are dropped from every format’s spine.

[spine] include

[spine] include is an ordered list of glob patterns that becomes that spine’s definitive order, replacing the alphabetical directory scan outright. Patterns are matched in the order you list them. Within a single pattern, matches are sorted lexicographically. A file matched by none of the listed patterns is dropped from the spine entirely, thus include makes a separate exclude for the same files unnecessary.

[spine]
include = ["index.typ", "install.typ", "ideas.typ", "flights.typ"]

The include attribute is one way of restructuring the order in which vertebrae appear in the spine. For finer-grained control, read on to the next section.

[[spine.section]]

Using [[spine.section]] allows you to group files under virtual directories for the purpose of order and structure in the Rheo spine without actually moving the files on disk. This is useful for reshaping the spine’s structure independently of your folder layout:

[[spine.section]]
name = "chapters"
include = ["ch-*.typ"]

• Files matching include get pulled under a virtual chapters group, gaining a namespaced handle exactly as if they lived in a chapters/ directory: ch-1.typ → <chapters:ch-1>.
• A section’s title defaults to a prettified version of name, and can be overridden explicitly.
• Sections can be nested via [[spine.section.section]] to arbitrary depth.
• When include lists more than one glob, matches are gathered in glob order and lexicographically within each glob — so listing globs in the order you want lets you control ordering explicitly, not just alphabetically.

Per-format overrides

A format-specific table via [pdf.spine], [html.spine], or [epub.spine] will override the global [spine] one field at a time.

[spine]
exclude = ["drafts/**"]

[pdf.spine]
title = "My Book"   # combined-output title, PDF/EPUB only

Here PDF still inherits the global exclude, even though it only sets its own title.

Each format uses its spine slightly differently. See the PDF, HTML, and EPUB format pages for details on how spines are configured and what defaults are applied for each output.