diff --git a/docs/usage.md b/docs/usage.md index 5aa8d47..40f3249 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -82,6 +82,48 @@ Use `inline_help` for a short parenthetical aside: 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. + + Meander poursuit automatiquement le texte sous 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: diff --git a/setup/core/macros.typ b/setup/core/macros.typ index fbfb573..4532ce6 100644 --- a/setup/core/macros.typ +++ b/setup/core/macros.typ @@ -136,16 +136,20 @@ radius: radius, stroke: 0.6pt + theme.border, )[ - #image(source, width: 100%) - #if caption != none { - block( - width: 100%, - inset: (x: 5pt, y: 3pt), - fill: theme.parchment, - )[ - #text(size: 8pt, style: "italic", fill: theme.muted)[#caption] - ] - } + #stack( + dir: ttb, + spacing: 0pt, + image(source, width: 100%), + if caption != none { + block( + width: 100%, + inset: (x: 5pt, y: 3pt), + fill: theme.parchment, + )[ + #text(size: 8pt, style: "italic", fill: theme.muted)[#caption] + ] + }, + ) ] meander.reflow({ diff --git a/setup/prelude.typ b/setup/prelude.typ index 2aa01fb..e709856 100644 --- a/setup/prelude.typ +++ b/setup/prelude.typ @@ -16,6 +16,7 @@ // Common prose helpers. #let ravhelp = setup.ravhelp #let inline_help = setup.inline_help +#let illustrated = setup.illustrated #let reference = setup.reference #let ravex = boxes.ravex #let ravtwoex = boxes.ravtwoex