335 lines
8.4 KiB
Markdown
335 lines
8.4 KiB
Markdown
# 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
|
|
```
|
|
|
|
## Create a themed document
|
|
|
|
For a new document that uses the same theme and document model as the Ravenous
|
|
handbooks, create a Typst file at the repository root with this structure:
|
|
|
|
```typst
|
|
#import "/setup/setup.typ": config_main
|
|
#import "/setup/prelude.typ": *
|
|
|
|
#show: config_main
|
|
|
|
#set document(
|
|
title: "Mon document",
|
|
author: "Mon nom",
|
|
)
|
|
|
|
= Mon document
|
|
|
|
Le contenu commence ici.
|
|
```
|
|
|
|
`config_main` applies the theme selected by `document.color_scheme` in
|
|
`data/config/build.yaml`, along with the shared page styles, text styles,
|
|
glossary support, and complete glossary output.
|
|
|
|
Compile it from the repository root:
|
|
|
|
```sh
|
|
typst compile mon_document.typ mon_document.pdf
|
|
```
|
|
|
|
To select another existing theme for one build, pass the shared `theme` input:
|
|
|
|
```sh
|
|
typst compile --input theme=steel mon_document.typ mon_document-steel.pdf
|
|
```
|
|
|
|
Available theme names are defined in `setup/theme/themes.typ`.
|
|
|
|
## Section references
|
|
|
|
Give the destination heading a label, then pass that label to `reference`:
|
|
|
|
```typst
|
|
== 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`:
|
|
|
|
```typst
|
|
#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:
|
|
|
|
```typst
|
|
#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:
|
|
|
|
```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.
|
|
|
|
## Glossary definitions
|
|
|
|
Use `show_definition` to display a glossary term followed by its complete
|
|
definition:
|
|
|
|
```typst
|
|
#show_definition("rl_channel")
|
|
```
|
|
|
|
This is equivalent to writing `#gls("rl_channel") :
|
|
#gls-description("rl_channel")`, while keeping repeated definitions consistent
|
|
with their glossary entry.
|
|
|
|
## Forge effect macros
|
|
|
|
Forge material and finishing effects should use the structured helpers below.
|
|
Besides producing consistent text, these calls allow the cookbook and balance
|
|
report to include the modifiers in their calculations.
|
|
|
|
Use `change` for a direct statistic modifier:
|
|
|
|
```typst
|
|
#change("integrity", "+2")
|
|
#change("torque", "-10")
|
|
```
|
|
|
|
The effect must include its sign. An optional `of_type` condition associates a
|
|
damage modifier with a particular element or physical damage type:
|
|
|
|
```typst
|
|
#change("elemental_damage", "+1", of_type: [@el_ice])
|
|
#change("physical_damage", "+5", of_type: [@el_blunt])
|
|
```
|
|
|
|
These render in the form “Dégâts de type Glace +1”.
|
|
|
|
Use `change-resist` for elemental or physical resistance changes in craft data:
|
|
|
|
```typst
|
|
#change-resist([@el_ice], 2)
|
|
#change-resist([@el_water], -3)
|
|
```
|
|
|
|
These render as “Résistance Glace (++)” and “Résistance Eau (---)”. The value
|
|
must be an integer and the element must be passed as content.
|
|
|
|
Use `resist-category` to grant resistance to every alteration associated with
|
|
an elemental or physical type:
|
|
|
|
```typst
|
|
#resist-category([@el_ice], 1)
|
|
```
|
|
|
|
This renders as “Résistance à toutes les altérations de type Glace
|
|
(#ddlvl(1, plus: true))”.
|
|
|
|
Use `tearing-resist` for resistance against attempts to tear an item away:
|
|
|
|
```typst
|
|
#tearing-resist(2)
|
|
```
|
|
|
|
This renders as “Résistance à l'arrachement (#ddlvl(2, plus: true))”.
|
|
|
|
Use `drawback-reduction` when an effect reduces existing penalties from other
|
|
compounded forge elements. It only affects negative values and never turns a
|
|
penalty into a bonus:
|
|
|
|
```typst
|
|
#drawback-reduction(("dodge", "parry"), "2")
|
|
#drawback-reduction(("damage",), "4")
|
|
```
|
|
|
|
Use `bonus-reduction` for the inverse operation. It reduces existing positive
|
|
bonuses and never turns a bonus into a penalty:
|
|
|
|
```typst
|
|
#bonus-reduction(("damage", "rmax"), "-2")
|
|
#bonus-reduction(("p_damage",), "-1")
|
|
```
|
|
|
|
Both reduction macros accept one or more statistic names. Damage per success
|
|
may be written as either `p_damage` or `damage_p`.
|
|
|
|
Inside trusted forge TSV cells, the quotes around statistic names and integer
|
|
amounts are optional. For example, the following is equivalent to the first
|
|
`bonus-reduction` example above:
|
|
|
|
```typst
|
|
#bonus-reduction((damage, rmax), -2)
|
|
```
|
|
|
|
## 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
|
|
```
|