配置：样式与篇

#段落样式

paragraphStyles属性声明具名样式，文档用:::paragraphs{style="…"}容器把它们应用到一组段落上：参考文献、术语表、注释，以及任何需要自己的字体、字重、倾斜、字号、行距、大写、小型大写字母或悬挂缩进的条目块。每个排版字段都是可选的，未设置时继承正文，所以一个样式只需写出与正文不同的地方。

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

剧本把舞台说明排成斜体，把演员表排成小型大写字母：

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

舞台说明印成斜体，其中的人名印成正体；样式的字重、italic和smallCaps在标注框内同样适用。

诗集会缩进某些诗行，并让超出行长的诗行的转行比诗行本身缩得更深。indent把段落的每一行向内移，悬挂缩进从那里量起：

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

verse-indented中的诗行从1.5 em处开始，转行从4 em处开始，与verse中各行的转行对齐。没有indent时，一个样式只能缩进首行或悬挂其余各行，不能两者兼得：一旦设置了hangingIndent，firstLineIndent就被忽略。

菜单把每个价格排在一行点之后，与版心末端对齐：

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

:::paragraphs{style="menu"}
洋葱汤 :tab 8.50
 
茴香柠檬烤鲷鱼 :tab 21.00
:::

每一行的点都在价格前0.5 em处结束（leaderGap）。菜名太长、一行排不下时换行，最后一行保留前导符和价格；价格在最后一个词旁边放不下时，这个词随价格一起移到下一行。

#:::paragraphs容器

:::paragraphs{style="<id>"}一行打开容器，单独的:::一行关闭容器；其间的每个段落都采用指定样式，而其中的标题、列表和其他块保持各自的常规样式。容器可以嵌套在其他围栏容器中。未知的style id不算错误：这些段落按普通正文渲染。

围栏还接受align（start、end、left、right、center、justify）、indent和endIndent（纯数字按em计），有没有样式都可以：有样式时，它们覆盖样式的设置；没有样式时，它们作用于外层容器的样式之上，或作用于围栏所在位置的文字样式之上（正文、篇、带样式的章节或标注框）。:::paragraphs{align=end}把一块文字排得与行尾对齐（地付き），:::paragraphs{align=end endIndent=1}则离行尾一个字。从postext 1.16起提供。

在容器内，文字流离开基线网格（7pt、行距1.2em的条目无法落在8pt/1.5em的网格上），最后一段让文字流重新对齐网格（以网格为准；下方空白是最小值，与标题遵循的约定相同）。条目像正文段落一样跨栏、跨页拆分，并有同样的段首孤行和段末孤行保护；紧接在容器之前的标题与容器的第一段保持在一起。

容器下方的空白取样式的spaceBetween和marginBottom与周围文字段落间距（开启bodyText.paragraphSpacing时为一行）中的较大者，并与下一个块在自身上方保留的空白合并，就像两个正文段落之间的空白那样：参考文献之后的标题位于最后一个条目下方自身marginTop处（若样式的空白更大，则取样式的空白）；一组较紧的条目之后的段落保留正文的段落间距。文字流先在文字下方重新对齐网格，对齐未覆盖的部分以整行网格顺延，因此容器之后的文字落在网格上。在postext 1.4及以前，样式的空白设在对齐之前的最后一行下方，下一个块上方的空白再加在其下，且不计段落间距；bodyText.paragraphContainerSpacing: 'add'保留这一规则，在它出现之前保存的配置也按它读取。设置了snapToGrid: false的样式不对齐网格：容器之后的文字恰好位于其下方指定空白处，偏离网格，直到下一个会对齐网格的块。以列表结尾的容器，在两种规则下都按1.4的方式排：列表保留自身下方的空白，marginBottom跟在这段空白之后，与下一个块的空白合并。

在:::callout内，容器以同样的方式采用其样式的外边距：marginTop和marginBottom与周围块的间距合并（负值会让它们靠得更近），位于框开头的容器不取上外边距，与栏顶相同。框内没有可重新对齐的基线网格，所以最后一段下方的空白取marginBottom、spaceBetween和框自身段落间距（其body.paragraphSpacing，即框内文字的一行；使用paragraphContainerSpacing: 'add'时不计）中的较大者，若下一个块自身的上外边距更大，则取后者；负的marginBottom则把下一个块往上拉。（在postext 1.4及以前，标注框内的容器忽略这两个外边距。）

const resolved = resolveParagraphStylesConfig(config.paragraphStyles, resolvedBodyText);
// => 每个未设置的字段都从解析后的正文填入
 
const minimal  = stripParagraphStylesDefaults(config.paragraphStyles);
// => 列表为空时为undefined；去掉为零的外边距和`name === id`

#行内标签样式

chipStyles属性声明行内:chip[text]{style="…"}的具名样式，即词库、键盘按键、标签所用的圆角着色小框（语法及其断行规则见文档格式参考）。默认提供一个样式chip（浅蓝色填充，主色细线描边，略带圆角，文字与周围词语相同），因此:chip[…]无需任何配置即可使用；声明chipStyles会替换这一默认列表。没有style的行内标签，或所用id未被任何样式声明的行内标签，采用第一个样式。

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长度（paddingX、paddingY、borderRadius、borderWidth、gap）相对于行内标签自身的字号。框是基线上方0.8 em、下方0.25 em的一条带，再加上paddingY和轮廓；它绘制在行框之外，从不改变行距，因此基线网格保持不变。框最终高于行距时，行内标签可能与上一行或下一行的行内标签相碰：当不同行上的两个行内标签重叠时，沙盒会列出“行内标签碰到相邻行”警告，并给出以点为单位的重叠量，以便减小paddingY、轮廓或fontSize。上下都没有行内标签的高行内标签不会被标出。

在VDT中，行内标签是kind: 'chip'的行片段，其chip字段携带文字串（各带字体字符串和宽度）、框的几何数据（boxWidth、ascent、descent、paddingX、borderWidth、borderRadius、间隙外边距）及其颜色；片段的text是一个单字符占位符，所以纯文本偏移量和源映射把一个行内标签计为一个字符。

const resolved = resolveChipStylesConfig(config.chipStyles);
// => 未设置时为内置的`chip`样式；每个字段都已填入
 
const minimal  = stripChipStylesDefaults(config.chipStyles);
// => 内置默认值时为undefined；去掉静态默认值
 
const style = pickChipStyle(resolved, 'key');
// => `key`样式，否则取第一个

#代码清单

codeStyle属性设定代码清单的外观：正文中的```和~~~围栏（见文档格式 › 代码块），以及要求用代码字体时的行内代码。清单按原样逐行排，用等宽字体，排在一个框中：任何一行都不断词、不两端对齐，每个空格保持自己的宽度，制表符前进到下一个制表位。这个框与:::callout出自同一套机制，所以清单可以在行与行之间断开，跨栏跨页，每部分各有一个框；标注框中的围栏是嵌套在其中的框。所有属性都是可选的。自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' } },
  },
};

#语法着色

引擎内置一个小型分词器，能识别以下语言的记号：js和ts（javascript、jsx、typescript、tsx）、json、python、bash（sh、zsh、shell）、console（shell会话）、css、html和xml（svg）、markdown以及sql；其他语言或未注明语言的清单都用color排。它读取整段清单，所以跨行的注释或字符串仍是一个记号。在console清单中，以提示符（$ 、% 、# 、> 、>>> 、PS …> ）开头的行是用户输入的内容（prompt），其他各行都是程序印出的内容（output）。

宿主程序可以用registerCodeHighlighter接入自己的高亮器（Shiki、Prism、highlight.js）。配置是可序列化的数据，所以这个函数注册到引擎上，而不是写在codeStyle中：

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

为某种语言注册的高亮器优先于为'*'注册的高亮器，后者又优先于内置分词器。每个片段要么指明一个token类别（由tokens着色），要么带有自己的color（CSS十六进制值）。高亮器返回undefined、抛出异常，或返回的各行拼不回清单本身的各行时，就跳过它。排版在排清单时读取注册表：要在构建之前注册；在web worker中排版时（沙盒就在worker中排版），要在worker内注册。

#行内代码

codeStyle.inline让反引号之间的文字用代码字体排：作为一个整体，与行内标签一样，行内不会在其中断开。未设置时，行内代码保持正文字体。

#清单如何排版

• 一行源文对应一行。 各行按代码字体自身的前进宽度构建，不经过段落断行器：空格保持宽度，连续的空格都保留，行首空格形成缩进。在从右向左的书中，清单从左向右读，各行从框的另一侧排起，与从左向右的引文相同，行号在它们左侧的边栏中。在竖排的书中，清单随竖排方向排（其中的拉丁文按竖排的惯例横躺），不带行号。
• 拆分。 比剩余空间高的清单在行与行之间断开，跨栏跨页，每部分各自成框，每侧至少留下splitMinLines行；只要有别的切口可用，折行的余下部分就与它所属的行留在一起。
• 输出。 画布、HTML查看器和PDF按排版结果画出各行和框。HTML查看器保留空格（white-space: pre），所以选区复制出的清单带有缩进，每行源文之后有一个换行，不带行号和续行标记。带标签的PDF把每段清单设为一个包含Code元素的段落，空格是真正的空格字形，行号和续行标记是artifact。可重排的EPUB写出<pre><code class="language-…">，带有记号的颜色和一份由codeStyle生成的样式表；固定版式的EPUB与印刷版相同。
• 字体。 正文含有围栏（或配置中有codeStyle分区）时，沙盒和configFontFamilies会加载代码字体的常规和粗体字重，直体和斜体都有；PDF嵌入各行所用的字体。

#标注框样式

calloutStyles属性声明一组具名的框样式，文档用:::callout{type="…"}容器来套用：注释、提示、警告、学习目标，以及任何需要用底色框或描边框与正文区分开的内容。默认只带一种中性样式note（浅灰底色，无边框、无色条、无图标、无标题），所以不做任何配置也能使用:::callout；一旦声明calloutStyles，就会替换这份默认列表。

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

#:::callout容器

:::callout{type="<id>"}一行打开框，单独一行:::关闭它。围栏接受五个属性：type（样式id）、title（覆盖样式的标题）、span、placement和columns（覆盖样式中的值）；两者之间的内容排在框内：先是可选的标题，然后是段落、列表、引文块、公式或资源嵌入，各自按样式的body / lists排版（标题保留它们平常的样式）。子块之间的外边距像正文中一样合并；框内部脱离基线网格，框之后文字流回到网格上，框下方至少留出marginBottom（以网格为准，外边距是最小值，资源遵循的也是这一约定）。snapToGrid: false的样式则保持精确的marginBottom，框之后的正文一直偏离网格，直到下一个标题或列表结尾。紧挨在标注框之前的标题与框保持同栏。

本版本的限制：

• 标注框保持完整，除非其样式设置了keepTogether: false。栏中剩余空间放不下时，它整个移到下一栏或下一页；一个被浮动区带或区带上限截短的空栏，只要完整的一栏能容纳它，框也会从中移出。比一整栏还高的框改为拆分，与可拆分的框一样；只有任何切口都拆不开的框（比栏还高的图、表或:::columns组，或没有切口能满足的splitMinLines）才会照排并溢出；此时版面记录一条calloutOverflow警告（VDTDocument.warnings），沙盒会列出它。可拆分的框留下能放下的部分，即完整的子块，或段落的若干行，每侧不少于splitMinLines行（单独一个图、表或独立公式就足以构成一侧），然后在下一栏或下一页的一个不带图标的框中继续，除非样式重复标题，否则也不带标题，还可以在它留下的部分下方加一个标记（见拆分框的标记）。
• 浮动体让位于不可拆分的框。当图的引用之后紧接的块是keepTogether标注框时，如果某个位置会让这个框在当前栏带中无栏可落（引用所在的栏，或它之后的空栏，在浮动之前本可容纳它），就不采用这个位置：图移到它的下一个位置，通常是下一页，框留在文字流中。这正是排版工人的做法：不会把框挤出页面，只在栏里留下那张图。
• 在多栏版式中，span: 'page'让框成为通栏块：它按整个版心宽度排布，把页面切分成栏带。它上方的各栏文字在切线处结束，框自己占一个通栏宽的栏，下方新开一组文字栏，文字流在每一栏中都从框下继续。在各栏平齐的地方，即页面顶端、span: 'page'的章首标题正下方、另一个通栏块正下方，或顶部浮动区带正下方，框直接在那里切开。如果它在页面中部出现、各栏参差不齐，就按排版工人的方式处理：它上方的正文在所有栏中齐平切断（引擎把该栏带的各栏缩短到相同的网格行数后重新排布，于是文字自然地从一栏流向下一栏，所有段首孤行、段末孤行和与下文同栏的规则照样生效），框横跨整页，各栏在它下方继续。切断要多跑几遍排布；如果切线下方放不下框加上段首孤行（widow）规则所需的最少正文行数，或者尝试几次后仍没有合适的排法，框就移到下一页顶端。上方的正文遵守这条切线：一栏在图下方只剩几行、放不下一个段落的开头时，该段落移到下一栏（图于是单独占据那一栏）；当某个块仍会越过切线时，切线下移一行，而不是移到那个块结束的地方。开启栏带的拆分框也在那里切断，所以它的其余部分不会越过切线。在headings.balancing.beforeSpan（默认开启）下，框离开的栏带在它后面齐平切断，就像一章的收尾栏带；样式允许拆分时（keepTogether: false），框中能放进拉齐后各栏下方的部分结束这一页，其余部分开启下一页。设beforeSpan: false时，框离开的页面只做常规的各栏齐底，不强制分页。紧挨在通栏块之前的标题不随它移动。在单栏版式中，span: 'page'就是普通的行内排布。
• placement: 'fixed'把框移出文字流：先排出框（width: 'auto'按标题收缩宽度；'fill'取锚点下方那一栏的文字宽度），再把它固定在它在文字流中所在的页面上，位置由fixed.anchor / fixed.offset描述，默认为内容区的左下角。它覆盖的文字栏让出这块区域（从底部截去，栏仍为空时从顶部截去），与浮动区带完全相同；如果这块区域中已经有正文、浮动体或通栏块，框就移到下一页。收尾一章的固定框（下一个块是章首页、:::part、浮动体屏障框或文档末尾）会先把它上方的各栏拉齐（headings.balancing.trailing），这样较短的收尾页会齐底结束，下方是徽标。框形和子块放在page.floats中，在所有后端中都在栏的裁切区之外渲染。
• placement: 'top' | 'bottom'让框像资源一样浮动：它在出现处离开文字流，占用该处之后第一个空闲区带，即当前页的页脚（'bottom'），或文字流打开的下一页的页首 / 页脚，宽度为一栏（span: 'column'）或整个版心（span: 'page'）；它之后的正文填满它离开的那一页。它的框形和子块进入page.floats，与固定框一样。位于新一页页首的浮动框排在等待该页的图之前；在较早一页引用、随后能放在它下方的图，即使剩下的正文不足三行，也会占满该页其余部分（图集页：框加图，中间没有正文）。span: 'side'框从不浮动：无论placement如何，它都叠放在正文旁边。columns大于1时（在样式中或作为围栏属性，postext 1.18起），span: 'column'框占用这么多相邻的栏：一组顶端平齐的空栏的栏首，或者当前栏及其后空栏的栏脚，例如:::callout{placement="top" columns="2"}。
• width: 'auto'只按标题收缩宽度，子内容被忽略。
• 嵌套在另一个标注框中的:::callout是一个独立的框：它按自己的样式（底色、边框、圆角、内边距、色条、标题、图标、标记、标签、排版）以父框的全部内宽排布，作为父框的一个子块叠放，其marginTop / marginBottom与相邻块合并。它的span和placement（围栏或样式中的）被忽略，嵌套框总是在父框内顺排；floatBarrier和snapToGrid同样被忽略。框可以任意层级嵌套，也可以放在:::columns组中（每个框完整地位于一栏中）。父框拆分时，切口落在嵌套框之前或之后，嵌套样式允许拆分时也可以落在它内部；每个片段都会重画它切过的框形，从上一个片段接续过来的嵌套框不带标题和图标，与顶层的接续部分一样。
• 子块中的:::columns{count=N} … :::组在框内把这些子块排成N个等宽的栏，间距为columnGap：这一串内容在最能让各栏平齐的块边界或行边界处切开（在中途切开的段落或列表项在下一栏开头继续，不带项目符号），每一栏都从组的顶部开始，组的高度等于最高的一栏；组之后的子块恢复全宽。拆分的框（keepTogether: false，或比一栏还高的框）也会在组内部、各栏之间切开：蛇形组依次填满各栏，接到下一个片段；平行组（breaks）则逐个流接续（postext 1.25起；见文档格式 › :::columns）。围栏上的gap为该组替代columnGap，rule在每条栏间空白中画一条竖线。可用来排两栏的要点小结，或让宽框中的几张表并排。
• 围栏的第六个属性label印在样式的标签上（见上文label）：:::callout{type="box" label="BOX 1-1" title="The octet rule"}；样式没有label时忽略该属性。

在VDT中，框是一个type: 'callout'的框形块，其装饰（底色、色条、图标、标题）放在designOverlay上，后面在同一栏中跟着它的子块；框形和每个子块都带有围栏的containerId。嵌套框是子块中一个独立的type: 'callout'框形，后面跟着它自己的块；这些块保留顶层围栏的containerId（排布和各栏齐底仍把它们看作一个单元），并加上calloutPath，即包围它们的各层嵌套围栏的容器id，由外到内排列（嵌套框形自己的id是最后一项）。带标签的PDF为每个嵌套框在其父框的Div内生成一个Div。图标图片与资源图片的解析方式相同：canvas图片注册表、HTML的resourceImageUrl选项和PDF的resourceBytes提供器。

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => 每个继承字段都从已解析的各节中填入；可选的
//    locale决定接续字符串的语言
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => 对内置的`note`默认值返回undefined；去掉静态默认值

#编号的命题与证明

带numbering的样式为它的框计数，就像LaTeX的amsthm为定理环境计数（postext 1.19起）。每个框印出它的标签和编号，即第一段开头的“定理2.”，围栏的title以括号跟在编号之后：:::callout{type="theorem" title="Bradley–Terry"}以“定理2（Bradley–Terry）.”开头。以标识符打开的框（{#thm:main}）可以作为交叉引用的目标，引用印出“定理2”（:ref{id="thm:main"}），\ref{thm:main}或style=number印出2。

证明就是一个标签不编号、带结束记号的样式：

calloutStyles: [
  { id: 'theorem', numbering: { label: '定理' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: '引理', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: '定义' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: '证明', counter: false, bold: false, italic: true } },
]

逐章排版的书中，计数器接着上一章继续（LayoutContinuation.statementCounters，由continuationAfter填入），全书大纲为每个编号框的锚点给出它的标签（OutlineEntry.numberLabel），所以从另一章引用时也能印出它。

#框内的排版

框用自己的body和lists排版设置内容，其余一切沿用文档的样式：

• 段落采用框的body：字体、字号、行距、颜色、强调颜色、字重、italic、smallCaps、对齐、断词、缩进和段间距。未设置的字段继承bodyText。继承来的强调颜色保留与调色板的关联，所以框内的粗体、斜体和:ref标签与框外一样随colorPalette变化。（postext 1.4及以前，无论主色是什么，框内的粗体都保持#295AA3。）
• 项目符号列表以框的lists（项目符号字符、颜色、字形大小和字重、缩进、间隔、条目间距）覆盖unorderedLists，文字是框的正文。lists.bulletChar或lists.color与文档的设置（unorderedLists）不同时，替换每一层的项目符号或颜色；与之相同或未设置时，每一层保留各自的设置（unorderedLists.levels），所以嵌套的破折号在框内依然保留。
• 编号列表采用lists.indent、gap和itemSpacing；只要样式设置了lists.color，也采用它，即使它就是文档的项目符号颜色；未设置时，编号保持orderedLists.color。（postext 1.4及以前，只有当颜色与unorderedLists.color不同时才会作用到编号上，所以设成同一种颜色不起作用。）编号本身的字体、字号和分隔符来自全局的orderedLists，因为lists只有项目符号字段：框内编号的样式请在那里设置。
• 框内的:::paragraphs使用它们的段落样式，嵌套框中也是如此。段落样式未设置的字段继承文档的bodyText，而不是框的body（也不继承框的斜体或小型大写字母）。
• :::columns组没有自己的样式：每一栏都共用框的正文和列表排版，columnGap设置栏间距。
• 引文块采用框的正文字体、字号和字重（与正文中一样为灰色斜体），以及框的小型大写字母。标题保留标题样式；独立公式保留数学设置。
• 图和表保留文档的题注和表格样式，宽度为框的内宽；它们的常规字重和粗体字重跟随框的body字重。
• 行内标签保留自己的标签样式；em字号按框的正文字号计算。
• :::space以框的正文行为单位计量（它在哪些位置被丢弃，见:::space）。
• 嵌套框完整采用自己的样式；它的span、placement、floatBarrier和snapToGrid被忽略。

#拆分框的标记

框跨栏或跨页拆分时（keepTogether: false，或框比一栏还高），第一部分之后的每一部分都不带标题和图标开始，默认也没有任何提示告诉读者框还在继续。图书或剧本常用的标记可以通过两个选项加上：

• repeatTitle: true在每个接续部分的开头重复标题，后接continuedSuffix，默认为“Key points (cont.)”。重复的标题采用标题样式，所以配合textTransform: 'uppercase'就得到剧本里的“HAMLET (CONT'D)”。图标和标签只留在第一部分。
• continuesMarkerEnabled: true在每个还要接续的部分的最后一行下方、框内，排出continuesMarker：“Continued”，西班牙语文档中为“Continúa”。它使用框的正文字体和字号：除非continuesMarkerItalic为false，否则为斜体；除非continuesMarkerAlign设为'left'或'center'，否则右对齐。标记占用它所结束的那一部分的空间，选择切口时会保证它放得下。

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

结束这一页的部分以“(MORE)”收尾，下一页以“HAMLET (CONT'D)”开始。两者都是分页附属物：在无障碍PDF中它们是artifact，在HTML中对辅助技术隐藏，所以标题只被朗读一次。在VDT中，它们是标记为artifact: true的designOverlay文本块。

#篇

parts属性配置篇章隔页。文档用:::part{number="…" title="…"}容器开启一篇，也就是把一组章节归在一起的“第一篇 基础”那种页面。篇隔页总是独占一页：容器先按配置的奇偶另起新页，把这一页改成单栏页面，正文区域取自parts.margins，再把篇首设计铺满整页；容器的结束标记之后再断一次页，让下一章（按它自己的breakBefore.parity）干净地开始。使用默认的一级标题设置时，得到的就是经典的排法：篇隔页在右页，左页空白，章从下一个右页开始。

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

#篇设计的占位符

设计中的标题占位符集合按篇自身的值解析：{titleText}是容器的title；{number}是原样写出的number；{numberDecimal}、{numberRoman}、{numberRomanLower}、{numberAlpha}、{numberAlphaLower}把它换成别的格式。编号可以按十进制数、罗马数字或中文数字解析，带不带外围的字都行（"IV"、"iv"、"4"、"４"、"四"、"卷四"和"第四卷"得到的{numberDecimal}都是4），其他写法一律解析为''。{partTitle} / {partNumber}、{chapterTitle} / {chapterNumber}（篇之前的那一章）、{pageNumber}、{totalPages}、{bookTotalPages}以及元数据占位符也都可用。{attr.<key>}读取当前章一级标题的属性。

#左页设计

versoDesign装饰篇隔页之后的那一页，条件是那一页没有内容，也就是隔页纸的背面。篇本身从不让这一页空着。breakAfter.parity默认为'any'，所以除非有别的东西提出奇偶要求，结束标记之后的内容就从紧接着的下一页开始：

• 下一章的标题。一级标题默认的breakBefore是'always-odd'；在右页的篇隔页之后，'odd'的效果相同：章移到下一个右页，左页留空，左页设计会绘制出来。
• parts.breakAfter: { enabled: true, parity: 'odd' }。不管下一个标题怎么设置，篇自己要求下一个右页。章可能从任意一侧开始时（breakBefore.parity: 'any'或breakBefore.enabled: false）用这种写法。

两者都没有时，章从左页开始，不绘制左页设计。breakAfter.enabled: false时，内容就接着排在篇隔页上。左页采用篇的调色板，所以容器上的palette="band=#…"也会给它换色。

parts: {
  breakBefore: { parity: 'odd' },
  breakAfter: { enabled: true, parity: 'odd' },   // 总会留出一张可以绘制的空白左页
  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' } },
    }],
  },
}

结束一章的篇。在逐章排版的书中（沙盒、buildBundle），一个:::part容器可以单独成为一章，也可以是某一章的结尾。这时篇隔页就是该章的最后一页，篇还欠着的事由下一章接手：它在第一个块之前执行breakAfter，并在自己的第一页空着时在上面绘制versoDesign。排出的页面与整本书放在一个文档里时完全一样。结束标记之后只能跟不放置任何东西的指令（:::numbering、:::space）；其他任何东西都算这一章的内容，于是由这一章自己断页。紧跟在篇后面的空章自成一页，那一页就是左页。自行逐章排版的宿主程序可以从continuationAfter()得到这一信息：以篇结尾的章会报告afterPartPage: true，把它传进下一章的continuation即可。

#:::part容器

:::part{number="…" title="…"}一行开启一篇，单独的:::结束它；两个属性都可省略（默认为''）。中间的各块（通常是章节列表）以bodyStyle排在篇隔页的单栏里，从margins.top开始；正文超出一页时，在普通页面上接排。这一页被归为role: 'part'（VDTPage.partInfo带有编号和标题），所以页眉页脚元素可以用pages: 'part' / pages: 'body'专门针对它或跳过它；PDF后端会把篇加到书签大纲中，位于它的各章之上。正文为空（:::part{…}后面直接是:::）是常见情况，照样生成这一页，相邻的两篇从不共用一页。嵌套在另一篇中的:::part会并入外层的篇。

第三个属性palette="<id>=<hex>[, <id>=<hex>…]"给篇指定自己的颜色：在篇隔页以及其后直到下一篇的每一页上，凡是链接到这些调色板id的设计颜色（页眉、页脚、章首色带、篇设计和左页设计），都改用篇给出的值，而不用文档调色板的值。书中各部分就是这样在不另做设计的情况下，给角标、书眉圆点和章首色带换色的：:::part{number="II" title="…" palette="band=#f6c297"}。正文流也随之变化：在这些页面上，凡是等于某个被覆盖条目基准值的流颜色，包括标题，粗体、斜体和引用的颜色，项目符号和列表编号，题注标签和题注色条，表格的文字、线条和填充（表头、表体、斑马纹行以及单元格自己的填充），标注框（背景、边框、色条、标题）和行内标签（填充、轮廓和文字），都改用篇的值；因此把headings.levels[1].color链接到band，每个部分的标题就会用各自的颜色排出。行内色块保留其中写明的颜色。各组之间用逗号、分号或空格分隔，id和颜色之间用=或:连接，#可以省略。篇在结束标记之后继续生效：{partTitle}、{partNumber}和调色板随正文流进入其后的各章，并通过continuationAfter()报告的continuation.part进入单独排版的章，所以一个部分的第二章在书眉中显示该部分的方式与第一章完全相同。

两个调色板条目可以有相同的基准值，而在篇中取不同的值：篇只覆盖其中一个，或给两者不同的颜色。单看数值无法判断某个流颜色来自哪个条目，所以流中的每个颜色都会与可能产生它的设置逐一对应，并取这些设置所链接的值。下面这些是区分开的：

• 一个块的文字颜色：文字颜色，粗体、斜体和引用的颜色，列表标记（项目符号或编号）以及编号后的分隔符。假设bodyText.color链接到ink、bodyText.boldColor链接到accent，两者都是#1a1a1a，那么带palette="accent=#b8413d"的篇会给粗体片段换色而保留正文颜色；如果链接到accent的是unorderedLists.color，它就给项目符号换色而保留列表项的文字；
• 每一级标题，以及每个设了颜色的标题样式；
• 目录行的文字、编号，以及它的页码和副标题；
• 每个标注框样式中的填充（背景、色条、标签页签）、边框、线条（标记和标签的线条）和文字（标题、图标、标记字形、标签）；
• 每个表格样式、行内标签样式和题注样式的每一种颜色。具名表格样式与tableStyle分开，资源类型的题注样式与captionStyle分开。单元格自己的填充按它自己的链接处理。

仍有一种情况按数值判断：不同位置的设置给一个块设定同一种颜色。例如bodyText.color、bodyText.blockquote.color、段落样式的color和标注框样式的body.color都设定块的文字颜色。当其中两个链接到基准值相同的条目，而篇把它们区分开时，颜色取覆盖值（两个都被覆盖时取最后写的那个）。遇到这种情况，请给这些条目各自不同的基准值。

const resolved = resolvePartsConfig(config.parts, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => margins从页面补全，bodyStyle取自正文和列表配置
 
const minimal = stripPartsDefaults(config.parts);
// => 只剩静态默认值时为undefined

#标题样式

headingStyles属性声明具名样式，文档用# Title {style="<id>"}把它应用到标题上。样式做两件事。一是覆盖标题所在级别的字体样式、设计和编号，即级别条目中除level之外的所有字段（字体、字号、颜色、breakBefore、span、advancedDesign、textTransform、hidden、numberingTemplate…）；二是管理标题开启的区段：从这个标题到下一个同级或更高级标题之间的页面，采用该样式的书眉、页面几何、正文字体样式和调色板。一本书的前置部分（序言排成一个宽栏，罗马数字页码，蓝色色带）就是这样放进一本双栏、十进制编号的手册里，而无须第二套配置。

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: [/* 色带、`{titleText}` */] } },
      header: { elements: [/* 页码 | 线条 | `{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"}

区段在下一个同级或更高级标题处结束：带样式的标题之后出现不带样式的#，就回到文档的书眉和页面几何；带样式的标题则开启它自己的区段。区段为凑奇偶留下的空白页属于该区段，这一点与章标题相同。

分页符不能代替标题自身的断页。样式继承所在级别的breakBefore（一级的默认值是{ enabled: true, parity: 'always-odd' }），标题无论出现在哪里都会执行它，紧跟在:::pagebreak之后也一样。分页符开启新页，标题随后仍然要求落在跨页中它那一侧。使用parity: 'odd'时，如果分页落在左页，后面会跟一张空白页，标题从下一个右页开始。使用'always-odd'时还会多出分隔空白页，而分页符不起任何作用，因为标题本来就会开启那一页。如果一个样式要从手动分页开启的那一页开始，比如扉页之后的目录页，就关掉它自己的断页：

headingStyles: [
  // 从正文安排的位置开始：即前面的`:::pagebreak`开启的那一页。
  { id: 'contents', numbered: false, toc: false, breakBefore: { enabled: false } },
],

如果想独占一页又不指定左右，改用breakBefore: { parity: 'any' }，并去掉:::pagebreak。

页面属于哪个区段。书眉和调色板按页选择，而不是按标题选择。一页采用该页上最后一次区段切换之后生效的区段：一个区段结束、另一个区段在同一页开始时（比如词典中两个很短的字母部分），这一页使用第二个区段的书眉和调色板；带样式的区段在页中遇到不带样式的标题而结束时，这一页回到文档的设置。{chapterTitle}遵循同样的规则：两章交汇的页面显示后一章的标题。空白页遵循章标题的规则：为凑奇偶留的空白页（blankForParity）属于其后开启的区段，'always-odd' / 'always-even'断页添加的分隔页（blankForForce）属于其前的区段。篇隔页会结束当前打开的区段。

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

两个字母都从第1页开始，所以第1页采用B区段的书眉：样式页眉里设置的书口索引标签在这一页上显示“B”，没有哪一页带“A”的标签。如果每个区段都需要自己的标签，就给每个区段单独一页（breakBefore）。 下面是排在编号章之后、用字母编号的附录，以及一张目录和PDF书签都列出、但页面上不印标题的献词页：

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

一级设为numberingTemplate: '{1}.'时，各章印作1.、2.…，附录印作Appendix A和Appendix B。献词开启自己的一页（按所在级别的breakBefore），只印出它的段落，但仍以Dedication出现在:::toc、{chapterTitle}书眉和PDF书签大纲中；给样式加上toc: false，就能把它排除在目录之外。章中间以一级标题排的图版或地图，需要的恰好与献词相反：使用runningChapter: false的样式（通常同时设numbered: false和toc: false），书眉就会保持在被它打断的那一章上。

const resolved = resolveHeadingStylesConfig(config.headingStyles, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => 级别覆盖已规范化，margins从页面补全，bodyStyle取自正文
 
const minimal = stripHeadingStylesDefaults(config.headingStyles);
// => 没有剩下任何样式时为undefined