# Writing Ravenous content with Typst This guide covers the shared helpers intended for ordinary chapters and rules. For the overall repository structure and build commands, see the [project README](../Readme.md). ## Import the prelude Start a chapter with: ```typst #import "/setup/prelude.typ": * ``` The leading `/` makes the path relative to the project root. The prelude is the recommended authoring interface: it exposes common helpers without importing document configuration or specialized models into every chapter. When compiling a chapter or test directly, keep the repository as Typst's root: ```sh typst compile --root . chapters/my_chapter.typ chapter.pdf ``` ## Section references Give the destination heading a label, then pass that label to `reference`: ```typst == Résistances Les règles complètes sont décrites ailleurs #reference(). ``` This renders a clickable reference such as “voir section 3.2 page 18”. For the long form, use `long: true`: ```typst #reference(, long: true) ``` This renders “Pour plus de détails, se référer à la section 3.2 page 18”. Both `long` and `fallback` are optional and default to `false` and `none`. If a label is optional or temporarily unavailable, provide a section name as a fallback: ```typst #reference( , fallback: [Règle à venir], ) ``` Without a matching label or a `fallback`, compilation fails deliberately so broken references are not silently published. ## Prose boxes The prelude provides themed boxes for common editorial content: ```typst #ravhelp[Une règle ou information importante.] #ravhelp(title: "Conseil")[Un conseil avec un titre personnalisé.] #ravex[Un exemple d'application de la règle.] #ravtwoex[ Premier exemple. ][ Second exemple, séparé visuellement du premier. ] #ravbox[Une boîte sans titre.] ``` Use `inline_help` for a short parenthetical aside: ```typst Le personnage agit immédiatement #inline_help[sauf indication contraire]. ``` ## Rule notation `ddlvl` displays a difficulty level using the project's notation: ```typst #ddlvl(3) #ddlvl(2, plus: true) ``` `kw` emphasizes a rules keyword: ```typst L'action affecte l'#kw[acteur]. ``` The prelude also exposes: - `hunbal`, for shared rule constants; - `symbols`, for the project's symbol collection; - `macros`, for less common helpers from `setup/core/macros.typ`. Prefer a directly exported helper such as `ddlvl` over `macros.ddlvl` when both are available. ## Tables and CSV data Use `st` to access the shared table styles: ```typst #show table: st.set-table-style #table( columns: (1fr, auto), [Nom], [Valeur], [Exemple], [3], ) ``` Use `csv-table` for data-backed tables: ```typst #csv-table( "/data/src/example.csv", columns: (1fr, auto), ) ``` CSV cells are treated as plain text by default. Set `evaluate: "markup"` or `evaluate: "code"` only when the source is trusted and needs Typst evaluation. ## Specialized imports The prelude intentionally stays small. Import from `/setup/setup.typ` or the relevant implementation module when working with document configuration, warnings, build metadata, domain models, report generation, or theme internals. Keep those imports explicit so a chapter's unusual dependencies remain visible. For example: ```typst #import "/setup/prelude.typ": * #import "/setup/setup.typ": gls, nogls ``` Before submitting a change, compile the relevant target. For changes to shared macros or styles, also compile the complete rulebook: ```sh typst compile main.typ main.pdf ```