Konfiguration: Stile und Teile

#Absatzformate

Die Eigenschaft paragraphStyles deklariert benannte Stile, die ein Dokument mit einem Container :::paragraphs{style="…"} auf eine Folge von Absätzen anwendet – Literaturverzeichnisse, Glossare, Anmerkungen, jeder Block von Einträgen, der eine eigene Schrift, Schriftstärke, Neigung, Größe, einen eigenen Zeilenabstand, Versalien, Kapitälchen oder einen hängenden Einzug verlangt. Jedes typografische Feld ist optional und erbt, wenn nicht gesetzt, den Wert des Fließtexts; ein Stil nennt also nur, was vom Fließtext abweicht.

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

Ein Theaterstück setzt seine Regieanweisungen kursiv und sein Personenverzeichnis in Kapitälchen:

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

Die Anweisung erscheint kursiv, der Name darin aufrecht; Schriftstärken, italic und smallCaps eines Stils gelten auch in Kästen.

Ein Gedichtband rückt manche Zeilen ein und hängt den Umbruch einer für die Satzbreite zu langen Zeile tiefer ein als die Zeile selbst. indent rückt jede Zeile des Absatzes ein, und der hängende Einzug zählt von dort aus:

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' } },
],

Eine Zeile in verse-indented beginnt bei 1,5 em und ihr Umbruch bei 4 em, auf gleicher Höhe mit den Umbrüchen der Zeilen in verse. Ohne indent kann ein Stil die erste Zeile einrücken oder die übrigen einhängen, nicht beides: firstLineIndent wird ignoriert, sobald hangingIndent gesetzt ist.

Eine Speisekarte setzt jeden Preis bündig an das Ende der Satzbreite, hinter eine Punktlinie:

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

Die Punkte jeder Zeile enden ein halbes Geviert vor dem Preis (leaderGap). Ein Gericht, das für seine Zeile zu lang ist, wird umbrochen, und seine letzte Zeile behält Punktlinie und Preis; passt der Preis nicht neben das letzte Wort, geht dieses Wort mit ihm in die nächste Zeile.

#Der Container :::paragraphs

Eine Zeile :::paragraphs{style="<id>"} öffnet den Container, eine bloße Zeile ::: schließt ihn; jeder Absatz dazwischen erhält den benannten Stil, während Überschriften, Listen und andere Blöcke darin ihre übliche Gestaltung behalten. Container dürfen in anderen eingefassten Containern verschachtelt werden. Eine unbekannte style-ID ist kein Fehler: Die Absätze erscheinen als schlichter Fließtext.

Die Einfassung nimmt außerdem align (start, end, left, right, center, justify), indent und endIndent (bloße Zahlen sind Geviert), mit oder ohne Stil: Mit Stil überschreiben sie ihn; ohne gelten sie über dem Stil des umschließenden Containers oder über dem Textstil an der Stelle der Einfassung (der Fließtext, ein Teil, ein gestalteter Abschnitt oder ein Kasten). :::paragraphs{align=end} setzt einen Block bündig an das Zeilenende (地付き) und :::paragraphs{align=end endIndent=1} ein Zeichen davor. Seit postext 1.16.

Im Container verlässt der Textfluss das Grundlinienraster – ein Eintrag in 7 pt mit 1,2 em Zeilenabstand passt nicht auf ein Raster von 8 pt/1,5 em –, und der letzte Absatz rastet den Fluss wieder darauf ein (das Raster hat Vorrang; der Abstand darunter ist ein Mindestwert, dieselbe Konvention, der Überschriften folgen). Einträge teilen sich über Spalten und Seiten wie Absätze des Fließtexts, mit demselben Schutz vor Witwen und Waisen; eine Überschrift unmittelbar vor dem Container bleibt bei dessen erstem Absatz.

Der Abstand unter dem Container ist der größere von spaceBetween und marginBottom des Stils und dem Absatzabstand des umgebenden Texts (eine Zeile, wenn bodyText.paragraphSpacing eingeschaltet ist), und er verschmilzt mit dem Abstand, den der nächste Block über sich hält, wie es der Abstand zwischen zwei Absätzen des Fließtexts tut: Eine Überschrift nach einem Literaturverzeichnis steht um ihr eigenes marginTop unter dem letzten Eintrag (oder um den Abstand des Stils, wenn dieser größer ist), und ein Absatz nach einer Gruppe engerer Einträge behält den Absatzabstand des Texts. Der Fluss rastet zuerst unter dem Text wieder auf das Raster ein, und was das Einrasten nicht abgedeckt hat, wird in ganzen Rasterzeilen weitergeführt, sodass der Text nach dem Container auf dem Raster landet. Bis postext 1.4 wurde der Abstand des Stils vor dem Einrasten unter die letzte Zeile gesetzt und der obere Abstand des nächsten Blocks darunter addiert, und der Absatzabstand blieb außen vor; bodyText.paragraphContainerSpacing: 'add' behält diese Regel, und vorher gespeicherte Konfigurationen werden damit gelesen. Ein Stil mit snapToGrid: false rastet nicht ein: Der Text nach dem Container steht um den genauen Abstand darunter, außerhalb des Rasters bis zum nächsten einrastenden Block. Ein Container, der mit einer Liste schließt, wird unter beiden Regeln wie in 1.4 gesetzt: Die Liste behält ihren eigenen Abstand darunter, und marginBottom folgt diesem Abstand und verschmilzt mit dem des nächsten Blocks.

Ein Stil kann die Regel für seine eigenen Container mit containerSpacing festlegen: 'add' am Stil einer großen Abbildung oder eines Literaturverzeichnisses beendet seine Gruppen mit dem eigenen Abstand des Stils, im Text und in einem Kasten, während jeder andere Container des Dokuments 'collapse' behält; 'collapse' an einem Stil bewirkt das Umgekehrte in einem Dokument, das mit 'add' gelesen wird. Ein Container, der keinen Stil nennt, folgt dem Dokument.

In einem :::callout übernimmt der Container die Außenabstände seines Stils auf dieselbe Weise: marginTop und marginBottom fallen mit dem Abstand der umgebenden Blöcke zusammen (ein negativer Wert zieht sie näher heran), und ein Container, der den Kasten eröffnet, erhält keinen oberen Außenabstand, wie am Kopf einer Spalte. Ein Kasten hat kein Grundlinienraster zum Einrasten, daher ist der Abstand unter dem letzten Absatz der größte von marginBottom, spaceBetween und dem eigenen Absatzabstand des Kastens (sein body.paragraphSpacing, eine Zeile seines Texts; entfällt mit paragraphContainerSpacing: 'add'), oder der eigene obere Außenabstand des nächsten Blocks, wenn dieser noch größer ist; ein negatives marginBottom zieht stattdessen den nächsten Block nach oben. (Bis postext 1.4 ignorierte ein Container in einem Kasten beide Außenabstände.)

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

#Chip-Stile

Die Eigenschaft chipStyles deklariert die benannten Stile des Inline-Elements :chip[text]{style="…"} – die abgerundeten, getönten Kästchen eines Wortspeichers, einer Tastaturtaste, eines Schlagworts (Syntax und Umbruchregeln stehen in der Referenz zum Dokumentformat). Ein Stil, chip, ist standardmäßig dabei (eine blassblaue Fläche mit einer Haarlinie in der Hauptfarbe, leicht abgerundet, der Text wie die umgebenden Wörter), sodass :chip[…] ohne jede Konfiguration funktioniert; wer chipStyles deklariert, ersetzt diese Standardliste. Ein Chip ohne style oder mit einer ID, die kein Stil deklariert, erhält den ersten Stil.

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"}.

Em-Längen des Kästchens (paddingX, paddingY, borderRadius, borderWidth, gap) beziehen sich auf die eigene Schriftgröße des Chips. Das Kästchen ist ein Band 0,8 em über und 0,25 em unter der Grundlinie, vergrößert um paddingY und die Umrisslinie; es wird außerhalb des Zeilenkastens gezeichnet und ändert nie den Zeilenabstand, sodass das Grundlinienraster hält. Wird das Kästchen höher als der Zeilenabstand, kann ein Chip in einen Chip auf der Zeile darüber oder darunter hineinragen – die Sandbox listet die Warnung „Chips berühren die nächste Zeile“, wenn sich zwei Chips auf verschiedenen Zeilen überlappen, mit der Überlappung in Punkt, sodass sich paddingY, die Umrisslinie oder fontSize verringern lassen. Ein hoher Chip ohne Chip darüber oder darunter wird nicht gemeldet.

Im VDT ist ein Chip ein Zeilensegment mit kind: 'chip', dessen Feld chip die Textläufe (jeder mit seiner Schriftangabe und Breite), die Geometrie des Kästchens (boxWidth, ascent, descent, paddingX, borderWidth, borderRadius, die Abstandsränder) und seine Farben trägt; der text des Segments ist ein Platzhalter aus einem Zeichen, sodass Klartext-Offsets und Quellzuordnungen einen Chip als ein Zeichen zählen.

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

#Code-Listings

Die Eigenschaft codeStyle legt fest, wie Code-Listings aussehen: die Codezäune ``` und ~~~ des Texts (siehe Dokumentformat › Codeblöcke) und Inline-Code, wenn er eine Code-Schrift verlangt. Ein Listing wird Zeile für Zeile so gesetzt, wie es geschrieben ist, in einer dicktengleichen Schrift, in einem Kasten: Keine Zeile wird getrennt oder im Blocksatz gesetzt, jedes Leerzeichen behält seine Breite, und ein Tabulator springt zum nächsten Tabstopp. Der Kasten stammt aus derselben Mechanik wie ein :::callout, sodass sich ein Listing zwischen Zeilen über Spalten und Seiten teilt, jeder Teil in einem eigenen Kasten, und ein Codeblock in einem Kasten ein darin verschachtelter Kasten ist. Jede Eigenschaft ist optional. Seit 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' } },
  },
};

#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).

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:

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.

#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 <pre><code class="language-…"> 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.

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

#Der Container :::callout

Eine Zeile :::callout{type="<id>"} ö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).
• 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). 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.

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.

Ein Beweis ist ein Stil mit einer nicht nummerierten Bezeichnung und einem Schlusszeichen:

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 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.

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

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.

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

#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.<key>} 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.

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="<id>=<hex>[, <id>=<hex>…]", 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.

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="<id>"} 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.

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"}

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:

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

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

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"}

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.

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