Configuration : styles et parties

#Styles de paragraphe

La propriété paragraphStyles déclare des styles nommés qu’un document applique à une suite de paragraphes avec un conteneur :::paragraphs{style="…"} : bibliographies, glossaires, notes, tout bloc d’entrées qui demande sa propre police, sa graisse, son inclinaison, son corps, son interlignage, des capitales, des petites capitales ou un retrait suspendu. Chaque champ typographique est facultatif et hérite du texte courant s’il n’est pas défini : un style n’énonce que ce qui le distingue du texte courant.

const config: PostextConfig = {
  paragraphStyles: [
    {
      id: 'bibliography',
      name: 'Bibliography',
      fontSize: { value: 7, unit: 'pt' },
      lineHeight: { value: 1.2, unit: 'em' },
      hangingIndent: { value: 2, unit: 'em' },
      spaceBetween: { value: 0.25, unit: 'em' },
      marginTop: { value: 1, unit: 'em' },
      marginBottom: { value: 1, unit: 'em' },
    },
  ],
};

## References
 
:::paragraphs{style="bibliography"}
Knuth, D. E. (1984). *The TeXbook*. Addison-Wesley.
 
Bringhurst, R. (2004). *The Elements of Typographic Style*. Hartley & Marks.
:::

Une pièce de théâtre compose ses didascalies en italique et sa liste des personnages en petites capitales :

paragraphStyles: [
  { id: 'direction', italic: true, fontSize: { value: 9, unit: 'pt' } },
  { id: 'cast', smallCaps: true, textAlign: 'center', fontWeight: 600 },
],

:::paragraphs{style="direction"}
Elsinore. A platform before the castle. *Francisco* at his post.
:::

La didascalie s’imprime en italique et le nom qu’elle contient en romain ; les graisses, italic et smallCaps d’un style s’appliquent aussi à l’intérieur des encadrés.

Un recueil de poésie met certains vers en retrait et renfonce le retour d’un vers trop long pour la ligne plus loin que le vers lui-même. indent décale vers l’intérieur chaque ligne du paragraphe, et le retrait suspendu se compte à partir de là :

paragraphStyles: [
  { id: 'verse', textAlign: 'left', firstLineIndent: { value: 0, unit: 'em' }, hangingIndent: { value: 4, unit: 'em' } },
  { id: 'verse-indented', textAlign: 'left', indent: { value: 1.5, unit: 'em' }, hangingIndent: { value: 2.5, unit: 'em' } },
],

Un vers en verse-indented commence à 1,5 em et son retour à 4 em, au même niveau que les retours des vers en verse. Sans indent, un style peut mettre en retrait la première ligne ou suspendre les autres, mais pas les deux : firstLineIndent est ignoré dès que hangingIndent est défini.

Un menu aligne chaque prix sur la fin de la ligne, derrière des points de conduite :

paragraphStyles: [
  {
    id: 'menu',
    textAlign: 'left',
    firstLineIndent: { value: 0, unit: 'em' },
    tabStops: [{ position: 'end', align: 'end', leader: '. ' }],
  },
],

:::paragraphs{style="menu"}
Onion soup :tab 8.50
 
Grilled sea bream with fennel and lemon :tab 21.00
:::

Les points de chaque ligne s’arrêtent un demi-cadratin avant le prix (leaderGap). Un plat trop long pour sa ligne passe à la ligne, et sa dernière ligne garde les points de conduite et le prix ; quand le prix ne tient pas à côté du dernier mot, ce mot descend avec lui.

#Le conteneur :::paragraphs

Une ligne :::paragraphs{style="<id>"} ouvre le conteneur et une ligne ::: seule le ferme ; chaque paragraphe compris entre les deux prend le style nommé, tandis que les titres, les listes et les autres blocs à l’intérieur gardent leur style habituel. Les conteneurs peuvent s’imbriquer dans d’autres conteneurs délimités. Un id de style inconnu n’est pas une erreur : les paragraphes se rendent comme du texte courant ordinaire.

La clôture d’ouverture accepte aussi align (start, end, left, right, center, justify), indent et endIndent (les nombres seuls sont en em), avec ou sans style : avec un style, ils le surchargent ; sans style, ils s’appliquent par-dessus le style du conteneur englobant, ou par-dessus le style de texte de l’endroit où se trouve la clôture (le texte courant, une partie, une section stylée ou un encadré). :::paragraphs{align=end} compose un bloc aligné sur la fin de la ligne (地付き) et :::paragraphs{align=end endIndent=1} un caractère avant elle. Depuis postext 1.16.

À l’intérieur du conteneur, le flux quitte la grille de ligne de base (une entrée de 7 pt avec un interlignage de 1,2 em ne peut pas tenir sur une grille de 8 pt/1,5 em) et le dernier paragraphe recale le flux sur la grille (la grille l’emporte ; l’espace en dessous est un minimum, la même convention que suivent les titres). Les entrées se coupent d’une colonne et d’une page à l’autre comme les paragraphes du texte courant, avec la même protection contre les orphelines et les veuves ; un titre placé juste avant le conteneur reste avec son premier paragraphe.

L’espace sous le conteneur est le plus grand de spaceBetween et marginBottom du style et de l’espacement de paragraphe du texte qui l’entoure (une ligne quand bodyText.paragraphSpacing est actif), et il se fond avec l’espace que le bloc suivant garde au-dessus de lui, comme l’espace entre deux paragraphes du texte courant : un titre placé après une bibliographie se trouve à son propre marginTop sous la dernière entrée (ou à l’espace du style, s’il est plus grand), et un paragraphe qui suit un groupe d’entrées plus serrées garde l’espacement de paragraphe du texte. Le flux se recale d’abord sur la grille sous le texte, et ce que le recalage n’a pas couvert est reporté en lignes de grille entières, si bien que le texte qui suit le conteneur tombe sur la grille. Jusqu’à postext 1.4, l’espace du style se plaçait sous la dernière ligne avant le recalage, l’espace au-dessus du bloc suivant s’ajoutait en dessous, et l’espacement de paragraphe n’était pas pris en compte ; bodyText.paragraphContainerSpacing: 'add' garde cette règle, et les configurations enregistrées avant elle se lisent avec elle. Un style avec snapToGrid: false ne se recale pas : le texte qui suit le conteneur se place exactement à cet espace en dessous, hors de la grille jusqu’au prochain bloc qui se recale. Un conteneur qui se ferme sur une liste est composé comme dans la 1.4 avec l’une ou l’autre règle : la liste garde son propre espace en dessous, et marginBottom suit cet espace, en se fondant avec celui du bloc suivant.

Un style peut fixer la règle de ses propres conteneurs avec containerSpacing : 'add' sur le style d’une grande figure ou d’une liste de références termine ses groupes sur l’espace propre du style, dans le texte comme à l’intérieur d’un encadré, tandis que tous les autres conteneurs du document gardent 'collapse' ; 'collapse' sur un style fait l’inverse dans un document qui se lit avec 'add'. Un conteneur qui ne nomme aucun style suit le document.

À l’intérieur d’un :::callout, le conteneur prend les marges de son style de la même façon : marginTop et marginBottom fusionnent avec l’espacement des blocs qui l’entourent (une valeur négative les rapproche), et un conteneur qui ouvre l’encadré ne prend pas de marge supérieure, comme en haut d’une colonne. Un encadré n’a pas de grille de ligne de base sur laquelle se recaler : l’espace sous le dernier paragraphe est donc le plus grand de marginBottom, de spaceBetween et de l’espacement de paragraphe propre à l’encadré (son body.paragraphSpacing, une ligne de son texte ; non pris en compte avec paragraphContainerSpacing: 'add'), ou la marge supérieure propre au bloc suivant, si elle est plus grande encore ; un marginBottom négatif remonte au contraire le bloc suivant. (Jusqu’à postext 1.4, un conteneur à l’intérieur d’un encadré ignorait les deux marges.)

const resolved = resolveParagraphStylesConfig(config.paragraphStyles, resolvedBodyText);
// => every unset field filled from the resolved body text
 
const minimal  = stripParagraphStylesDefaults(config.paragraphStyles);
// => undefined when the list is empty; zero margins and `name === id` dropped

#Styles de pastille

La propriété chipStyles déclare les styles nommés de la pastille en ligne :chip[text]{style="…"} : les petits cadres arrondis et teintés d’une banque de mots, d’une touche de clavier, d’une étiquette (la syntaxe et ses règles de coupure de ligne se trouvent dans la référence du format du document). Un style, chip, est fourni par défaut (un fond bleu pâle avec un filet extra-fin dans la couleur principale, légèrement arrondi, le texte comme les mots qui l’entourent) : :chip[…] fonctionne donc sans aucune configuration ; déclarer chipStyles remplace cette liste par défaut. Une pastille sans style, ou dont l’id n’est déclaré par aucun style, prend le premier style.

const config: PostextConfig = {
  chipStyles: [
    { id: 'chip', name: 'Word bank' },
    {
      id: 'key',
      name: 'Keyboard key',
      background: { hex: '#fff4d6', model: 'hex' },
      borderColor: { hex: '#8a6d1f', model: 'hex' },
      borderRadius: { value: 2, unit: 'pt' },
      bold: true,
    },
  ],
};

Classify: :chip[battery] :chip[cable] :chip[switch]
 
Press :chip[Ctrl]{style="key"} + :chip[C]{style="key"}.

Les longueurs en em du cadre (paddingX, paddingY, borderRadius, borderWidth, gap) sont relatives au corps propre de la pastille. Le cadre est une bande de 0,8 em au-dessus et de 0,25 em au-dessous de la ligne de base, agrandie de paddingY et du contour ; il est peint hors de la boîte de ligne et ne change jamais l’interlignage : la grille de ligne de base tient. Quand le cadre devient plus haut que le pas de ligne, une pastille peut empiéter sur une pastille de la ligne du dessus ou du dessous : le sandbox affiche alors un avertissement « Chips touch the next line » quand deux pastilles de lignes différentes se chevauchent, avec le chevauchement en points, pour que vous puissiez réduire paddingY, le contour ou fontSize. Une haute pastille sans pastille au-dessus ou au-dessous n’est pas signalée.

Dans le VDT, une pastille est un segment de ligne de kind: 'chip' dont le champ chip porte les segments de texte (chacun avec sa chaîne de police et sa largeur), la géométrie du cadre (boxWidth, ascent, descent, paddingX, borderWidth, borderRadius, les marges d’espacement) et ses couleurs ; le text du segment est un caractère de substitution unique, si bien que les positions en texte brut et les correspondances avec la source comptent une pastille comme un seul caractère.

const resolved = resolveChipStylesConfig(config.chipStyles);
// => the built-in `chip` style when unset; every field filled
 
const minimal  = stripChipStylesDefaults(config.chipStyles);
// => undefined for the built-in default; static defaults dropped
 
const style = pickChipStyle(resolved, 'key');
// => the `key` style, else the first one

#Listings de code

La propriété codeStyle règle l’aspect des listings de code : les blocs délimités ``` et ~~~ du texte (voir Format du document › Blocs de code), et le code en ligne quand il demande une police de code. Un listing est composé ligne par ligne tel qu’il est écrit, dans une police à chasse fixe, dans un cadre : aucune ligne n’est coupée par césure ni justifiée, chaque espace garde sa largeur, et une tabulation passe au taquet suivant. Le cadre vient de la même mécanique qu’un :::callout : un listing se coupe donc entre deux lignes d’une colonne et d’une page à l’autre, chaque partie dans son propre cadre, et un bloc délimité à l’intérieur d’un encadré est un cadre imbriqué dans celui-ci. Toutes les propriétés sont facultatives. Depuis postext 1.23.

const config: PostextConfig = {
  codeStyle: {
    fontFamily: 'JetBrains Mono',
    fontSize: { value: 0.8, unit: 'em' },
    background: { hex: '#0e1116', model: 'hex' },
    color: { hex: '#d3d9df', model: 'hex' },
    padding: { top: { value: 4, unit: 'mm' }, right: { value: 5, unit: 'mm' }, bottom: { value: 4, unit: 'mm' }, left: { value: 5, unit: 'mm' } },
    borderRadius: { value: 2, unit: 'pt' },
    lineNumbers: true,
    tokens: {
      keyword: { color: { hex: '#f2b134', model: 'hex' }, bold: true },
      string: { color: { hex: '#3ddc84', model: 'hex' } },
      comment: { color: { hex: '#8a939d', model: 'hex' }, italic: true },
    },
    inline: { background: { hex: '#eef1f4', model: 'hex' } },
  },
};

#Coloration syntaxique

Un petit analyseur lexical intégré au moteur nomme les jetons de js et ts (javascript, jsx, typescript, tsx), json, python, bash (sh, zsh, shell), console (une session de terminal), css, html et xml (svg), markdown et sql ; un listing dans tout autre langage, ou sans langage, est composé en color. Il lit le listing entier : un commentaire ou une chaîne qui s’étend sur plusieurs lignes reste un seul jeton. Dans un listing console, une ligne qui commence par une invite ($ , % , # , > , >>> , PS …> ) est ce que l’utilisateur a tapé (prompt) et toute autre ligne est ce que les programmes ont affiché (output).

Un hôte branche son propre surligneur (Shiki, Prism, highlight.js) avec registerCodeHighlighter. Les configurations sont des données sérialisables : la fonction s’enregistre donc auprès du moteur, elle ne s’écrit pas dans codeStyle :

import { registerCodeHighlighter } from 'postext';
 
// fn(code, lang) returns the listing's lines, each as runs whose texts join into the line.
registerCodeHighlighter('rust', (code) => code.split('\n').map((line) => [
  { text: line, token: line.trimStart().startsWith('//') ? 'comment' : undefined },
]));
registerCodeHighlighter('*', null); // remove the one registered for every language

Un surligneur enregistré pour un langage l’emporte sur un surligneur enregistré pour '*', qui l’emporte lui-même sur l’analyseur intégré. Un segment nomme un genre de jeton token (coloré par tokens) ou une color propre (un hexadécimal CSS). Un surligneur qui renvoie undefined, lève une exception ou renvoie des lignes qui ne reconstituent pas celles du listing est ignoré. La mise en page lit le registre au moment de composer un listing : enregistrez avant de construire, et dans un web worker (le Sandbox met en page dans l’un d’eux), enregistrez à l’intérieur du worker.

#Code en ligne

codeStyle.inline compose le texte placé entre accents graves dans une police de code : d’un seul tenant, comme une pastille, qu’une ligne ne coupe jamais. S’il n’est pas défini, le code en ligne garde la police du texte.

#Composition d’un listing

• Une ligne par ligne de source. Les lignes sont construites à partir des chasses propres à la police de code, pas par l’algorithme de coupure des paragraphes : les espaces gardent leur largeur, une suite d’espaces est conservée, les espaces en tête créent un retrait. Un listing dans un livre de droite à gauche se lit de gauche à droite, ses lignes composées depuis le côté opposé du cadre comme une citation de gauche à droite, ses numéros dans la marge à leur gauche. Dans un livre vertical, un listing suit le flux vertical (son texte latin couché, comme le compose le texte vertical) et ne prend pas de numéros de ligne.
• Coupure. Un listing plus haut que la place restante se coupe entre deux lignes d’une colonne et d’une page à l’autre, chaque partie encadrée séparément, sans jamais laisser moins de splitMinLines lignes d’un côté ; la suite d’une ligne coupée reste avec elle quand une autre coupe tient.
• Sorties. Le canvas, la visionneuse HTML et le PDF peignent les lignes et le cadre tels qu’ils sont mis en page. La visionneuse HTML conserve les espaces (white-space: pre) : une sélection copie le listing avec son indentation et un saut de ligne après chaque ligne de source, sans numéros ni marques de coupure. Un PDF balisé compose chaque listing comme un paragraphe contenant un élément Code, avec de vrais glyphes d’espace, ses numéros et ses marques de coupure étant des artefacts. L’EPUB recomposable écrit <pre><code class="language-…"> avec les couleurs des jetons et une feuille de style tirée de codeStyle ; l’EPUB à mise en page fixe reprend l’imprimé.
• Polices. Le Sandbox et configFontFamilies chargent la police de code quand le texte contient un bloc délimité (ou que la configuration a une section codeStyle), en graisses normale et grasse, en romain et en italique ; le PDF incorpore les polices qu’utilisent les lignes.

#Styles d’encadré

La propriété calloutStyles déclare les styles d’encadré nommés qu’un document applique avec un conteneur :::callout{type="…"} : notes, conseils, avertissements, objectifs d’apprentissage, tout contenu mis à part du texte courant dans un cadre teinté ou bordé. Un style neutre, note, est fourni par défaut (fond gris clair, sans bordure, sans bande, sans icône, sans titre), si bien que :::callout fonctionne sans aucune configuration ; déclarer calloutStyles remplace cette liste par défaut.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
 
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::

#Le conteneur :::callout

Une ligne :::callout{type="<id>"} ouvre l’encadré et une ligne ::: seule le ferme. La clôture accepte cinq attributs : type (l’id du style), title (remplace le titre du style), span, placement et columns (remplacent les valeurs du style) ; le contenu placé entre les deux est mis en page dans l’encadré : un titre facultatif, puis les paragraphes, listes, citations, formules ou ressources intégrées, chacun composé avec la typographie body / lists du style (les titres gardent leurs styles habituels). Les marges entre enfants fusionnent comme dans le texte courant ; l’intérieur quitte la grille de ligne de base, et le flux y revient après l’encadré avec au moins marginBottom en dessous (la grille l’emporte ; la marge est un minimum, la même convention que suivent les ressources). Un style avec snapToGrid: false garde plutôt le marginBottom exact, et le texte qui suit l’encadré reste hors de la grille jusqu’au titre suivant ou à la fin d’une liste. Un titre placé juste avant un encadré reste avec lui.

Limites de cette version :

• Un encadré est gardé entier, sauf si son style fixe keepTogether: false. Quand il ne tient pas dans l’espace restant de la colonne, il passe en entier à la colonne ou à la page suivante, y compris hors d’une colonne vide que des bandes de flottants ou un plafond de bande ont raccourcie, pourvu qu’une colonne pleine puisse le contenir. Un encadré plus haut qu’une colonne pleine se coupe au contraire, comme un encadré sécable ; seul celui qu’aucune coupe ne peut diviser (une figure ou un tableau plus haut que la colonne, ou un splitMinLines qu’aucune coupe ne satisfait) est placé malgré tout et déborde ; la mise en page enregistre alors un avertissement calloutOverflow (VDTDocument.warnings), que le Sandbox liste. Un groupe :::columns se coupe comme l’encadré qui l’entoure, entre ses sous-colonnes (depuis postext 1.25) ; il reste entier, et peut déborder de la même façon, seulement avec layout.flowColumns: false ou à l’intérieur d’un encadré imbriqué. Un encadré sécable laisse derrière lui la partie qui tient (des enfants entiers, ou les lignes d’un paragraphe jusqu’à splitMinLines de chaque côté ; une figure, un tableau ou une formule centrée suffisent à eux seuls pour un côté) et continue dans un encadré sans icône sur la colonne ou la page suivante, sans le titre sauf si le style le répète, et éventuellement avec une marque sous la partie qu’il laisse (voir Marques sur un encadré coupé).
• Les flottants cèdent la place à un encadré insécable. Quand le bloc qui suit immédiatement la référence d’une figure est un encadré keepTogether, un emplacement qui ne laisserait à l’encadré aucune colonne de la bande en cours où se poser (la colonne de la référence ou une colonne vide après elle, qui le contenait avant le flottant) n’est pas pris : la figure passe à son emplacement suivant, en général la page suivante, et l’encadré reste dans le flux, comme le composerait un compositeur, plutôt que de chasser l’encadré de la page et de laisser la colonne avec la figure seule.
• span: 'page' dans une mise en page à plusieurs colonnes fait de l’encadré un bloc pleine largeur : il est mis en page sur toute la largeur de contenu et découpe la page en bandes de colonnes ; les colonnes de texte au-dessus sont fermées à la ligne de coupe, l’encadré occupe sa propre colonne pleine largeur, et une nouvelle bande de colonnes de texte s’ouvre en dessous, si bien que le flux continue sous l’encadré dans chaque colonne. Là où les colonnes sont à niveau (en haut d’une page, juste sous un titre d’ouverture span: 'page', juste sous un autre bloc pleine largeur, ou juste sous une bande de flottants de tête), l’encadré coupe simplement à cet endroit. S’il arrive en milieu de page, avec des colonnes inégales, il est composé comme le ferait un compositeur : le texte au-dessus est coupé à niveau sur toutes les colonnes (le moteur relance le placement avec les colonnes de la bande raccourcies au même nombre de lignes de grille, si bien que le texte passe naturellement d’une colonne à l’autre et que chaque règle d’orpheline, de veuve et de maintien avec le suivant s’applique toujours), l’encadré couvre la page et les colonnes reprennent en dessous. La coupe demande quelques passes de placement supplémentaires ; quand la ligne de coupe ne laisserait pas de place pour l’encadré plus le minimum de lignes de texte contre les veuves en dessous, ou qu’aucune disposition ne convient après quelques essais, l’encadré passe en haut de la page suivante. Le texte au-dessus respecte la coupe : un paragraphe qui ne peut pas commencer dans les quelques lignes qu’une colonne garde sous une figure au-dessus de la coupe passe à la colonne suivante (la figure reste alors seule dans sa colonne), et quand un bloc dépasserait encore la coupe, la coupe est prise une ligne plus bas plutôt qu’à la fin de ce bloc. Un encadré coupé qui ouvre la bande est coupé là aussi, si bien que son reste ne dépasse jamais la coupe. Avec headings.balancing.beforeSpan (la valeur par défaut), la bande qu’il quitte est coupée à niveau derrière lui (comme la bande qui clôt un chapitre) et, quand le style permet la coupe (keepTogether: false), la partie de l’encadré qui tient sous les colonnes mises à niveau ferme la page et le reste ouvre la suivante ; avec beforeSpan: false, la page qu’il quitte est simplement équilibrée comme d’habitude, sans forcer de saut de page. Un titre placé juste avant un bloc pleine largeur ne voyage pas avec lui. Dans les mises en page à une colonne, span: 'page' est simplement en ligne.
• placement: 'fixed' retire l’encadré du flux : il est mis en page (width: 'auto' s’ajuste au titre ; 'fill' prend la largeur de la colonne de texte sous le point d’ancrage) et épinglé sur la page où il apparaît dans le flux, à la position que décrivent fixed.anchor / fixed.offset (par défaut, le coin inférieur gauche de la zone de contenu). Les colonnes de texte qu’il recouvre lui cèdent cette zone (coupée par le bas, ou par le haut quand la colonne est encore vide), exactement comme une bande de flottants ; quand la zone contient déjà du texte, un flottant ou un bloc pleine largeur, l’encadré passe à la page suivante. Un encadré fixe qui clôt le chapitre (le bloc suivant est une ouverture de chapitre, un :::part, un encadré barrière pour les flottants ou la fin du document) met d’abord à niveau les colonnes au-dessus de lui (headings.balancing.trailing), si bien qu’une dernière page courte se termine à niveau avec le badge en dessous. Le cadre et les enfants vivent dans page.floats et sont rendus hors du découpage des colonnes dans tous les moteurs de rendu.
• placement: 'top' | 'bottom' fait flotter l’encadré comme une ressource : il quitte le flux là où il apparaît et prend la première bande libre après ce point (le pied de la page en cours ('bottom'), ou la tête / le pied de la page suivante qu’ouvre le flux), à la largeur de la colonne (span: 'column') ou sur toute la largeur de contenu (span: 'page') ; le texte qui le suit remplit la page qu’il a quittée. Son cadre et ses enfants vont dans page.floats, comme pour un encadré fixe. Un encadré flottant en tête d’une nouvelle page est placé avant les figures qui attendent cette page, et une figure citée sur une page précédente qui tient ensuite sous lui prend le reste de cette page même quand il resterait moins de trois lignes de texte (une page de galerie : encadré plus figure, sans texte entre eux). Un encadré span: 'side' ne flotte jamais : il s’empile à côté du texte quel que soit son placement. Avec columns supérieur à 1 (dans le style ou comme attribut de la clôture, depuis postext 1.18), un encadré span: 'column' occupe autant de colonnes adjacentes : la tête d’une suite de colonnes vides qui commencent à niveau, ou le pied de la colonne en cours et des colonnes vides qui la suivent, comme dans :::callout{placement="top" columns="2"}.
• width: 'auto' s’ajuste au titre seulement ; les enfants sont ignorés.
• Un :::callout imbriqué dans un autre encadré est un encadré à part entière : il est mis en page avec son propre style (fond, bordure, rayon, marge intérieure, bande, titre, icône, marque, onglet, typographie) sur toute la largeur intérieure de son parent et s’empile comme un enfant de celui-ci, ses marginTop / marginBottom fusionnant avec ses voisins. Son span et son placement (de la clôture ou du style) sont ignorés (un encadré imbriqué suit toujours le flux de son parent), tout comme floatBarrier et snapToGrid. Les encadrés s’imbriquent à toute profondeur et peuvent se trouver dans un groupe :::columns (chacun entier, dans une colonne). Quand le parent se coupe, la coupe tombe avant ou après un encadré imbriqué, ou à l’intérieur quand le style imbriqué permet la coupe ; chaque fragment redessine les cadres qu’il traverse, et un encadré imbriqué qui continue depuis le fragment précédent perd son titre et son icône, comme une suite de premier niveau.
• Un groupe :::columns{count=N} … ::: parmi les enfants dispose ces enfants en N colonnes de même largeur, séparées de columnGap, dans l’encadré : la suite est coupée aux limites de bloc ou de ligne qui mettent le mieux les colonnes à niveau (un paragraphe ou un élément de liste coupé au milieu continue en tête de la colonne suivante sans sa puce), chaque colonne commence en haut du groupe et le groupe est aussi haut que sa colonne la plus haute ; les enfants qui le suivent reviennent à toute la largeur. Un encadré qui se coupe (keepTogether: false, ou plus haut qu’une colonne) coupe aussi à l’intérieur d’un groupe, entre ses colonnes : un groupe en serpentin remplit ses colonnes tour à tour et continue dans le fragment suivant, un groupe parallèle (breaks) continue flux par flux (depuis postext 1.25 ; voir Format du document › :::columns). Un gap sur la clôture remplace columnGap pour ce groupe, et rule trace un filet dans chaque gouttière. Utilisez-le pour un résumé des points clés sur deux colonnes, ou pour les tableaux d’un large encadré placés côte à côte.
• Le sixième attribut de la clôture, label, s’imprime sur l’onglet du style (voir label plus haut) : :::callout{type="box" label="BOX 1-1" title="The octet rule"} ; sans style label, l’attribut est ignoré.

Dans le VDT, l’encadré est un bloc cadre type: 'callout' dont la décoration (fond, bande, icône, titre) vit dans designOverlay, suivi de ses blocs enfants dans la même colonne ; le cadre et chaque enfant portent le containerId de la clôture. Un encadré imbriqué est un cadre type: 'callout' à part parmi les enfants, suivi de ses blocs ; ceux-ci gardent le containerId de la clôture de premier niveau (le placement et l’équilibrage voient toujours une seule unité) et ajoutent calloutPath, les id de conteneur des clôtures imbriquées qui les entourent, de la plus extérieure à la plus intérieure (l’id propre d’un cadre imbriqué est la dernière entrée). Le PDF balisé donne à chaque encadré imbriqué un Div à l’intérieur de celui de son parent. Les images d’icône se résolvent comme les images de ressource : le registre d’images du canvas, l’option HTML resourceImageUrl et le fournisseur PDF resourceBytes.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => every inherited field filled from the resolved sections; the optional
//    locale picks the language of the continuation strings
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped

#Énoncés numérotés et démonstrations

Un style doté de numbering compte ses encadrés, comme amsthm de LaTeX compte les environnements de théorème (depuis postext 1.19). Chaque encadré imprime son étiquette et son numéro (« Theorem 2. » en ouverture de son premier paragraphe), et le title de la clôture suit le numéro entre parenthèses : :::callout{type="theorem" title="Bradley–Terry"} s’ouvre sur « Theorem 2 (Bradley–Terry). ». Un encadré ouvert avec un identifiant ({#thm:main}) est une cible de renvois, qui impriment « Theorem 2 » (:ref{id="thm:main"}), et \ref{thm:main} ou style=number imprime 2.

Une démonstration est un style avec une étiquette non numérotée et une marque de fin :

calloutStyles: [
  { id: 'theorem', numbering: { label: 'Theorem' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lemma', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definition' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Proof', counter: false, bold: false, italic: true } },
]

Dans un livre mis en page chapitre par chapitre, les compteurs reprennent depuis le chapitre précédent (LayoutContinuation.statementCounters, que remplit continuationAfter), et le plan du livre donne à l’ancre de chaque encadré numéroté son étiquette (OutlineEntry.numberLabel), si bien qu’un renvoi depuis un autre chapitre l’imprime.

#Typographie dans un encadré

Un encadré compose son contenu avec sa propre typographie body et lists ; tout le reste garde les styles du document :

• Les paragraphes prennent le body de l’encadré : caractère, taille, interlignage, couleur, couleurs d’emphase, graisses, italic, smallCaps, alignement, césure, retrait et espacement des paragraphes. Un champ non défini hérite de bodyText. Une couleur d’emphase héritée garde son lien à la palette, si bien que le gras, l’italique et les étiquettes :ref d’un encadré changent avec colorPalette comme à l’extérieur. (Jusqu’à postext 1.4, le gras d’un encadré restait #295AA3 quelle que soit la Main Color.)
• Les listes à puces prennent les lists de l’encadré (caractère de puce, couleur, taille et graisse du glyphe, retrait, écart, espacement des éléments) par-dessus unorderedLists, et leur texte est le texte de l’encadré. Un lists.bulletChar ou un lists.color différent de celui du document (unorderedLists) remplace la puce ou la couleur de tous les niveaux ; s’il le répète, ou s’il n’est pas défini, chaque niveau garde la sienne (unorderedLists.levels), si bien que les tirets imbriqués survivent dans l’encadré.
• Les listes numérotées prennent lists.indent, gap et itemSpacing, et lists.color dès que le style le fixe, y compris quand c’est la couleur de puce du document ; un style qui ne le fixe pas garde les numéros dans orderedLists.color. (Jusqu’à postext 1.4, la couleur n’atteignait les numéros que si elle différait de unorderedLists.color, si bien que lui donner cette couleur même n’avait aucun effet.) Le numéro lui-même (son caractère, sa taille et son séparateur) vient du orderedLists global, puisque lists n’a que des champs de puce : c’est là qu’il faut styler les numéros d’un encadré.
• Les :::paragraphs dans un encadré utilisent leur style de paragraphe, dans les encadrés imbriqués aussi. Les champs que le style laisse non définis héritent du bodyText du document, non du body de l’encadré (ni de son italique ou de ses petites capitales).
• Les groupes :::columns n’ont pas de style propre : toutes les colonnes partagent la typographie du texte et des listes de l’encadré, et columnGap fixe l’écart entre elles.
• Les citations prennent le caractère, la taille et les graisses du texte de l’encadré (en italique et en gris, comme dans le texte courant), ainsi que ses petites capitales. Les titres gardent les styles de titre ; les formules centrées, les réglages mathématiques.
• Les figures et tableaux gardent les styles de légende et de tableau du document, à la largeur intérieure de l’encadré ; leurs graisses normale et grasse suivent les graisses du body de l’encadré.
• Les pastilles gardent leur style de pastille ; une taille en em se lit par rapport à la taille du texte de l’encadré.
• :::space se mesure en lignes du texte de l’encadré (voir :::space pour les cas où il est supprimé).
• Un encadré imbriqué prend entièrement son propre style ; ses span, placement, floatBarrier et snapToGrid sont ignorés.

#Marques sur un encadré coupé

Quand un encadré se coupe entre colonnes ou pages (keepTogether: false, ou un encadré plus haut qu’une colonne), chaque partie après la première s’ouvre sans le titre ni l’icône, et par défaut rien n’indique au lecteur que l’encadré continue. Deux options ajoutent les marques qu’emploie un livre ou un scénario :

• repeatTitle: true répète le titre en tête de chaque suite, suivi de continuedSuffix (« Key points (cont.) » par défaut). La répétition prend le style du titre : avec textTransform: 'uppercase', elle donne le « HAMLET (CONT'D) » d’un scénario. L’icône et l’onglet restent sur la première partie.
• continuesMarkerEnabled: true place continuesMarker (« Continued », ou « Continúa » dans un document espagnol) sous la dernière ligne de chaque partie qui se poursuit, à l’intérieur de l’encadré, dans le caractère et la taille du texte de l’encadré : en italique sauf si continuesMarkerItalic vaut false, au fer à droite sauf si continuesMarkerAlign indique 'left' ou 'center'. La marque prend de la place dans la partie qu’elle clôt, et la coupe est choisie pour qu’elle tienne.

calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::

La partie qui clôt la page se termine par « (MORE) », et la page suivante s’ouvre sur « HAMLET (CONT'D) ». Les deux relèvent de l’habillage de pagination : dans un PDF accessible, ce sont des artefacts, et dans le HTML elles sont masquées aux technologies d’assistance, si bien que le titre n’est lu qu’une fois. Dans le VDT, ce sont des blocs de texte designOverlay marqués artifact: true.

#Parties

La propriété parts configure les pages de partie qu’un document ouvre avec un conteneur :::part{number="…" title="…"} : la page « Partie I — Fondements » qui regroupe une suite de chapitres. Une partie occupe toujours une page à elle : le conteneur saute à une nouvelle page de la parité configurée, la convertit en page à une seule colonne dont la zone de texte vient de parts.margins, pose la maquette d’ouverture sur toute la page, et saute de nouveau après la clôture finale pour que le chapitre suivant (avec son propre breakBefore.parity) commence proprement ; avec les réglages par défaut du H1, on obtient la page de partie classique sur un recto, un verso blanc, et le chapitre sur le recto suivant.

const config: PostextConfig = {
  parts: {
    breakBefore: { parity: 'odd' },
    breakAfter: { enabled: true, parity: 'any' },
    margins: { top: { value: 9, unit: 'cm' }, left: { value: 3, unit: 'cm' }, right: { value: 3, unit: 'cm' } },
    design: {
      elements: [
        {
          kind: 'text', id: 'number', content: 'Part {numberRoman}',
          fontSize: { value: 12, unit: 'pt' }, fontWeight: 600, align: 'left',
          placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 3, unit: 'cm' }, y: { value: 5, unit: 'cm' } }, size: { width: 'auto', height: 'auto' } },
        },
        {
          kind: 'text', id: 'title', content: '{titleText}',
          fontSize: { value: 28, unit: 'pt' }, fontWeight: 700, align: 'left', overflow: 'wrap',
          placement: { anchor: { to: '#number', edge: 'below' }, size: { width: { value: 15, unit: 'cm' }, height: 'auto' } },
        },
      ],
    },
    bodyStyle: { fontSize: { value: 11, unit: 'pt' }, numberColor: { hex: '#AA0000', model: 'hex' } },
  },
};

:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
3. Reading the weather
:::
 
# The lantern and its parts

#Variables de la maquette de partie

L’emplacement de maquette résout le jeu de variables des titres avec les valeurs propres à la partie : {titleText} est le title de la clôture ; {number}, le number tel qu’il est écrit ; {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower} le reformatent. Le numéro est lu comme un nombre décimal, un chiffre romain ou des chiffres chinois, avec ou sans les mots qui les encadrent ("IV", "iv", "4", "４", "四", "卷四" et "第四卷" donnent tous {numberDecimal} = 4), et ces variables valent '' pour toute autre chose. {partTitle} / {partNumber}, {chapterTitle} / {chapterNumber} (le chapitre qui précède la partie), {pageNumber}, {totalPages}, {bookTotalPages} et les variables de métadonnées sont aussi disponibles. {attr.<key>} lit les attributs du H1 du chapitre en cours.

#La maquette du verso

versoDesign décore la page qui suit immédiatement une page de partie quand cette page ne contient rien : le dos du feuillet de partie. La partie elle-même ne laisse jamais cette page blanche. breakAfter.parity vaut 'any' par défaut, si bien que le contenu qui suit la clôture commence sur la page suivante, sauf si quelque chose demande une parité :

• Le titre du chapitre suivant. Le breakBefore par défaut du H1 est 'always-odd', et 'odd' fait de même après une page de partie sur un recto : le chapitre passe au recto suivant et le verso reste blanc. La maquette du verso se peint.
• parts.breakAfter: { enabled: true, parity: 'odd' }. La partie demande elle-même le recto suivant, quoi que fasse le titre suivant. Utilisez-le quand les chapitres peuvent s’ouvrir d’un côté comme de l’autre (breakBefore.parity: 'any', ou breakBefore.enabled: false).

Sans l’un ni l’autre, le chapitre s’ouvre sur le verso et aucune maquette de verso n’est dessinée. Avec breakAfter.enabled: false, le contenu continue sur la page de partie elle-même. Le verso prend la palette de la partie : un palette="band=#…" sur la clôture le recolore aussi.

parts: {
  breakBefore: { parity: 'odd' },
  breakAfter: { enabled: true, parity: 'odd' },   // always a blank verso to paint
  versoDesign: {
    elements: [{
      kind: 'box', id: 'field',
      style: { backgroundColor: { hex: '#b07d2b', model: 'hex', paletteId: 'band' } },
      placement: { anchor: { to: 'page', edge: 'top-left' }, size: { width: 'fill', height: 'fill' } },
    }],
  },
}

Une partie qui clôt son chapitre. Dans un livre mis en page chapitre par chapitre (le Sandbox, buildBundle), une clôture :::part peut être un chapitre à elle seule, ou la fin d’un chapitre. Sa page de partie est alors la dernière page du chapitre, et le chapitre suivant reprend ce que la partie doit encore : il applique breakAfter avant son premier bloc et peint versoDesign sur sa première page quand cette page reste blanche. Les pages sortent comme elles sortiraient avec tout le livre dans un seul document. Seules des directives qui ne placent rien (:::numbering, :::space) peuvent suivre la clôture ; tout le reste est du contenu du chapitre, qui prend alors le saut lui-même. Un chapitre vide juste après la partie est une page à lui seul : cette page est le verso. Un hôte qui met lui-même les chapitres en page obtient ce comportement de continuationAfter(), qui signale afterPartPage: true pour un chapitre qui se termine par une partie ; transmettez-le dans la continuation du chapitre suivant.

#Le conteneur :::part

Une ligne :::part{number="…" title="…"} ouvre la partie et un ::: seul la ferme ; les deux attributs sont facultatifs (ils valent '' par défaut). Les blocs placés entre les deux (en général la liste des chapitres) s’écoulent dans la colonne unique de la page de partie avec bodyStyle, à partir de margins.top ; un contenu plus long que la page continue sur des pages ordinaires. La page est classée role: 'part' (VDTPage.partInfo porte le numéro et le titre), si bien que les éléments d’en-tête et de pied de page peuvent la cibler ou l’éviter avec pages: 'part' / pages: 'body' ; le moteur PDF ajoute la partie aux signets, au-dessus de ses chapitres. Un contenu vide (:::part{…} directement suivi de :::) est le cas courant et produit quand même la page : des parties consécutives ne partagent jamais une page. Un :::part imbriqué dans une autre partie est aplati dans la partie extérieure.

Un troisième attribut, palette="<id>=<hex>[, <id>=<hex>…]", donne à la partie ses propres couleurs : sur la page de partie et sur chaque page qui la suit, jusqu’à la partie suivante, chaque couleur de maquette (en-tête, pied de page, bandeau d’ouverture, maquettes de partie et de verso) liée à l’un de ces id de palette prend la valeur de la partie au lieu de celle de la palette du document. C’est ainsi que les sections d’un livre recolorent l’onglet de coin, le point du titre courant et le bandeau d’ouverture de chapitre sans seconde maquette : :::part{number="II" title="…" palette="band=#f6c297"}. Le flux de texte suit aussi : sur les mêmes pages, toute couleur du flux égale à la valeur de base d’une entrée de palette remplacée (titres, couleurs du gras, de l’italique et des renvois, puces et numéros de liste, étiquettes et barres de légende, texte, filets et fonds des tableaux (en-tête, corps, lignes alternées et fond propre d’une cellule), encadrés (fond, bordure, bande, titre) et pastilles (fond, contour et texte)) prend la valeur de la partie, si bien qu’un headings.levels[1].color lié à band compose les titres de chaque section dans sa propre couleur. Les pastilles de couleur en ligne gardent la couleur écrite en elles. Les paires sont séparées par des virgules, des points-virgules ou des espaces, = ou : joint l’id et la couleur, le # est facultatif. Une partie reste en vigueur après la fermeture de sa clôture : {partTitle}, {partNumber} et la palette suivent le flux dans les chapitres qui la suivent et, grâce à continuation.part, que signale continuationAfter(), dans les chapitres mis en page séparément, si bien que le deuxième chapitre d’une section affiche la section dans ses titres courants exactement comme le premier.

Deux entrées de palette peuvent partager une valeur de base et prendre pourtant des valeurs différentes dans une partie, quand la partie remplace l’une et pas l’autre ou leur donne des couleurs différentes. La valeur seule ne dit pas de quelle entrée vient une couleur du flux : chaque couleur du flux est donc rapprochée des réglages dont elle peut venir, et prend la valeur à laquelle ces réglages sont liés. Sont distingués :

• les couleurs du texte d’un bloc : la couleur du texte, les couleurs du gras, de l’italique et des renvois, la marque de liste (une puce ou un numéro) et le séparateur qui suit un numéro. Avec bodyText.color lié à ink et bodyText.boldColor lié à accent, tous deux #1a1a1a, une partie avec palette="accent=#b8413d" recolore les passages en gras et laisse le texte ; avec plutôt unorderedLists.color lié à accent, elle recolore les puces et laisse le texte des éléments ;
• chaque niveau de titre, et chaque style de titre qui fixe une couleur ;
• le texte d’une ligne de la table des matières, son numéro, ainsi que son numéro de page et son sous-titre ;
• dans chaque style d’encadré, les fonds (fond, bande, onglet), la bordure, les filets (marque et onglet) et le texte (titre, icône, glyphe de la marque, onglet) ;
• chaque couleur de chaque style de tableau, de pastille et de légende. Un style de tableau nommé est distinct de tableStyle, et le style de légende d’un type de ressource de captionStyle. Le fond propre d’une cellule suit son propre lien.

Un cas se décide encore par la valeur : des réglages situés à des endroits différents qui fixent la même couleur d’un bloc. bodyText.color, bodyText.blockquote.color, le color d’un style de paragraphe et le body.color d’un style d’encadré fixent tous la couleur du texte d’un bloc, par exemple. Quand deux d’entre eux sont liés à des entrées qui partagent une valeur de base et que la partie les distingue, la couleur prend le remplacement (le dernier écrit, quand les deux sont remplacés). Donnez à ces entrées des valeurs de base qui leur sont propres.

const resolved = resolvePartsConfig(config.parts, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => margins filled from the page, bodyStyle from the body / list configs
 
const minimal = stripPartsDefaults(config.parts);
// => undefined when only static defaults remain

#Styles de titre

La propriété headingStyles déclare des styles nommés qu’un document applique à un titre avec # Title {style="<id>"}. Un style fait deux choses. Il remplace la typographie, la maquette et la numérotation du niveau du titre (tous les champs d’une entrée de niveau sauf level : police, taille, couleur, breakBefore, span, advancedDesign, textTransform, hidden, numberingTemplate…) et il régit la section que le titre ouvre : ses pages, jusqu’au titre suivant de même niveau ou de niveau supérieur, prennent les titres courants, la géométrie de page, la typographie du texte et la palette du style. C’est ainsi que les pages liminaires d’un livre (une préface sur une seule colonne large, avec des folios en chiffres romains et des bandeaux bleus) prennent place dans un manuel à deux colonnes numéroté en chiffres arabes, sans seconde configuration.

const config: PostextConfig = {
  headingStyles: [
    {
      id: 'front-matter',
      numbered: false,
      breakBefore: { enabled: true, parity: 'odd' },
      span: 'page',
      advancedDesign: { enabled: true, minHeight: { value: 52, unit: 'mm' }, slot: { elements: [/* bands, `{titleText}` */] } },
      header: { elements: [/* folio | rule | `{title}. {subtitle}` */] },
      margins: { left: { value: 50, unit: 'mm' }, right: { value: 17, unit: 'mm' } },
      layout: { layoutType: 'single' },
      bodyStyle: { fontSize: { value: 10.5, unit: 'pt' }, textAlign: 'justify' },
      palette: { band: '#547396' },
    },
  ],
};

# Preface {style="front-matter"}

Une section se ferme au titre suivant de même niveau ou de niveau supérieur : un # sans style après un titre stylé revient aux titres courants et à la géométrie du document ; un titre stylé ouvre sa propre section. Les pages que la section a laissées blanches pour la parité lui appartiennent, comme pour les titres de chapitre.

Un saut de page ne remplace pas le saut propre au titre. Un style hérite du breakBefore de son niveau (la valeur par défaut du niveau 1 est { enabled: true, parity: 'always-odd' }), et un titre l’applique où qu’il se trouve, juste après un :::pagebreak aussi. Le saut de page ouvre une nouvelle page, puis le titre demande encore son côté de la double page. Avec parity: 'odd', un saut qui tombe sur un verso est suivi d’une page blanche, si bien que le titre s’ouvre sur le recto suivant. Avec 'always-odd', la page blanche de séparation s’ajoute aussi, et le saut de page ne change rien, puisque le titre aurait de toute façon ouvert cette page. Un style destiné à commencer sur la page qu’ouvre un saut manuel, comme une page de table des matières après la page de titre, désactive son propre saut :

headingStyles: [
  // Starts where the text puts it: on the page the `:::pagebreak` before it opened.
  { id: 'contents', numbered: false, toc: false, breakBefore: { enabled: false } },
],

Pour garder une page à soi sans choisir de côté, réglez plutôt breakBefore: { parity: 'any' } et omettez le :::pagebreak.

À quelle section appartient une page. Les titres courants et la palette se choisissent par page, non par titre. Une page prend la section en vigueur après le dernier changement de section qu’elle contient : là où une section se termine et une autre commence sur la même page (deux courtes lettres d’un dictionnaire, par exemple), la page porte les titres courants et la palette de la seconde ; là où une section stylée se termine au milieu de la page sur un titre sans style, la page revient à ceux du document. {chapterTitle} suit la même règle : une page où deux chapitres se rencontrent affiche le titre du second. Les pages blanches suivent la règle des titres de chapitre : une page blanche de parité (blankForParity) appartient à la section qui s’ouvre après elle, et la page de séparation qu’ajoute un saut 'always-odd' / 'always-even' (blankForForce) à la section qui la précède. Une page de partie ferme la section ouverte.

# A {style="letter"}
 
Aardvark, abacus.
 
# B {style="letter"}
 
Babble, badger… (runs on to the next page)

Les deux lettres commencent en page 1 : la page 1 prend donc les titres courants de la section B. Un onglet de tranche placé dans l’en-tête du style y affiche « B », et aucune page ne porte l’onglet de « A ». Donnez à chaque section une page à elle (breakBefore) quand chacune a besoin de son onglet. Des annexes désignées par des lettres après des chapitres numérotés, et une page de dédicace que la table des matières et les signets PDF listent, mais dont la page n’affiche pas le titre :

headingStyles: [
  { id: 'appendix', numberingTemplate: 'Appendix {1:A}' },
  { id: 'silent', hidden: true, numbered: false },
],

# Dedication {style="silent"}
 
For M., who read every draft.
 
# Method
 
…
 
# Survey instrument {style="appendix" startAt=1}
 
# Raw data {style="appendix"}

Avec numberingTemplate: '{1}.' au niveau 1, les chapitres impriment 1., 2.…, les annexes Appendix A et Appendix B. La dédicace ouvre sa page (le breakBefore de son niveau), n’imprime que son paragraphe et apparaît malgré tout sous le nom Dedication dans :::toc, dans les titres courants {chapterTitle} et dans les signets du PDF ; ajoutez toc: false au style pour l’exclure de la table des matières. Une planche ou une carte composée comme un H1 au milieu d’un chapitre demande l’inverse de la dédicace : un style avec runningChapter: false (en général avec numbered: false et toc: false) garde les titres courants sur le chapitre qu’elle interrompt.

const resolved = resolveHeadingStylesConfig(config.headingStyles, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => level overrides normalised, margins filled from the page, bodyStyle from the body
 
const minimal = stripHeadingStylesDefaults(config.headingStyles);
// => undefined when no style remains