ravenous_typst/docs/usage.md

3.8 KiB

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.

Import the prelude

Start a chapter with:

#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:

typst compile --root . chapters/my_chapter.typ chapter.pdf

Section references

Give the destination heading a label, then pass that label to reference:

== Résistances <ssec:resistances>

Les règles complètes sont décrites ailleurs
#reference(<ssec:resistances>).

This renders a clickable reference such as “voir section 3.2 page 18”. For the long form, use long: true:

#reference(<ssec:resistances>, 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:

#reference(
  <ssec:future-rule>,
  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:

#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:

Le personnage agit immédiatement #inline_help[sauf indication contraire].

Rule notation

ddlvl displays a difficulty level using the project's notation:

#ddlvl(3)
#ddlvl(2, plus: true)

marques formats a number of status marks and pluralizes “marque” automatically:

#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:

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:

#show table: st.set-table-style

#table(
  columns: (1fr, auto),
  [Nom], [Valeur],
  [Exemple], [3],
)

Use csv-table for data-backed tables:

#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:

#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:

typst compile main.typ main.pdf