>` | eine ruhige Palette | Das Aussehen jeder Token-Art, Art für Art mit den Standardwerten zusammengeführt (siehe unten). Eine an die Palette gebundene Farbe folgt `colorPalette` und der Palette eines Teils. |
| `inline` | `InlineCodeStyleConfig` | nicht gesetzt | Inline-Code in einer Code-Schrift (siehe unten). Nicht gesetzt, wird Inline-Code in der Schrift des Texts gesetzt, wie vor 1.23. |
### Syntaxhervorhebung
Ein kleiner, in die Engine eingebauter Tokenizer benennt die Token von `js` und `ts` (`javascript`, `jsx`, `typescript`, `tsx`), `json`, `python`, `bash` (`sh`, `zsh`, `shell`), `console` (eine Shell-Sitzung), `css`, `html` und `xml` (`svg`), `markdown` und `sql`; ein Listing in jeder anderen Sprache oder ohne Sprache wird in `color` gesetzt. Er liest das ganze Listing, sodass ein Kommentar oder eine Zeichenkette, die über Zeilen läuft, ein Token bleibt. In einem Listing `console` ist eine Zeile, die mit einem Prompt beginnt (`$ `, `% `, `# `, `> `, `>>> `, `PS …> `), das, was der Benutzer eingegeben hat (`prompt`), und jede andere Zeile das, was die Programme ausgegeben haben (`output`).
| Art | Standard | Was sie benennt |
| --- | --- | --- |
| `keyword` | `#8b2c8f` | Reservierte Wörter: `const`, `def`, `if`, `SELECT`, ein HTML-Tag-Name, eine CSS-At-Regel. |
| `string` | `#3d7a2a` | Zeichenketten, Template-Literale, Attributwerte. |
| `number` | `#985f00` | Zahlen und Konstanten (`true`, `None`, `null`), Farben, Entitäten. |
| `comment` | `#7a7f87`, kursiv | Kommentare. |
| `function` | `#2b5fb4` | Ein Name, gefolgt von einer Klammer; Shell-Builtins. |
| `type` | `#99540a` | Typen und großgeschriebene Klassennamen, CSS-Selektoren. |
| `operator` | die Farbe des Codes | Operatoren, Shell-Pipes und -Umleitungen. |
| `punctuation` | die Farbe des Codes | Klammern, Trennzeichen. |
| `variable` | `#b23b2e` | Shell-Variablen, JSON-Schlüssel, CSS-Eigenschaften, HTML-Attribute, `self`. |
| `meta` | `#985f00` | Dekoratoren, Kommandozeilenoptionen (`-l`, `--all`), ein Doctype. |
| `prompt` | die Farbe des Codes, fett | Die eingegebene Zeile einer Shell-Sitzung. |
| `output` | `#5c6168` | Was die Programme ausgegeben haben. |
Ein Host bindet mit `registerCodeHighlighter` seinen eigenen Highlighter ein (Shiki, Prism, highlight.js). Konfigurationen sind serialisierbare Daten, daher wird die Funktion bei der Engine registriert, nicht in `codeStyle` geschrieben:
```ts
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
```
Ein für eine Sprache registrierter Highlighter hat Vorrang vor einem für `'*'` registrierten, der wiederum Vorrang vor dem eingebauten Tokenizer hat. Ein Textlauf nennt eine Token-Art `token` (eingefärbt über `tokens`) oder eine eigene `color` (ein CSS-Hexwert). Ein Highlighter, der `undefined` liefert, eine Ausnahme wirft oder Zeilen liefert, die sich nicht zu denen des Listings zusammenfügen, wird übergangen. Das Layout liest das Register, wenn es ein Listing setzt: Registrieren Sie vor dem Build, und in einem Web Worker (die Sandbox setzt in einem) registrieren Sie innerhalb des Workers.
### Inline-Code
`codeStyle.inline` setzt Text zwischen Backticks in einer Code-Schrift: als eine Einheit, wie einen Chip, in der eine Zeile nie umbricht. Nicht gesetzt, behält Inline-Code die Schrift des Texts.
| Eigenschaft | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `fontFamily` | `string` | `codeStyle.fontFamily` | Die Schrift. |
| `fontSize` | `Dimension` | `0.9em` | `em` ist die Größe des umgebenden Texts. |
| `color` | `ColorValue` | die des Texts | |
| `bold` / `italic` | `boolean` | `false` | Zusätzlich zu den eigenen Auszeichnungen des Texts (Code in fettem Text ist fett). |
| `background` | `ColorValue` | keine | Eine Fläche hinter dem Abschnitt. |
| `borderColor` / `borderWidth` | `ColorValue` / `Dimension` | keine / `0.5pt` | Eine Umrisslinie. |
| `borderRadius` | `Dimension` | `0.2em` | `em` ist die Größe des Abschnitts. |
| `paddingX` / `paddingY` | `Dimension` | `0.2em` mit Fläche oder Umrisslinie, sonst `0` / `0.1em` | Raum innerhalb der Fläche; der senkrechte Innenabstand wird außerhalb des Zeilenkastens gezeichnet. |
### Wie ein Listing gesetzt wird
- **Eine Zeile pro Quellzeile.** Die Zeilen werden aus den eigenen Dickten der Code-Schrift gebildet, nicht vom Absatzumbruch: Leerzeichen behalten ihre Breite, eine Folge davon bleibt erhalten, führende Leerzeichen rücken ein. Ein Listing in einem Buch mit Leserichtung von rechts nach links liest sich von links nach rechts, seine Zeilen werden von der gegenüberliegenden Seite des Kastens aus gesetzt, wie ein Zitat mit Leserichtung von links nach rechts, seine Nummern stehen in der Leiste links davon. In einem vertikal gesetzten Buch folgt ein Listing dem vertikalen Fluss (sein lateinischer Text seitlich gedreht, wie ihn vertikaler Text setzt) und erhält keine Zeilennummern.
- **Teilung.** Ein Listing, das höher als der verbleibende Raum ist, teilt sich zwischen Zeilen über Spalten und Seiten, jeder Teil als eigener Kasten gerahmt, und lässt nie weniger als `splitMinLines` Zeilen auf einer Seite; der Rest einer umbrochenen Zeile bleibt bei ihr, wenn ein anderer Schnitt passt.
- **Ausgaben.** Canvas, HTML-Betrachter und PDF zeichnen die Zeilen und den Kasten so, wie sie umbrochen sind. Der HTML-Betrachter behält die Leerzeichen (`white-space: pre`), sodass eine Auswahl das Listing mit seiner Einrückung und einem Zeilenvorschub nach jeder Quellzeile kopiert, ohne Nummern oder Umbruchzeichen. Ein getaggtes PDF setzt jedes Listing als Absatz mit einem Element `Code`, mit echten Leerzeichen-Glyphen, seine Nummern und Umbruchzeichen als Artefakte. Das umfließende EPUB schreibt `` mit den Farben der Token und einem Stylesheet aus `codeStyle`; das EPUB mit festem Layout entspricht dem Druck.
- **Schriften.** Die Sandbox und `configFontFamilies` laden die Code-Schrift, wenn der Text einen Codeblock enthält (oder die Konfiguration einen Abschnitt `codeStyle` hat), in ihren normalen und fetten Schnitten, aufrecht und kursiv; das PDF bettet die Schnitte ein, die die Zeilen verwenden.
## Kastenstile
Die Eigenschaft `calloutStyles` deklariert die benannten Kastenstile, die ein Dokument mit einem Container `:::callout{type="…"}` anwendet – Anmerkungen, Tipps, Warnungen, Lernziele, jeder Inhalt, der in einem getönten oder umrandeten Kasten vom Fließtext abgesetzt wird. Ein neutraler Stil, `note`, ist standardmäßig dabei (hellgrauer Hintergrund, kein Rahmen, kein Streifen, kein Symbol, kein Titel), sodass `:::callout` ohne jede Konfiguration funktioniert; wer `calloutStyles` deklariert, ersetzt diese Standardliste.
```ts
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' } },
},
],
};
```
```md
:::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.
:::
```
| Eigenschaft | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `id` | `string` | — | Bezeichner, den `:::callout{type="…"}` auswählt. Eine Einfassung mit unbekanntem oder fehlendem `type` verwendet den ersten konfigurierten Stil (die Sandbox meldet unbekannte Typen). |
| `name` | `string` | `id` | Lesbarer Name (nur für die Editor-Oberfläche). |
| `title` | `string` | `''` | Standardtitel; leer bedeutet kein Titel. Das Attribut `title` der Einfassung überschreibt ihn pro Instanz. |
| `span` | `'column' \| 'page' \| 'side'` | `'column'` | Waagerechte Ausdehnung: die Spalte, die volle Inhaltsbreite oder die nur für Gleitobjekte bestimmte Seitenspalte eines Layouts mit anderthalb Spalten (`layout.sideColumnRole: 'floats'`) – der Kasten verlässt dann den Fluss und stapelt sich in dieser Spalte neben dem Text, den er unterbricht. Pro Instanz mit dem Attribut `span` überschreibbar. In mehrspaltigen Layouts wird ein Kasten mit `'page'` zu einem *Spannblock*: Er teilt die Seite in Spaltenbänder und steht in einer eigenen Spalte über die volle Breite (siehe den Abschnitt zum Container unten). Ein Seitenkasten, den die Seitenspalte seiner Seite nicht fassen kann, nimmt die Seitenspalte der nächsten Seite; wo das Kapitel (oder das Dokument) zuerst endet, wird jeder noch wartende Kasten in der Reihenfolge seiner Einfassungen in die Seitenspalte einer Seite nach dem Text gesetzt, und der Build meldet das (`afterText`; bis postext 1.24 entfielen die Kästen nach der ersten solchen Seite). |
| `columns` | `number` | `1` | Wie viele benachbarte Spalten ein gleitender Kasten (`placement` `'auto'`, `'top'` oder `'bottom'`, mit `span: 'column'`) einnimmt, wie es `placement.columns` bei einer Abbildung tut: der Kasten eines Artikels über drei der fünf Spalten einer Zeitung. So viele Spalten, wie die Seite hat, oder mehr machen ihn zu einem Kasten über die ganze Seitenbreite. Ein im Fluss gesetzter Kasten (`'here'`) bleibt in seiner Spalte. Pro Instanz mit dem Attribut `columns` überschreibbar. Seit postext 1.18. |
| `placement` | `'here' \| 'auto' \| 'top' \| 'bottom' \| 'fixed'` | `'here'` | Wohin der Kasten kommt. `'here'` setzt ihn in den Fluss; `'top'` / `'bottom'` lassen ihn wie eine Ressource **gleiten** (`'auto'` nimmt das Band, das zuerst frei ist, Kopf oder Fuß) – er verlässt den Fluss an seiner Stelle und nimmt das erste freie Band an oder nach diesem Punkt (den Fuß der aktuellen Seite oder Kopf / Fuß der nächsten Seite, die der Fluss eröffnet), und der Text danach füllt die Seite um ihn herum; `'fixed'` verankert ihn über `fixed` (siehe unten) an Seitenkoordinaten, außerhalb des Spaltenflusses. Einzelheiten im Abschnitt zum Container. Pro Instanz mit dem Attribut `placement` überschreibbar. |
| `sideAtColumnEnd` | `'before' \| 'after'` | `'before'` | Wo ein Seitenkasten (`span: 'side'`) steht, wenn der Text nach seiner Einfassung nicht in derselben Spalte weitergeht: Die Spalte hat keinen Platz mehr dafür, oder die Umbruchregeln schicken ihn weiter (ein Absatz, den die Regeln für Witwen und Waisen ganz verschieben, eine Überschrift, die bei ihrem Text bleibt). `'before'` hält ihn an seiner Einfassung, auf dieser Seite, neben dem Text davor, und schiebt ihn vom Fuß der Spalte nach oben, wenn er unter der Einfassung nicht passt: der Platz für eine Glosse, die nach der erläuterten Stelle geschrieben ist. `'after'` setzt ihn auf Höhe der ersten Zeile des Texts nach der Einfassung, in die Seitenspalte der Seite, auf der dieser Text weitergeht: der Platz für eine Zeilennummer oder eine Marginalie, die vor ihrer Zeile geschrieben ist. Geht der Text in derselben Spalte weiter, setzen beide den Kasten an seine Einfassung. Ein Kasten, dem in seinem Kapitel nichts folgt, bleibt in beiden Fällen beim Text davor, und hintereinander eingefasste Seitenkästen behalten ihre Reihenfolge. Bis postext 1.4 verhielt sich jeder Seitenkasten wie `'before'`, was der Standard bleibt: Ein Stil für Glossen hält seine Kästen auf der Seite der Stelle, die sie erläutern. |
| `fixed` | `{ anchor?, offset? }` | `{ anchor: { to: 'container', edge: 'bottom-left' } }` | Position eines Kastens mit `'fixed'`: ein `ElementAnchor` (`to`: `'container'` = der Inhaltsbereich der Seite, auf geraden Seiten gespiegelt; `'page'` = das Endformat; `'bleed'` = der Anschnitt; `edge`: eine der neun Kanten des Containers) plus ein optionales `offset` (Maße `x` / `y`). |
| `floatBarrier` | `boolean` | `false` | Den Kasten zu einer Gleitobjekt-Schranke machen: Jede Abbildung oder Tabelle, auf die vor ihm verwiesen wird, wird vor ihm platziert – in den freien Plätzen der Seite, sonst auf Seiten, die vor dem Kasten eröffnet werden –, sodass kein Gleitobjekt an einem abschließenden Kasten eines Kapitels (typischerweise eine Zusammenfassung der „Kernpunkte“) vorbeigerät. Kapitelauftakte, `:::part` und das Ende des Dokuments sind immer Schranken. |
| Ein Kasten mit `span: 'page'` auf einer mehrspaltigen Seite schneidet das Band unter dem Text, dem er folgt; eine Abbildung über die ganze Breite, auf die vor ihm verwiesen wird, nimmt diesen Schnitt zuerst – der Text wird ausgeglichen, die Abbildung steht genau dort, wo er endete, und der Kasten geht darunter weiter (oder auf der nächsten Seite, wenn er nicht mehr passt). Eine Abbildung, die zu hoch ist, um dem ausgeglichenen Text zu folgen, eröffnet stattdessen die nächste Seite, der Kasten danach, und das verlassene Band endet trotzdem ausgeglichen. Ein teilbarer Kasten (`keepTogether: false`) beginnt unter Text und Abbildung mit so vielen Einträgen, wie passen, und der Rest geht auf der nächsten Seite weiter. | | | |
| `width` | `'fill' \| 'auto'` | `'fill'` | `'fill'` nimmt die verfügbare Breite ein; `'auto'` passt sich eng an den Titel an (als Abzeichen) und ignoriert den Inhalt. |
| `backgroundEnabled` / `background` | `boolean` / `ColorValue` | `true` / `#f4f4f4` | Fläche des Kastens. |
| `border` | `{ enabled, color, width }` | `false`, `#cccccc`, `0.5pt` | Umrisslinie des Kastens, innerhalb der Kastenkante gezeichnet wie der Rahmen eines Kastenelements (siehe [Kastenelemente](https://postext.dev/de/docs/configuration-page-layout.md#kastenelemente)). |
| `borderRadius` | `Dimension` | `0` | Eckenradius von Hintergrund / Rahmen (begrenzt auf die halbe Breite und Höhe des Kastens). Der Streifen folgt ihm: Bei einem abgerundeten Kasten wird der Streifen auf den abgerundeten Rahmen beschnitten, so wie CSS ein `border-left` auf `border-radius` beschneidet. Der Reiter `label` behält eckige Ecken. |
| `padding` | `{ top, right, bottom, left }` | je `0.75em` | Innenabstand zwischen Kastenkante und Inhalt. `em`-Werte beziehen sich auf die Schriftgröße des Kastentexts. |
| `stripe` | `{ enabled, side, width, color }` | `false`, `'left'`, `1.5em`, Hauptfarbe | Vollflächiges Band an einer Kante. Ein Streifen `'left'` / `'right'` verschmälert den Inhalt; ein Streifen `'top'` schiebt ihn nach unten. `'left'` und `'right'` sind Seiten des Textflusses (in einem Buch mit Leserichtung von rechts nach links ist `'left'` die rechte Seite des Blatts); `'start'` und `'end'` folgen der eigenen Richtung des Kastens, sodass ein `:::callout{dir=ltr}` in einem arabischen Buch einen Streifen `'start'` links setzt. Bei einem Kasten mit `borderRadius` werden seine äußeren Ecken mit denen des Rahmens gerundet (bis postext 1.4 blieben sie eckig und ragten über die Rundung hinaus). |
| `icon` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, width, color, align, position, cornerSide }` | `'none'`, Schrift der Überschriften, `400`, `1.5em`, Hauptfarbe, `'top'`, `'inline'`, `'right'` | Ein Textzeichen (`kind: 'glyph'`) oder eine Bitmap-/SVG-Ressource (`kind: 'resource'` + `resourceId`) neben dem Inhalt. Mit einem seitlichen Streifen wird das Symbol über dem Streifen zentriert; sonst reserviert es eine eigene Spalte (`size` + `titleStyle.gap`). `align: 'center'` zentriert es senkrecht zum Inhalt. Ein Ressourcenbild wird unter Wahrung seines Seitenverhältnisses in das Quadrat eingepasst – oder in einen Rahmen von `width` × `size`, wenn `width` gesetzt ist (ein breiter Streifen von Symbolen); ein Symbol, das höher als der Inhalt ist, vergrößert den Kasten entsprechend (und zentriert mit `align: 'center'` den Inhalt daran). `position: 'corner'` hängt das Symbol als Abzeichen an eine obere Ecke, zur Hälfte über den Rahmen hinaus, ohne dem Inhalt Raum zu nehmen; ein breites Symbol (`width`) wird nach der Breite, in der es gezeichnet wird, an der Ecke zentriert, und an der linken Ecke beginnt der Titel hinter seiner inneren Hälfte (bis postext 1.4 wurde es nach seiner Höhe platziert, sodass ein breiter Streifen über den Kasten hinaus und über den Titel hing); `cornerSide` wählt die Ecke – `'right'` / `'left'` oder `'outer'` / `'inner'`, die der Seitenparität gespiegelter Ränder folgen (außen = rechts auf einer rechten Seite, links auf einer linken). |
| `marker` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, color, align, gap, rule }` | `'none'`, Schrift der Überschriften, `400`, `1.5em`, Hauptfarbe, `'center'`, `0.5em`, Linie aus (`0.5pt`, Hauptfarbe, Länge `0`) | Ein zweites Symbol, *außerhalb* des Kastens in einer Spalte links davon gezeichnet, mit einer optionalen senkrechten Linie `rule` zwischen ihm und dem Kasten – die „hier tippen“-Hand neben einem Abzeichen zur Selbsteinschätzung. Der Rahmen wird zu `[marker][rule][gap][box]` und so hoch wie das höchste der drei; `align` zentriert sie zueinander oder richtet sie oben aus. `rule.length` ist ein Mindestwert: Die Linie reicht immer mindestens über die Höhe des Kastens. |
| `titleStyle` | `{ fontFamily, fontSize, fontWeight, italic, color, textTransform, gap, letterSpacing, indent, lineHeight }` | Schrift der Überschriften, Größe des Fließtexts, `700`, `false`, Hauptfarbe, `'none'`, `0.5em`, `0`, `0`, `1.2em` | Typografie des Titels. `gap` ist der Abstand zwischen dem Titel und dem ersten Kindblock (und der Abstand der Symbolspalte). `lineHeight` ist der Zeilenabstand der Titelzeilen, wobei `em` die eigene Größe des Titels zählt; die Grundlinie liegt in jeder Zeile bei 0,8 davon, wie im Fließtext, sodass ein Titel mit dem Zeilenabstand des Fließtexts (`lineHeight: 12pt` über einem Raster von 12 pt) den Kasten bei einer ganzen Zahl von Zeilen und seinen Titel auf dem Raster hält, während der Standard von 1,2 em jedem Kasten einen Bruchteil einer Zeile hinzufügt. `textTransform: 'uppercase'` erhält die Länge. `letterSpacing` sperrt den Titel (Canvas `letterSpacing` / PDF `Tc`); `indent` rückt ihn von der Innenkante des Kastens nach rechts. Ein Eckabzeichen auf der Seite des Titels (der linken Ecke) reserviert zuerst seinen eigenen Raum – die innere Hälfte des Abzeichens plus `gap` –, sodass der Titel es auf jeder Seite freihält; `indent` kommt nur darüber hinaus hinzu. |
| `body` | `{ fontFamily, fontSize, lineHeight, color, boldColor, italicColor, fontWeight, boldFontWeight, italic, smallCaps, textAlign, hyphenation, paragraphSpacing, firstLineIndent, tabStops, tabInterval }` | erbt `bodyText`; `italic` / `smallCaps` `false` | Typografie der Absätze und Listeneinträge im Kasten. Jedes Feld erbt, wenn nicht gesetzt, den Wert des Fließtexts; `italicColor` setzt die Farbe kursiven Texts (ein kursives Hervorhebungszitat in der Farbe des Kastens). `fontWeight` / `boldFontWeight` setzen die Schriftstärken des normalen und des fetten Texts; `italic` setzt den Kasten kursiv, wobei Text in `*…*` aufrecht wird; `smallCaps` setzt ihn in Kapitälchen; `tabStops` und `tabInterval` ersetzen im Kasten die des Fließtexts (siehe [Tabulatoren](https://postext.dev/de/docs/configuration-text.md#tabulatoren)). Was der Text des Kastens sonst noch übernimmt, steht unter [Typografie im Kasten](https://postext.dev/de/docs/configuration-styles.md#typografie-im-kasten). |
| `lists` | `{ bulletChar, color, indent, gap, itemSpacing, bulletFontSize, bulletFontWeight }` | erbt `unorderedLists` | Typografie der Listen im Kasten (`color`, `indent`, `gap` und `itemSpacing` gelten auch für nummerierte Listen). `bulletFontSize` / `bulletFontWeight` setzen das Aufzählungszeichen in der Schrift des Kastentexts in dieser Größe und Schriftstärke (ein kräftiges, farbiges Aufzählungszeichen). |
| `label` | `{ fontFamily, fontSize, fontWeight, color, background, position, height, paddingX, offset, inset, icon, rule }` | nicht gesetzt (kein Reiter) | Ein Reiter an der Oberkante des Kastens, der das Attribut `label` der Einfassung druckt – die Nummer eines nummerierten Kastens („BOX 1-1“). Er schmiegt sich an die Ecke `position` (`'top-right'` / `'top-left'`), um `inset` eingerückt, ragt `offset` über die Oberkante des Kastens hinaus (dieser Raum gehört zum Block, zusätzlich zu `marginTop`, sodass der Reiter ihn auch am Kopf einer Spalte behält), ist `height` hoch mit `paddingX` auf jeder Seite des Texts und kann daneben eine Ressource `icon` tragen (`{ resourceId, width, gap }`, auf der von der Ecke abgewandten Seite) sowie eine Linie `rule` (`{ enabled, color, width }`) entlang der Oberkante von der gegenüberliegenden Ecke bis zu ihm. Standardwerte: Schrift der Überschriften, Größe des Fließtexts, `700`, Weiß auf der Hauptfarbe, `1.4em` hoch, `0.6em` Innenabstand. Der Reiter ist eine eigene Form, die auf dem Rahmen steht, und behält daher eckige Ecken, gleich welchen `borderRadius` der Kasten hat. |
| `columnGap` | `Dimension` | `1.5em` | Abstand zwischen den Spalten einer Gruppe `:::columns` im Kasten (siehe den Abschnitt zum Container unten). |
| `marginTop` / `marginBottom` | `Dimension` | `0.75em` / `0.75em` | Abstand über dem Kasten (fällt mit dem Außenabstand des vorigen Blocks zusammen) und Mindestabstand darunter (der genaue Abstand mit `snapToGrid: false`). Ein gleitender Kasten (`placement: 'top'`, `'bottom'` oder `'auto'`) behält den Gleitobjektabstand, eine Zeile Fließtext, zwischen seinem Band und dem Text; ein größeres `marginBottom` setzt den Abstand unter einem Kasten in einem Kopfband, ein größeres `marginTop` den Abstand über einem Kasten in einem Fußband, mit dem Band auf das Raster aufgerundet. Bis postext 1.4 ignorierte ein gleitender Kasten seine Außenabstände. |
| `snapToGrid` | `boolean` | `true` | Mit `true` rastet der Fluss nach dem Kasten wieder auf das Grundlinienraster ein, der Abstand darunter ist also `marginBottom`, auf ganze Rasterzeilen aufgerundet. Mit `false` behält der Kasten sein genaues `marginBottom`, das mit dem oberen Außenabstand des nächsten Blocks zusammenfällt – zwei aufeinanderfolgende Kästen eines solchen Stils stehen genau `max(marginBottom, marginTop)` voneinander entfernt –, und der Text danach kann bis zum nächsten Einrastpunkt (einer Überschrift, dem Ende einer Liste) außerhalb des Rasters stehen, wie nach einer Überschrift mit `headings.snapToGrid: false`. Gedacht für Dokumente aus gestapelten Kästen (Arbeitsblätter, Formulare). Es gilt für Kästen im Fluss; Kästen über die ganze Seitenbreite in einem mehrspaltigen Layout sowie gleitende, fixierte und Seitenkästen behalten das Raster, da Spaltenbänder und Gleitzonen darauf aufgebaut werden. Die Hebel des Spaltenausgleichs bleiben unverändert: Ein Kasten, der eine Spalte abschließt, wird weiterhin auf den letzten Rasterplatz der Spalte hinabgeschoben. |
| `keepTogether` | `boolean` | `true` | Mit `true` wird der Kasten zusammengehalten: Ein Kasten, der nicht in den verbleibenden Raum passt, wandert ganz in die nächste Spalte oder auf die nächste Seite. Nur ein Kasten, der höher als eine leere, volle Spalte ist – eine ganze Seite bei einem Kasten mit `span: 'page'` –, lässt sich nicht zusammenhalten: Er wird stattdessen nach den Regeln für `false` unten geteilt, statt überzulaufen, beginnend an seiner Stelle, und eine Fortsetzung, die in eine Spalte passt, wandert dann ganz weiter; ein so hoher gleitender Kasten (`placement: 'top' \| 'bottom' \| 'auto'`) gleitet nicht, sondern bleibt an seiner Stelle im Fluss. Mit `false` darf jeder Kasten zwischen seinen Kindblöcken oder zwischen den Zeilen eines Absatzes oder Listeneintrags umbrechen: Der tiefste passende Schnitt schließt die aktuelle Spalte ab (oder bei einem Kasten mit `span: 'page'` die Seite, bündig mit dem Fuß der Spalten), und der Rest geht am Kopf der nächsten in einem eigenen Kasten weiter – gleicher Rahmen und Streifen, kein Symbol und kein Titel, sofern `repeatTitle` ihn nicht wiederholt –, und wird erneut geteilt, wenn er immer noch zu hoch ist. Der Text jedes Fragments behält die Spalte, die ein Inline-Symbol am Kopf einnimmt, leer, sodass der Kasten auf jeder Seite eine Satzbreite hat. Ein Schnitt in einem Listeneintrag lässt dessen Aufzählungszeichen beim Kopf. Der Rahmen jedes Fragments teilt `contentIndex` / `containerId` der Einfassung und vermerkt `callout.part` / `callout.continued`. Verwenden Sie es für einen langen abschließenden Kasten mit „Kernpunkten“ zusammen mit `headings.balancing.beforeSpan` oder für einen Anmerkungsstil, dessen Kästen nie eine Abbildung von der Seite drängen dürfen. Ein verschachtelter Kasten (ein `:::callout` in einem anderen) ist ein Kindblock seines Elternkastens: Ein Schnitt darf davor oder danach fallen und in ihm nur, wenn sein eigener Stil das Teilen erlaubt (`keepTogether: false` oder höher als eine volle Spalte), nach seinem eigenen `splitMinLines`. |
| `splitMinLines` | `number` | `2` | Mindestzahl an Textzeilen, die ein Fragment eines geteilten Kastens (`keepTogether: false` oder ein zusammenzuhaltender Kasten, der höher als eine volle Spalte ist) auf beiden Seiten des Schnitts behält. Es schützt nur Text: Eine Seite mit mindestens einer Abbildung, Tabelle, abgesetzten Formel oder einem verschachtelten Kasten ist unabhängig von ihrer Zeilenzahl zulässig, sodass ein Kasten mit Bildern ein einzelnes auf einer Seite lassen darf. Ein Schnitt in einem Absatz oder Listeneintrag zählt weiterhin jede Zeile auf beiden Seiten (eine Abbildung oder Formel dort als eine Zeile) und lässt außerdem mindestens `layout.boxChildSplitMinLines` Zeilen dieses Absatzes oder Eintrags auf jeder Seite (standardmäßig zwei; dieses Minimum, wenn es kleiner ist, sodass 1 eine erlaubt). Mit den Standardwerten wird ein Eintrag von zwei oder drei Zeilen nie geteilt und einer von vier Zeilen nur zwei zu zwei. Mit dem Standard bricht kein Kasten so um, dass eine einzelne Textzeile am Fuß einer Spalte oder am Kopf der nächsten steht; erfüllt kein Schnitt das Minimum, wandert der Kasten ganz. (Vor postext 1.5 prüfte ein Schnitt in einem Absatz nur die Zeilen der ganzen Seite, sodass ein Eintrag von zwei Zeilen eins zu eins geteilt werden konnte, wenn andere Zeilen des Kastens das Minimum auffüllten.) |
| `repeatTitle` | `boolean` | `false` | Den Titel am Kopf jeder Fortsetzung eines geteilten Kastens wiederholen, gefolgt von `continuedSuffix` („Key points (cont.)“). Die Wiederholung übernimmt den Titelstil. Ein Kasten ohne Titel wiederholt nichts. Siehe [Hinweise an einem geteilten Kasten](https://postext.dev/de/docs/configuration-styles.md#hinweise-an-einem-geteilten-kasten). |
| `continuedSuffix` | `string` | `'(cont.)'` | Text nach dem wiederholten Titel, in der Sprache des Dokuments (`locale`, sonst die Sprache der Silbentrennung), wie bei einer geteilten Tabelle, und mit dem Titel verbunden wie bei einer Tabelle. |
| `continuesMarkerEnabled` | `boolean` | `false` | `continuesMarker` unter die letzte Zeile jedes weitergehenden Teils eines geteilten Kastens setzen, innerhalb des Kastens. |
| `continuesMarker` | `string` | `'Continued'` / `'Continúa'` | Text dieses Hinweises (das „(MORE)“ eines Drehbuchs), in Schrift und Größe des Kastentexts, je nach Sprache des Dokuments. |
| `continuesMarkerAlign` | `'left' \| 'center' \| 'right'` | `'right'` | Wo der Hinweis in der Innenbreite des Kastens steht. |
| `continuesMarkerItalic` | `boolean` | `true` | Den Hinweis kursiv setzen. |
| `numbering` | `{ label, counter, numberingTemplate, resetOn, counterFormat, placement, bold, italic, suffix }` | nicht gesetzt | Die Kästen dieses Stils als nummerierte Aussagen zählen: Sätze, Lemmata, Definitionen. Siehe [Nummerierte Aussagen und Beweise](https://postext.dev/de/docs/configuration-styles.md#nummerierte-aussagen-und-beweise). |
| `endMark` | `string` | `''` | Ein Zeichen, rechtsbündig ans Ende der letzten Zeile des Kastens gesetzt, wie ein Beweis mit `'∎'` oder `'□'` endet: auf der letzten Zeile, wenn es nach einem Leerzeichen passt, sonst auf einer eigenen Zeile. Ein Kasten, der mit einer abgesetzten Formel ohne Nummer endet, nimmt es als Kennzeichen der Formel. Mit eingeschalteter Mathematik werden die Quadrate (∎ □ ■ ▪ ◻ ▫) aus den eigenen Glyphen von TeX gezeichnet, sodass eine Schrift ohne sie (die latin-Dateien von Fontsource) sie trotzdem druckt; mit ausgeschalteter Mathematik werden sie in der Schrift des Kastentexts gesetzt. |
### Der Container `:::callout`
Eine Zeile `:::callout{type=""}` öffnet den Kasten, eine bloße Zeile `:::` schließt ihn. Die Einfassung nimmt fünf Attribute an – `type` (die ID des Stils), `title` (überschreibt den Titel des Stils), `span`, `placement` und `columns` (überschreiben die Werte des Stils) –, und der Inhalt dazwischen wird im Kasten gesetzt: ein optionaler Titel, dann die Absätze, Listen, Zitatblöcke, Formeln oder Ressourceneinbettungen, jeweils mit der Typografie `body` / `lists` des Stils (Überschriften behalten ihre üblichen Stile). Außenabstände zwischen Kindblöcken fallen wie im Fließtext zusammen; das Innere verlässt das Grundlinienraster, und der Fluss rastet nach dem Kasten mit mindestens `marginBottom` darunter wieder darauf ein (das Raster hat Vorrang; der Außenabstand ist ein Mindestwert – dieselbe Konvention, der Ressourcen folgen). Ein Stil mit `snapToGrid: false` behält stattdessen das genaue `marginBottom`, und der Text nach dem Kasten bleibt bis zur nächsten Überschrift oder zum nächsten Listenende außerhalb des Rasters. Eine Überschrift unmittelbar vor einem Kasten bleibt bei ihm.
Grenzen in dieser Version:
- Ein Kasten wird zusammengehalten, sofern sein Stil nicht `keepTogether: false` setzt. Passt er nicht in den verbleibenden Spaltenraum, wandert er ganz in die nächste Spalte oder auf die nächste Seite – auch aus einer leeren Spalte, die Gleitobjekt-Bänder oder eine Bandgrenze verkürzt haben, solange eine volle Spalte ihn fassen würde. Ein Kasten, der höher als eine volle Spalte ist, wird stattdessen geteilt, wie ein teilbarer; nur einer, den kein Schnitt teilen kann (eine Abbildung oder Tabelle, die höher als die Spalte ist, oder ein `splitMinLines`, das kein Schnitt erfüllt), wird trotzdem platziert und läuft über; das Layout vermerkt dann eine Warnung `calloutOverflow` (`VDTDocument.warnings`), die die Sandbox auflistet. Eine Gruppe `:::columns` wird wie der Kasten um sie herum geschnitten, zwischen ihren Unterspalten (seit postext 1.25); sie bleibt nur mit `layout.flowColumns: false` oder in einem verschachtelten Kasten ganz und kann dann ebenso überlaufen. Ein teilbarer Kasten lässt den passenden Teil zurück – ganze Kindblöcke oder die Zeilen eines Absatzes bis hinab zu `splitMinLines` auf jeder Seite (eine Abbildung, Tabelle oder abgesetzte Formel allein genügt für eine Seite) – und geht in einem Kasten ohne Symbol in der nächsten Spalte oder auf der nächsten Seite weiter, ohne Titel, sofern der Stil ihn nicht wiederholt, und optional mit einem Hinweis unter dem verlassenen Teil (siehe [Hinweise an einem geteilten Kasten](https://postext.dev/de/docs/configuration-styles.md#hinweise-an-einem-geteilten-kasten)).
- Gleitobjekte weichen einem unteilbaren Kasten. Ist der Block direkt nach dem Verweis auf eine Abbildung ein Kasten mit `keepTogether`, wird ein Platz, der dem Kasten keine Spalte des aktuellen Bands zum Landen ließe (die verweisende Spalte oder eine leere danach, die ihn vor dem Gleitobjekt aufgenommen hat), nicht genommen: Die Abbildung geht zu ihrem nächsten Platz weiter, meist auf der nächsten Seite, und der Kasten bleibt im Fluss – so, wie ein Setzer ihn setzen würde, statt den Kasten von der Seite zu drängen und die Spalte mit der Abbildung allein zu lassen.
- `span: 'page'` in einem mehrspaltigen Layout macht den Kasten zu einem **Spannblock**: Er wird auf die volle Inhaltsbreite gesetzt und teilt die Seite in Spaltenbänder – die Textspalten darüber werden an der Schnittlinie geschlossen, der Kasten nimmt eine eigene Spalte über die volle Breite ein, und darunter öffnet sich ein neues Band von Textspalten, sodass der Fluss in jeder Spalte unter dem Kasten weitergeht. Wo die Spalten *ausgeglichen* sind – am Kopf einer Seite, direkt unter einer Auftaktüberschrift mit `span: 'page'`, direkt unter einem anderen Spannblock oder direkt unter einem Gleitobjekt-Band am Kopf –, schneidet der Kasten einfach dort. Kommt er mitten auf der Seite an, bei ungleichen Spalten, wird er so gesetzt, wie es ein Setzer täte: Der Text darüber wird über alle Spalten ausgeglichen geschnitten (die Engine wiederholt die Platzierung mit Spalten des Bands, die auf dieselbe Zahl von Rasterzeilen gekürzt sind, sodass der Text natürlich von Spalte zu Spalte überläuft und jede Regel zu Waisen, Witwen und Zusammenhalt mit dem Folgenden weiterhin gilt), der Kasten überspannt die Seite, und die Spalten gehen darunter weiter. Der Schnitt kostet einige zusätzliche Platzierungsdurchgänge; ließe die Schnittlinie keinen Raum für den Kasten plus das Witwenminimum an Fließtextzeilen darunter, oder passt nach einigen Versuchen keine Anordnung, wandert der Kasten an den Kopf der nächsten Seite. Der Text darüber hält sich an den Schnitt: Ein Absatz, der in den wenigen Zeilen, die eine Spalte unter einer Abbildung darüber freihält, nicht beginnen kann, geht in die nächste Spalte (die Abbildung steht dann allein in ihrer Spalte), und würde ein Block dennoch über den Schnitt hinauslaufen, wird der Schnitt eine Zeile tiefer gesetzt, statt dort, wo dieser Block endet. Ein geteilter Kasten, der das Band eröffnet, wird ebenfalls dort geschnitten, sodass sein Rest nie über den Schnitt hinausläuft. Mit `headings.balancing.beforeSpan` (dem Standard) wird das verlassene Band hinter ihm ausgeglichen geschnitten – wie das abschließende Band eines Kapitels –, und wenn der Stil das Teilen erlaubt (`keepTogether: false`), schließt der Teil des Kastens, der unter die ausgeglichenen Spalten passt, die Seite ab, und der Rest eröffnet die nächste; mit `beforeSpan: false` wird die verlassene Seite einfach wie üblich ausgeglichen, ohne einen Seitenumbruch zu erzwingen. Eine Überschrift direkt vor einem Spannblock wandert nicht mit ihm. In einspaltigen Layouts ist `span: 'page'` einfach ein Kasten im Fluss.
- `placement: 'fixed'` nimmt den Kasten aus dem Fluss: Er wird gesetzt (`width: 'auto'` passt sich eng an den Titel an; `'fill'` nimmt die Breite der Textspalte unter dem Ankerpunkt) und auf der Seite, auf der er im Fluss vorkommt, an der Position fixiert, die `fixed.anchor` / `fixed.offset` beschreiben – standardmäßig die linke untere Ecke des Inhaltsbereichs. Die Textspalten, die er überdeckt, geben diese Zone frei (von unten abgeschnitten oder von oben, wenn die Spalte noch leer ist), genau wie bei einem Gleitobjekt-Band; enthält die Zone bereits Text, ein Gleitobjekt oder einen Spannblock, wandert der Kasten auf die nächste Seite. Ein fixierter Kasten, der das Kapitel abschließt (der nächste Block ist ein Kapitelauftakt, ein `:::part`, ein Schrankenkasten oder das Ende des Dokuments), gleicht zuerst die Spalten darüber aus (`headings.balancing.trailing`), sodass eine kurze Schlussseite ausgeglichen über dem Abzeichen darunter endet. Rahmen und Kindblöcke stehen in `page.floats` und werden in jeder Ausgabe außerhalb des Spaltenbeschnitts gezeichnet.
- `placement: 'top' | 'bottom'` lässt den Kasten wie eine Ressource **gleiten**: Er verlässt den Fluss an seiner Stelle und nimmt das erste freie Band nach diesem Punkt – den Fuß der aktuellen Seite (`'bottom'`) oder Kopf / Fuß der nächsten Seite, die der Fluss eröffnet – in Spaltenbreite (`span: 'column'`) oder in voller Inhaltsbreite (`span: 'page'`); der Text danach füllt die verlassene Seite. Rahmen und Kindblöcke kommen in `page.floats`, wie bei einem fixierten Kasten. Ein gleitender Kasten, der eine neue Seite anführt, wird vor den Abbildungen gesetzt, die auf diese Seite warten, und eine Abbildung, auf die auf einer früheren Seite verwiesen wurde und die dann darunter passt, nimmt den Rest dieser Seite, auch wenn weniger als drei Textzeilen übrig blieben (eine Galerieseite: Kasten plus Abbildung, kein Text dazwischen). Ein Kasten mit `span: 'side'` gleitet nie: Er stapelt sich neben dem Text, gleich welche Platzierung er hat. Mit `columns` über 1 (im Stil oder als Attribut der Einfassung, seit postext 1.18) nimmt ein Kasten mit `span: 'column'` so viele benachbarte Spalten ein: den Kopf einer Folge leerer Spalten, die auf gleicher Höhe beginnen, oder den Fuß der aktuellen Spalte und der leeren danach, wie in `:::callout{placement="top" columns="2"}`.
- `width: 'auto'` passt sich nur eng an den Titel an; Kindblöcke werden ignoriert.
- Ein in einem anderen Kasten verschachteltes `:::callout` ist ein eigener Kasten: Es wird mit seinem eigenen Stil (Hintergrund, Rahmen, Radius, Innenabstand, Streifen, Titel, Symbol, Marker, Reiter, Typografie) auf die volle Innenbreite seines Elternkastens gesetzt und stapelt sich als ein Kindblock darin, wobei sein `marginTop` / `marginBottom` mit den Nachbarn zusammenfällt. Sein `span` und `placement` (aus Einfassung oder Stil) werden ignoriert – ein verschachtelter Kasten fließt immer in seinem Elternkasten –, ebenso `floatBarrier` und `snapToGrid`. Kästen lassen sich beliebig tief verschachteln und können in einer Gruppe `:::columns` stehen (jeder ganz, in einer Spalte). Wird der Elternkasten geteilt, fällt der Schnitt vor oder nach einem verschachtelten Kasten oder in ihn, wenn der verschachtelte Stil das Teilen erlaubt; jedes Fragment zeichnet die Rahmen neu, die es durchschneidet, und ein verschachtelter Kasten, der aus dem vorigen Fragment fortgesetzt wird, verliert Titel und Symbol, wie eine Fortsetzung auf oberster Ebene.
- Eine Gruppe `:::columns{count=N}` … `:::` unter den Kindblöcken setzt diese Kindblöcke im Kasten in `N` gleich breiten Spalten im Abstand `columnGap`: Die Folge wird an den Block- oder Zeilengrenzen geschnitten, die die Spalten am besten ausgleichen (ein mittendrin geschnittener Absatz oder Listeneintrag geht am Kopf der nächsten Spalte ohne sein Aufzählungszeichen weiter), jede Spalte beginnt am Kopf der Gruppe, und die Gruppe ist so hoch wie ihre höchste Spalte; die Kindblöcke danach kehren zur vollen Breite zurück. Ein Kasten, der sich teilt (`keepTogether: false` oder höher als eine Spalte), schneidet auch innerhalb einer Gruppe, zwischen ihren Spalten: Eine fortlaufende Gruppe füllt ihre Spalten der Reihe nach und geht im nächsten Fragment weiter, eine parallele (`breaks`) geht Strang für Strang weiter (seit postext 1.25; siehe [Dokumentformat › `:::columns`](https://postext.dev/de/docs/document-format.md#columns)). Ein `gap` an der Einfassung ersetzt `columnGap` für diese Gruppe, und `rule` zieht eine Linie durch jeden Spaltenabstand. Verwenden Sie es für eine zweispaltige Zusammenfassung von Kernpunkten oder für nebeneinandergesetzte Tabellen eines breiten Kastens.
- Das sechste Attribut der Einfassung, `label`, erscheint auf dem Reiter des Stils (siehe `label` oben) – `:::callout{type="box" label="BOX 1-1" title="The octet rule"}`; ohne einen Stil `label` wird das Attribut ignoriert.
Im VDT ist der Kasten ein Rahmenblock mit `type: 'callout'`, dessen Schmuck (Hintergrund, Streifen, Symbol, Titel) in `designOverlay` liegt, gefolgt von seinen Kindblöcken in derselben Spalte; der Rahmen und jeder Kindblock tragen die `containerId` der Einfassung. Ein verschachtelter Kasten ist ein eigener Rahmen mit `type: 'callout'` unter den Kindblöcken, gefolgt von seinen Blöcken; sie behalten die `containerId` der Einfassung auf oberster Ebene (Platzierung und Ausgleich sehen weiterhin eine Einheit) und fügen `calloutPath` hinzu, die Container-IDs der umgebenden verschachtelten Einfassungen, die äußerste zuerst (die eigene ID eines verschachtelten Rahmens ist der letzte Eintrag). Das getaggte PDF gibt jedem verschachtelten Kasten ein `Div` innerhalb dessen seines Elternkastens. Symbolbilder werden wie Ressourcenbilder aufgelöst: über das Bildregister des Canvas, die HTML-Option `resourceImageUrl` und den PDF-Provider `resourceBytes`.
```ts
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
```
### Nummerierte Aussagen und Beweise
Ein Stil mit `numbering` zählt seine Kästen, so wie `amsthm` in LaTeX Theorem-Umgebungen zählt (seit postext 1.19). Jeder Kasten druckt seine Bezeichnung und Nummer – „**Theorem 2.**“ zu Beginn seines ersten Absatzes –, und der `title` der Einfassung folgt der Nummer in Klammern: `:::callout{type="theorem" title="Bradley–Terry"}` beginnt mit „**Theorem 2** (Bradley–Terry)**.**“. Ein Kasten, der mit einem Bezeichner eröffnet wird (`{#thm:main}`), ist ein Ziel von Querverweisen, die „Theorem 2“ drucken (`:ref{id="thm:main"}`), und `\ref{thm:main}` oder `style=number` druckt 2.
| Feld | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `label` | `string` | — | Das Wort vor der Nummer: `'Theorem'`, `'Lemma'`, `'Definición'`. |
| `counter` | `string \| false` | die `id` des Stils | Der Zähler, den die Kästen erhöhen. Stile, die denselben Zähler nennen, teilen ihn, wie es `\newtheorem{lemma}[theorem]` tut: Theorem 1, Lemma 2, Theorem 3. `'equation'` zählt mit den bezeichneten Gleichungen. `false` druckt die Bezeichnung ohne Nummer (das „*Proof.*“ eines Beweises). |
| `numberingTemplate` / `resetOn` / `counterFormat` | `string` / `ResourceCounterReset` / `ResourceCounterFormat` | `'{n}'` / `'never'` / `'decimal'` | Wie bei einem Ressourcentyp: `'{h1}.{n}'` mit `resetOn: 'h1'` nummeriert Theorem 2.1, 2.2 … nach Kapitel; `'{h1}.{h2}.{n}'` mit `'h2'` nach Abschnitt. Ein von mehreren Stilen geteilter Zähler zählt weiter, was auch immer ihre Vorlagen drucken. Ein Platzhalter nimmt nach einem Doppelpunkt einen Stil an, wie bei einem Ressourcentyp: `'{h1:A}.{n}'` druckt *Theorem A.1* in einem mit Buchstaben gezählten Anhang. |
| `placement` | `'runIn' \| 'title'` | `'runIn'` | `'runIn'` eröffnet den ersten Absatz des Kastens mit der Bezeichnung (ein Kasten, der mit einer Liste, einer Formel oder einem anderen Kasten beginnt, erhält dafür einen Absatz); `'title'` macht die Bezeichnung zum Titel des Kastens, in dessen `titleStyle`: „Theorem 2 (Bradley–Terry)“. |
| `bold` / `italic` | `boolean` | `true` / `false` | Der Schnitt der eingebundenen Bezeichnung und ihres Suffixes, unabhängig vom Text des Kastens: Ein kursiver Text (`body.italic`) lässt eine aufrechte Bezeichnung aufrecht. Der Titel in Klammern wird aufrecht in der normalen Schriftstärke gesetzt. |
| `suffix` | `string` | `'.'` | Nach der eingebundenen Bezeichnung und ihrem Titel gesetzt. |
Ein Beweis ist ein Stil mit einer nicht nummerierten Bezeichnung und einem Schlusszeichen:
```ts
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 } },
]
```
In einem Buch, das Kapitel für Kapitel umbrochen wird, zählen die Zähler vom vorigen Kapitel aus weiter (`LayoutContinuation.statementCounters`, das `continuationAfter` füllt), und die Gliederung des Buchs gibt dem Anker jedes nummerierten Kastens seine Bezeichnung (`OutlineEntry.numberLabel`), sodass ein Verweis aus einem anderen Kapitel sie druckt.
### Typografie im Kasten
Ein Kasten setzt seinen Inhalt mit seiner eigenen Typografie `body` und `lists`; alles andere behält die Stile des Dokuments:
- **Absätze** übernehmen den `body` des Kastens: Schrift, Größe, Zeilenabstand, Farbe, Auszeichnungsfarben, Schriftstärken, `italic`, `smallCaps`, Ausrichtung, Silbentrennung, Einzug und Absatzabstand. Ein nicht gesetztes Feld erbt `bodyText`. Eine geerbte Auszeichnungsfarbe behält ihre Bindung an die Palette, sodass sich fetter und kursiver Text sowie Bezeichnungen von `:ref` in einem Kasten mit `colorPalette` ändern wie außerhalb. (Bis postext 1.4 blieb Fettes in einem Kasten `#295AA3`, gleich welche Hauptfarbe galt.)
- **Aufzählungen** übernehmen die `lists` des Kastens (Aufzählungszeichen, Farbe, Glyphengröße und -stärke, Einzug, Abstand, Eintragsabstand) über `unorderedLists`, und ihr Text ist der Text des Kastens. Ein `lists.bulletChar` oder `lists.color`, das von dem des Dokuments (`unorderedLists`) abweicht, ersetzt Aufzählungszeichen oder Farbe jeder Ebene; eines, das ihn wiederholt oder nicht gesetzt ist, lässt jeder Ebene ihren eigenen Wert (`unorderedLists.levels`), sodass verschachtelte Striche im Kasten erhalten bleiben.
- **Nummerierte Listen** übernehmen `lists.indent`, `gap` und `itemSpacing` sowie `lists.color`, sobald der Stil es setzt – auch wenn es die Farbe der Aufzählungszeichen des Dokuments ist; ein Stil, der es nicht setzt, behält die Nummern in `orderedLists.color`. (Bis postext 1.4 erreichte die Farbe die Nummern nur, wenn sie von `unorderedLists.color` abwich, sodass es nichts bewirkte, sie auf genau diese Farbe zu setzen.) Die Nummer selbst – Schrift, Größe und Trennzeichen – stammt aus dem globalen `orderedLists`, da `lists` nur Felder für Aufzählungszeichen hat: Gestalten Sie die Nummern eines Kastens dort.
- **`:::paragraphs` im Kasten** verwenden ihr Absatzformat, auch in verschachtelten Kästen. Die Felder, die das Format nicht setzt, erben den `bodyText` des Dokuments, nicht den `body` des Kastens (auch nicht dessen Kursive oder Kapitälchen).
- **Gruppen `:::columns`** haben keinen eigenen Stil: Jede Spalte teilt die Text- und Listentypografie des Kastens, und `columnGap` setzt den Abstand zwischen ihnen.
- **Zitatblöcke** übernehmen Schrift, Größe und Schriftstärken des Kastentexts (kursiv und grau, wie im Fließtext) sowie seine Kapitälchen. **Überschriften** behalten die Überschriftenstile, **abgesetzte Formeln** die Mathematik-Einstellungen.
- **Abbildungen und Tabellen** behalten die Legenden- und Tabellenstile des Dokuments, in der Innenbreite des Kastens; ihre normalen und fetten Schriftstärken folgen denen des `body` des Kastens.
- **Chips** behalten ihren Chip-Stil; eine Größe in `em` wird an der Schriftgröße des Kastentexts gemessen.
- **`:::space`** wird in Zeilen des Kastentexts gemessen (siehe [`:::space`](https://postext.dev/de/docs/document-format.md#space) dazu, wo es entfällt).
- **Ein verschachtelter Kasten** übernimmt seinen eigenen Stil vollständig; sein `span`, `placement`, `floatBarrier` und `snapToGrid` werden ignoriert.
### Hinweise an einem geteilten Kasten
Teilt sich ein Kasten über Spalten oder Seiten (`keepTogether: false` oder ein Kasten, der höher als eine Spalte ist), beginnt jeder Teil nach dem ersten ohne Titel und Symbol, und standardmäßig sagt nichts dem Leser, dass der Kasten weitergeht. Zwei Optionen fügen die Hinweise hinzu, die ein Buch oder ein Drehbuch verwendet:
- **`repeatTitle: true`** wiederholt den Titel am Kopf jeder Fortsetzung, gefolgt von `continuedSuffix` – standardmäßig „Key points (cont.)“. Die Wiederholung übernimmt den Titelstil, sodass sie mit `textTransform: 'uppercase'` das „HAMLET (CONT'D)“ eines Drehbuchs ergibt. Symbol und Reiter bleiben am ersten Teil.
- **`continuesMarkerEnabled: true`** setzt `continuesMarker` – „Continued“ oder „Continúa“ in einem spanischen Dokument – unter die letzte Zeile jedes weitergehenden Teils, innerhalb des Kastens, in Schrift und Größe des Kastentexts: kursiv, sofern `continuesMarkerItalic` nicht `false` ist, rechtsbündig, sofern `continuesMarkerAlign` nicht `'left'` oder `'center'` angibt. Der Hinweis nimmt Raum in dem Teil ein, den er abschließt, und der Schnitt wird so gewählt, dass er passt.
```ts
calloutStyles: [{
id: 'speech',
keepTogether: false,
titleStyle: { textTransform: 'uppercase' },
repeatTitle: true,
continuedSuffix: "(CONT'D)",
continuesMarkerEnabled: true,
continuesMarker: '(MORE)',
continuesMarkerAlign: 'center',
continuesMarkerItalic: false,
}],
```
```md
:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::
```
Der Teil, der die Seite abschließt, endet mit „(MORE)“, und die nächste Seite beginnt mit „HAMLET (CONT'D)“. Beides gehört zum Paginierungszubehör: In einem barrierefreien PDF sind es Artefakte, und im HTML sind sie vor assistiven Technologien verborgen, sodass der Titel nur einmal vorgelesen wird. Im VDT sind es Textblöcke in `designOverlay` mit dem Flag `artifact: true`.
## Teile
Die Eigenschaft `parts` konfiguriert die Teiltitelseiten, die ein Dokument mit einem Container `:::part{number="…" title="…"}` eröffnet – die Seite „Teil I – Grundlagen“, die eine Folge von Kapiteln zusammenfasst. Ein Teil belegt immer eine eigene Seite: Der Container bricht auf eine neue Seite der konfigurierten Parität um, wandelt sie in eine einspaltige Seite um, deren Textbereich aus `parts.margins` stammt, legt die Auftaktgestaltung über die ganze Seite und bricht nach der schließenden Einfassung erneut um, sodass das nächste Kapitel (mit seinem eigenen `breakBefore.parity`) sauber beginnt – mit den Standardeinstellungen für H1 ergibt das die klassische Teiltitelseite rechts, eine leere linke Seite und das Kapitel auf der nächsten rechten Seite.
```ts
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' } },
},
};
```
```md
:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
3. Reading the weather
:::
# The lantern and its parts
```
| Eigenschaft | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `page` | `boolean` | `true` | Ob ein `:::part` eine Teiltitelseite eröffnet. Mit `false` wird keine Seite eröffnet und der Inhalt der Einfassung nicht gesetzt: Nummer, Titel und Palette des Teils gelten ab dem nächsten Inhalt, ohne eigenen Umbruch. Typischer Einsatz: `htmlViewer.overrides.parts.page: false`, eine Bildschirmausgabe ohne Teiltitel. |
| `breakBefore.parity` | `HeadingBreakParity` | `'odd'` | Parität der Seite, auf der der Teil beginnt. Dieselben Werte und Regeln für die Zugehörigkeit leerer Seiten wie beim [breakBefore](https://postext.dev/de/docs/configuration-text.md#umbruch-davor) der Überschriften: Eine Vakatseite, die eingefügt wird, um die Parität zu erreichen, gehört zum Teil (ihr `{partTitle}` löst bereits zum neuen Teil auf); die vorgeschriebene Trennseite von `'always-*'` gehört zum vorigen Inhalt. |
| `breakAfter.enabled` | `boolean` | `true` | Den Inhalt nach der schließenden Einfassung auf eine neue Seite verschieben. Mit `false` geht er in der einzigen Spalte der Teiltitelseite weiter. |
| `breakAfter.parity` | `HeadingBreakParity` | `'any'` | Parität dieser neuen Seite. Belassen Sie sie bei `'any'`, und lassen Sie das eigene `breakBefore.parity` des nächsten Kapitels entscheiden, ob eine leere linke Seite folgt. Der Umbruch wird angewandt, wenn der nächste Block platziert wird, sodass ein Teil, der das Dokument abschließt, keine leere Seite am Ende hinterlässt. |
| `margins` | `PageMargins` | Seitenränder | Textbereich der Teiltitelseite – die einzige Spalte, in der die Blöcke der Einfassung fließen. Jede Seite erbt, wenn nicht gesetzt, den Seitenrand; `mirror` vertauscht Bund- und Außensteg auf geraden Seiten genau wie die Seitenränder. |
| `design` | `DesignSlot` | leer | Auftaktgestaltung. Ihr Container ist das **Endformat** der Seite, sodass Container-Anker und `'page'`-Anker zusammenfallen und `'bleed'` bei eingeschalteten Schnittmarken bis in den Anschnitt reicht. Rein dekorativ: Sie reserviert nie Textraum – erhöhen Sie `margins.top`, um den Text von ihr freizuhalten. Ist sie leer, wird oben links im Textbereich ein Standardtext `{number} {titleText}` in der Typografie von H1 erzeugt, mit dem `numberSeparator` von H1 zwischen Nummer und Titel. |
| `versoDesign` | `DesignSlot` | leer | Gestaltung der leeren linken Seite, die auf eine Teiltitelseite folgt (die Rückseite des Teiltitelblatts): derselbe Container und dieselben Platzhalter wie bei `design`. Für eine schlichte linke Seite leer lassen. Sie wird nur gezeichnet, wenn die Seite nach der Teiltitelseite leer bleibt, was einen Umbruch mit Parität erfordert: siehe [Die Gestaltung der linken Seite](https://postext.dev/de/docs/configuration-styles.md#die-gestaltung-der-linken-seite) unten. |
| `bodyStyle.fontFamily`, `fontSize`, `lineHeight`, `color`, `textAlign` | wie in `bodyText` | erben `bodyText` | Typografie der Absätze, Zitatblöcke und Listeneinträge in der Einfassung. Schriftstärken, Auszeichnungsfarben und Silbentrennung stammen aus dem Fließtext. |
| `bodyStyle.bulletColor` | `ColorValue` | `unorderedLists.color` | Farbe der Aufzählungszeichen in Aufzählungen innerhalb des Teils. |
| `bodyStyle.numberColor` | `ColorValue` | `orderedLists.color` | Farbe der Nummern in nummerierten Listen innerhalb des Teils. Nummern werden immer in der fetten Schriftstärke des Fließtexts gesetzt, sodass sich eine Kapitelliste wie ein Inhaltsverzeichnis liest. |
| `bodyStyle.unorderedLists` | `UnorderedListsConfig` | — | Teilweise Überschreibungen, die innerhalb des Teils nach `bulletColor` über die `unorderedLists` des Dokuments gelegt werden. Listenweite Werte gehen auf die Ebenen über, die sie geerbt haben; Einträge in `levels` gelten nur für ihre Ebene. |
| `bodyStyle.orderedLists` | `OrderedListsConfig` | — | Teilweise Überschreibungen, die innerhalb des Teils nach `numberColor` und der fetten Schriftstärke über die `orderedLists` des Dokuments gelegt werden – z. B. ein `separator` `'•'` mit eigenem `separatorFontFamily` und `separatorColor` für die Kapitelliste eines Teilauftakts. |
### Platzhalter der Teilgestaltung
Der Gestaltungsplatz löst die Platzhalter der Überschriften mit den eigenen Werten des Teils auf: `{titleText}` ist der `title` der Einfassung; `{number}` die `number` genau so, wie sie geschrieben ist; `{numberDecimal}`, `{numberRoman}`, `{numberRomanLower}`, `{numberAlpha}`, `{numberAlphaLower}` formatieren sie um – die Nummer wird als Dezimalzahl, römische Zahl oder chinesische Zahlzeichen gelesen, mit oder ohne die Wörter, die sie einrahmen (`"IV"`, `"iv"`, `"4"`, `"４"`, `"四"`, `"卷四"` und `"第四卷"` ergeben alle `{numberDecimal}` = `4`), und lösen bei allem anderen zu `''` auf. `{partTitle}` / `{partNumber}`, `{chapterTitle}` / `{chapterNumber}` (das Kapitel vor dem Teil), `{pageNumber}`, `{totalPages}`, `{bookTotalPages}` und die Metadaten-Platzhalter stehen ebenfalls zur Verfügung. `{attr.}` liest die Attribute der H1 des aktuellen Kapitels.
### Die Gestaltung der linken Seite
`versoDesign` schmückt die Seite direkt nach einer Teiltitelseite, wenn diese Seite keinen Inhalt hat: die Rückseite des Teiltitelblatts. Der Teil selbst lässt diese Seite nie leer. `breakAfter.parity` ist standardmäßig `'any'`, sodass der Inhalt nach der Einfassung auf der unmittelbar folgenden Seite beginnt, sofern nicht etwas eine Parität verlangt:
- **Die Überschrift des nächsten Kapitels.** Das Standard-`breakBefore` von H1 ist `'always-odd'`, und `'odd'` bewirkt nach einer rechten Teiltitelseite dasselbe: Das Kapitel wandert auf die nächste rechte Seite, und die linke bleibt leer. Die Gestaltung der linken Seite wird gezeichnet.
- **`parts.breakAfter: { enabled: true, parity: 'odd' }`.** Der Teil verlangt selbst die nächste rechte Seite, was immer die nächste Überschrift tut. Verwenden Sie es, wenn Kapitel auf beiden Seiten beginnen dürfen (`breakBefore.parity: 'any'` oder `breakBefore.enabled: false`).
Mit keinem von beiden beginnt das Kapitel auf der linken Seite, und es wird keine Gestaltung der linken Seite gezeichnet. Mit `breakAfter.enabled: false` geht der Inhalt auf der Teiltitelseite selbst weiter. Die linke Seite übernimmt die Palette des Teils, sodass ein `palette="band=#…"` an der Einfassung auch sie umfärbt.
```ts
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' } },
}],
},
}
```
**Ein Teil, der sein Kapitel abschließt.** In einem Buch, das Kapitel für Kapitel umbrochen wird (die Sandbox, `buildBundle`), kann eine Einfassung `:::part` ein eigenes Kapitel sein oder das Ende eines Kapitels. Ihre Teiltitelseite ist dann die letzte Seite des Kapitels, und das nächste Kapitel übernimmt, was der Teil noch schuldet: Es wendet `breakAfter` vor seinem ersten Block an und zeichnet `versoDesign` auf seiner ersten Seite, wenn diese leer bleibt. Die Seiten fallen so aus, wie sie es mit dem ganzen Buch in einem Dokument täten. Nur Direktiven, die nichts platzieren (`:::numbering`, `:::space`), dürfen der Einfassung folgen; alles andere ist Inhalt des Kapitels, das dann den Umbruch selbst übernimmt. Ein leeres Kapitel direkt nach dem Teil ist eine eigene Seite: Diese Seite ist die linke Seite. Ein Host, der Kapitel selbst umbricht, erhält dies von `continuationAfter()`, das für ein Kapitel, das mit einem Teil endet, `afterPartPage: true` meldet; geben Sie es in der `continuation` des nächsten Kapitels weiter.
### Der Container `:::part`
Eine Zeile `:::part{number="…" title="…"}` öffnet den Teil, ein bloßes `:::` schließt ihn; beide Attribute sind optional (Standard ist `''`). Die Blöcke dazwischen – typischerweise die Kapitelliste – fließen mit `bodyStyle` in der einzigen Spalte der Teiltitelseite, beginnend bei `margins.top`; ein Inhalt, der länger als die Seite ist, geht auf gewöhnlichen Seiten weiter. Die Seite wird als `role: 'part'` eingestuft (`VDTPage.partInfo` trägt Nummer und Titel), sodass Elemente der Kopf- und Fußzeile sie mit `pages: 'part'` / `pages: 'body'` ansteuern oder auslassen können; die PDF-Ausgabe fügt den Teil der Gliederung über seinen Kapiteln hinzu. Ein leerer Inhalt (`:::part{…}` direkt gefolgt von `:::`) ist der übliche Fall und erzeugt trotzdem die Seite – aufeinanderfolgende Teile teilen sich nie eine. Ein in einem anderen Teil verschachteltes `:::part` wird in den äußeren eingeebnet.
Ein drittes Attribut, `palette="=[, =…]"`, gibt dem Teil eigene Farben: Auf der Teiltitelseite und auf jeder folgenden Seite – bis zum nächsten Teil – nimmt jede Gestaltungsfarbe (Kopfzeile, Fußzeile, Auftaktband, Teil- und Rückseitengestaltung), die an eine dieser Paletten-IDs gebunden ist, den Wert des Teils statt den der Dokumentpalette an. So färben die Abschnitte eines Buchs den Eckreiter, den Punkt im Kolumnentitel und das Band des Kapitelauftakts ohne zweite Gestaltung um: `:::part{number="II" title="…" palette="band=#f6c297"}`. Der Textfluss folgt ebenfalls: Auf denselben Seiten nimmt jede Flussfarbe, die dem Grundwert eines überschriebenen Paletteneintrags gleicht – Farben von Überschriften, Fettem, Kursivem und Verweisen, Aufzählungszeichen und Listennummern, Legendenbezeichnungen und Legendenbalken, Tabellentext, Tabellenlinien und -flächen (Kopf, Inhalt, Zebrastreifen und die eigene Fläche einer Zelle), Kästen (Hintergrund, Rahmen, Streifen, Titel) und Chips (Fläche, Umrisslinie und Text) –, den Wert des Teils an, sodass ein an `band` gebundenes `headings.levels[1].color` die Überschriften jedes Abschnitts in dessen eigener Farbe setzt. Inline-Farbfelder behalten die in ihnen geschriebene Farbe. Paare werden durch Kommas, Semikolons oder Leerzeichen getrennt, `=` oder `:` verbindet ID und Farbe, das `#` ist optional. Ein Teil bleibt nach dem Schließen seiner Einfassung wirksam: `{partTitle}`, `{partNumber}` und die Palette folgen dem Fluss in die Kapitel danach und – über `continuation.part`, das `continuationAfter()` meldet – in einzeln umbrochene Kapitel, sodass das zweite Kapitel eines Abschnitts den Abschnitt in seinen Kolumnentiteln genau wie das erste zeigt.
Zwei Paletteneinträge können denselben Grundwert haben und in einem Teil dennoch unterschiedliche Werte annehmen, wenn der Teil den einen überschreibt und den anderen nicht oder ihnen verschiedene Farben gibt. Der Wert allein sagt nicht, aus welchem Eintrag eine Flussfarbe stammt; daher wird jede Farbe des Flusses mit den Einstellungen abgeglichen, aus denen sie stammen kann, und nimmt den Wert an, an den diese Einstellungen gebunden sind. Unterschieden werden:
- die Farben des Texts eines Blocks: die Textfarbe, die Farben von Fettem, Kursivem und Verweisen, das Listenzeichen (ein Aufzählungszeichen oder eine Nummer) und das Trennzeichen nach einer Nummer. Mit `bodyText.color` an `ink` und `bodyText.boldColor` an `accent` gebunden, beide `#1a1a1a`, färbt ein Teil mit `palette="accent=#b8413d"` den fetten Text um und lässt den übrigen Text unverändert; ist stattdessen `unorderedLists.color` an `accent` gebunden, färbt er die Aufzählungszeichen um und lässt den Text der Einträge unverändert;
- jede Überschriftenebene und jeder Überschriftenstil, der eine Farbe setzt;
- der Text einer Zeile des Inhaltsverzeichnisses, ihre Nummer sowie ihre Seitenzahl und ihr Untertitel;
- in jedem Kastenstil die Flächen (Hintergrund, Streifen, Reiter), der Rahmen, die Linien (Marker und Reiter) und der Text (Titel, Symbol, Marker-Glyphe, Reiter);
- jede Farbe jedes Tabellen-, Chip- und Legendenstils. Ein benannter Tabellenstil ist von `tableStyle` getrennt, der Legendenstil eines Ressourcentyps von `captionStyle`. Die eigene Fläche einer Zelle folgt ihrer eigenen Bindung.
Ein Fall wird weiterhin nach dem Wert entschieden: Einstellungen an verschiedenen Stellen, die dieselbe Farbe eines Blocks setzen. `bodyText.color`, `bodyText.blockquote.color`, das `color` eines Absatzformats und das `body.color` eines Kastenstils setzen beispielsweise alle die Textfarbe eines Blocks. Sind zwei davon an Einträge mit demselben Grundwert gebunden und unterscheidet der Teil sie, nimmt die Farbe die Überschreibung an (die zuletzt geschriebene, wenn beide überschrieben sind). Geben Sie solchen Einträgen eigene Grundwerte.
```ts
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
```
## Überschriftenstile
Die Eigenschaft `headingStyles` deklariert benannte Stile, die ein Dokument mit `# Title {style=""}` auf eine Überschrift anwendet. Ein Stil leistet zweierlei. Er überschreibt Typografie, Gestaltung und Nummerierung der Überschriftenebene – jedes Feld eines Ebeneneintrags außer `level` (Schrift, Größe, Farbe, `breakBefore`, `span`, `advancedDesign`, `textTransform`, `hidden`, `numberingTemplate` …) –, und er bestimmt den **Abschnitt**, den die Überschrift eröffnet: Dessen Seiten, bis zur nächsten Überschrift derselben oder einer höheren Ebene, übernehmen Kolumnentitel, Seitengeometrie, Texttypografie und Palette des Stils. So steht die Titelei eines Buchs (ein Vorwort in einer einzigen breiten Spalte mit römischen Seitenzahlen und blauen Bändern) in einem zweispaltigen, dezimal nummerierten Handbuch, ohne dass es eine zweite Konfiguration braucht.
```ts
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' },
},
],
};
```
```md
# Preface {style="front-matter"}
```
| Eigenschaft | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `id` | `string` | — | Bezeichner, auf den `{style="…"}` in einer Überschriftenzeile verweist. Eine unbekannte ID lässt die Überschrift, wie sie ist. |
| `name` | `string` | `id` | Lesbarer Name (nur für die Editor-Oberfläche). |
| `numbered` | `boolean` | `true` | Ob die Überschrift zählt: Sie erhöht den Zähler ihrer Ebene (die Nummern von `numberingTemplate`, das `{h1}` der Ressourcennummern), die Kapitelordnungszahl hinter `{chapterNumber}` und die im Inhaltsverzeichnis gedruckte Nummer. `false` für ein Vorwort, ein Autorenverzeichnis, ein Register: Das erste nummerierte Kapitel danach ist weiterhin Kapitel 1, und `{chapterNumber}` ist auf ihren Seiten leer. |
| `toc` | `boolean` | `true` | Ob `:::toc` die Überschrift aufführt. Eine Überschrift überschreibt das mit `{toc="false"}` / `{toc="true"}`. |
| `runningChapter` | `boolean` | `true` | Ob eine Überschrift der Ebene 1 in diesem Stil zum laufenden Kapitel wird: dem Kapitel, das `{chapterTitle}`, `{chapterNumber}`, `{attr.}` und ihre Formen `…AtTop` auf ihrer Seite und den folgenden nennen. `false` für eine Tafel, eine Karte oder einen Umschlag, die als H1 in einem Kapitel gesetzt sind: Die Kolumnentitel übergehen sie, auch auf ihrer eigenen Seite, und nennen weiter das Kapitel, das sie unterbricht; sie setzt auch kein Leitwort `h1`. Die Überschrift zählt weiterhin, wenn `numbered` gilt (ihre eigene Gestaltung liest ihr eigenes `{chapterNumber}`), und wird weiterhin von `:::toc` aufgeführt, wenn `toc` gilt. Mit zusätzlich `toc: false` erhält sie kein PDF-Lesezeichen: Die Tafel eines Kapitels auf der Seite vor dessen Auftakt überlässt die Lesezeichen den Kapiteln. Überschriften anderer Ebenen ignorieren die Option. Mit dem Standard drucken die Seiten nach einer Tafel deren Titel. Ein Vorwort oder ein Prolog mit `numbered: false` ist weiterhin ein eigenes Kapitel und behält den Standard. Die Option ändert nur, welches Kapitel die Platzhalter nennen: Der Stil eröffnet weiterhin einen eigenen Abschnitt, wie jeder Überschriftenstil, sodass die Seiten bis zur nächsten Überschrift der Ebene 1 die Kolumnentitel-Plätze, Ränder, Spalten, den Textstil und die Palette des Tafelstils übernehmen (die des Dokuments, wo der Stil keine setzt), nicht die eines gestalteten Abschnitts, den das unterbrochene Kapitel eröffnet hat. In einem Buch, das Kapitel für Kapitel umbrochen wird, gehen die Kolumnentitel nicht von einer Kapiteldatei in die nächste über, sodass eine Tafel, die eine Datei eröffnet, bis zur ersten Kapitelüberschrift der Datei leere Kapitelplatzhalter zeigt. |
| Ebenenfelder | wie in `headings.levels[]` | die Werte der Ebene | `fontFamily`, `fontSize`, `lineHeight`, `fontWeight`, `italic`, `color`, `marginTop`, `marginBottom`, `snapToGrid`, `breakBefore`, `span`, `advancedDesign`, `textTransform`, `letterSpacing`, `lineSpan`, `indent`, `firstLineIndent`, `jidori`, `dropCap`, `hidden`: Jedes gesetzte Feld ersetzt für Überschriften dieses Stils den Wert der Überschriftenebene (`dropCap: false` entfernt die Initiale der Ebene). `breakBefore` wird Feld für Feld mit dem der Ebene zusammengeführt: Ein Stil, der nur `parity` setzt, behält das `enabled` der Ebene, und einer, der nur `enabled: true` setzt, behält ihre Parität (bis postext 1.4 kam das fehlende Feld stattdessen aus dem Standard ohne Umbruch). |
| `numberingTemplate` | `string` | die der Ebene | Vorlage, mit der die Überschriften des Stils nummeriert werden, anstelle der ihrer Ebene (dieselben Platzhalter wie [`levels[].numberingTemplate`](https://postext.dev/de/docs/configuration-text.md#überschreibungen-pro-ebene)). Der Zähler bleibt der der Ebene: Ein Anhangsstil mit `'Appendix {1:A}'` nach fünf Kapiteln druckte *Appendix F*; starten Sie die Zählung daher mit `{startAt=1}` beim ersten Anhang neu. `''` druckt keine Nummer, während die Überschrift weiterhin zählt: nicht einmal die Kapitelordnungszahl, die Inhaltsverzeichnis und `{chapterNumber}` für eine Überschrift der Ebene 1 ohne Vorlage zeigen. Die Nummer erscheint im Fluss, im `{number}` der Gestaltung des Stils, im Inhaltsverzeichnis und in `{chapterNumber}`. |
| `header`, `footer` | `DesignSlot` | die des Dokuments | Kolumnentitel der Seiten des Abschnitts, die dort `header` / `footer` ersetzen (die Filter `parity` und `pages` der Elemente gelten weiterhin). Ein leerer Platz entfernt sie. |
| `margins` | `PageMargins` | Seitenränder | Textbereich der Seiten des Abschnitts; jede Seite erbt, wenn nicht gesetzt, den Seitenrand, `mirror` eingeschlossen. Wirkt auf den Seiten, die der Abschnitt eröffnet – kombinieren Sie es mit `breakBefore`. |
| `layout` | `LayoutConfig` | `layout` | Spaltenlayout der Seiten des Abschnitts (`layoutType`, `gutterWidth` …): eine einzige breite Spalte für ein Vorwort in einem zweispaltigen Buch. Seine `columnRule` wird auf den Seiten des Abschnitts gezeichnet, und jedes Feld, das es nicht setzt, übernimmt den Wert von `layout.columnRule` des Dokuments, sodass ein Abschnitt, der nur seine Spalten ändert, die Spaltenlinie des Dokuments behält (siehe [Spaltenlinie](https://postext.dev/de/docs/configuration-page-layout.md#spaltenlinie)). |
| `bodyStyle` | `PartsBodyStyleConfig` | erbt `bodyText` | Typografie der Absätze, Zitatblöcke und Listen im Abschnitt – dieselben Felder wie [parts.bodyStyle](https://postext.dev/de/docs/configuration-styles.md#teile). |
| `palette` | `Record` | `{}` | Überschreibungen der Palette (ID → Hex) für die Seiten des Abschnitts, über denen des aktuellen Teils – derselbe Mechanismus wie das Attribut `palette` eines Teils und mit derselben Reichweite: nicht nur die auf diesen Seiten gesetzten Gestaltungsplätze (Kolumnentitel, das Auftaktband – jede an eine überschriebene ID gebundene Farbe), sondern auch der Textfluss, nach Wert: Jede Flussfarbe, die dem Grundwert eines überschriebenen Eintrags gleicht – Farben von Überschriften, Fettem, Kursivem und Verweisen, Aufzählungszeichen und Listennummern, Legendenbezeichnungen und Legendenbalken, Tabellentext, Tabellenlinien und -flächen, Kästen (Hintergrund, Rahmen, Streifen, Titel) und Chips (Fläche, Umrisslinie und Text) –, nimmt den Wert des Abschnitts an, wie unter einem Teil, einschließlich der Regel für zwei Einträge mit demselben Grundwert (siehe [Der Container `:::part`](https://postext.dev/de/docs/configuration-styles.md#der-container-part)). Inline-Farbfelder behalten die in ihnen geschriebene Farbe. Auch die Seitenfarbe folgt: Ist `page.backgroundColor` an einen überschriebenen Eintrag gebunden (oder hat es, ungebunden, dessen Grundwert), werden die Seiten des Abschnitts im Wert des Abschnitts gefärbt, sodass die Wirtschaftsseiten einer Zeitung auf Lachsrosa gedruckt werden, während die übrigen weiß bleiben. Seit postext 1.18. |
Ein Abschnitt endet an der nächsten Überschrift derselben oder einer höheren Ebene: Ein ungestaltetes `#` nach einem gestalteten kehrt zu Kolumnentiteln und Geometrie des Dokuments zurück; ein gestaltetes eröffnet seinen eigenen Abschnitt. Seiten, die der Abschnitt für die Parität leer gelassen hat, gehören zu ihm, wie es bei Kapiteltiteln der Fall ist.
**Ein Seitenumbruch ersetzt nicht den eigenen Umbruch der Überschrift.** Ein Stil erbt das `breakBefore` seiner Ebene (der Standard für Ebene 1 ist `{ enabled: true, parity: 'always-odd' }`), und eine Überschrift wendet es an, wo immer sie steht, auch direkt nach einem `:::pagebreak`. Der Seitenumbruch eröffnet eine neue Seite, und die Überschrift verlangt dann trotzdem ihre Seite der Doppelseite. Mit `parity: 'odd'` folgt auf einen Umbruch, der auf einer linken Seite landet, eine Vakatseite, sodass die Überschrift auf der nächsten rechten Seite beginnt. Mit `'always-odd'` kommt auch die trennende Vakatseite hinzu, und der Seitenumbruch ändert nichts, da die Überschrift diese Seite ohnehin eröffnet hätte. Ein Stil, der auf der Seite beginnen soll, die ein manueller Umbruch eröffnet, etwa eine Inhaltsseite nach der Titelseite, schaltet seinen eigenen Umbruch aus:
```ts
headingStyles: [
// Starts where the text puts it: on the page the `:::pagebreak` before it opened.
{ id: 'contents', numbered: false, toc: false, breakBefore: { enabled: false } },
],
```
Um eine eigene Seite zu behalten, ohne eine Seite der Doppelseite zu wählen, setzen Sie stattdessen `breakBefore: { parity: 'any' }` und lassen das `:::pagebreak` weg.
**Zu welchem Abschnitt eine Seite gehört.** Kolumnentitel und Palette werden pro Seite gewählt, nicht pro Überschrift. Eine Seite übernimmt den Abschnitt, der nach dem letzten Abschnittswechsel auf ihr gilt: Wo ein Abschnitt auf derselben Seite endet und ein anderer beginnt – etwa zwei kurze Buchstaben eines Wörterbuchs –, trägt die Seite Kolumnentitel und Palette des zweiten; wo ein gestalteter Abschnitt mitten auf der Seite an einer ungestalteten Überschrift endet, kehrt die Seite zu denen des Dokuments zurück. `{chapterTitle}` folgt derselben Regel: Eine Seite, auf der zwei Kapitel zusammentreffen, zeigt den Titel des späteren. Leere Seiten folgen der Regel für [Kapiteltitel](https://postext.dev/de/docs/configuration-text.md#zugehörigkeit-leerer-seiten): Eine Vakatseite für die Parität (`blankForParity`) gehört zum Abschnitt, der nach ihr beginnt, und die Trennseite, die ein Umbruch `'always-odd'` / `'always-even'` hinzufügt (`blankForForce`), zum Abschnitt davor. Ein Teiltitel schließt den offenen Abschnitt.
```md
# A {style="letter"}
Aardvark, abacus.
# B {style="letter"}
Babble, badger… (runs on to the next page)
```
Beide Buchstaben beginnen auf Seite 1, also übernimmt Seite 1 die Kolumnentitel des Abschnitts `B`: Ein im Kopf des Stils gesetzter Daumenregister-Reiter zeigt dort „B“, und keine Seite trägt den Reiter für „A“. Geben Sie jedem Abschnitt eine eigene Seite (`breakBefore`), wenn jeder seinen Reiter braucht.
Mit Buchstaben gezählte Anhänge nach nummerierten Kapiteln und eine Widmungsseite, die Inhaltsverzeichnis und PDF-Lesezeichen aufführen, die Seite selbst aber nicht betitelt:
```ts
headingStyles: [
{ id: 'appendix', numberingTemplate: 'Appendix {1:A}' },
{ id: 'silent', hidden: true, numbered: false },
],
```
```md
# Dedication {style="silent"}
For M., who read every draft.
# Method
…
# Survey instrument {style="appendix" startAt=1}
# Raw data {style="appendix"}
```
Mit `numberingTemplate: '{1}.'` auf Ebene 1 drucken die Kapitel *1.*, *2.* …, die Anhänge *Appendix A* und *Appendix B*. Die Widmung eröffnet ihre Seite (das `breakBefore` ihrer Ebene), druckt nur ihren Absatz und erscheint trotzdem als *Dedication* in `:::toc`, in Kolumnentiteln mit `{chapterTitle}` und in der PDF-Gliederung – fügen Sie dem Stil `toc: false` hinzu, um sie aus dem Inhaltsverzeichnis herauszuhalten. Eine Tafel oder Karte, die mitten in einem Kapitel als H1 gesetzt ist, verlangt das Gegenteil der Widmung: Ein Stil mit `runningChapter: false` (meist mit `numbered: false` und `toc: false`) hält die Kolumnentitel bei dem Kapitel, das sie unterbricht.
```ts
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
```