# 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]. ``` ## Illustrated prose Use `illustrated` to place a framed image beside prose and let the text flow around it. Image paths beginning with `/` are relative to the repository root: ```typst #illustrated( "/images/illustrations/example_child.jpg", [ Sur terre, sous la surface des mers et dans les cieux vivent les enfants des calamités. Le texte se poursuit naturellement autour de l'illustration. ], ) ``` Add a caption, change the image width, or place it on the left when useful: ```typst #illustrated( "/images/illustrations/example_child.jpg", [ Le contenu peut comporter plusieurs paragraphes. Le texte est présenté à côté de l'image. ], side: left, width: 4cm, caption: [Un Zizfir juvénile.], ) ``` The optional parameters are: - `side`: `left` or `right`; defaults to `right`; - `width`: displayed image width; defaults to `4cm`; - `radius`: corner radius for the image frame; defaults to `3pt`; - `caption`: content displayed beneath the image; defaults to `none`. For several nearby illustrations, alternating `side: left` and `side: right` usually gives the page a more balanced rhythm. Keep headings outside the body passed to `illustrated` so they remain part of the document outline. ## Rule notation `ddlvl` displays a difficulty level using the project's notation: ```typst #ddlvl(3) #ddlvl(2, plus: true) ``` `marques` formats a number of status marks and pluralizes “marque” automatically: ```typst #marques([@al_saignement], 1, 2) // 1 marque de saignement (difficulty 2) #marques([@al_saignement], 3, 2) // 3 marques de saignement (difficulty 2) ``` `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 ```