配置：列表与数学公式

#无序列表

unorderedLists属性控制项目符号列表（-、*、+）和GFM任务列表（- [ ]、- [x]）的渲染方式。最多支持五层嵌套。

#无序列表默认值

#任务列表扩展

GFM任务项（- [ ] …、- [x] …）按无序列表项渲染，用复选框代替项目符号。方框由引擎自己绘制：一个方形轮廓，任务完成时加一个勾。它不向任何字体索取字形，所以在每台机器上，在画布、PDF、HTML和EPUB里都一样，辅助技术读出☐或☑。方框的边长是标记字号（bulletFontSize，或该层级的fontSize）的0.6 em，这也是它在gap之前所占的宽度；标记与正文同字号时，方框立在列表项首行的基线上。线条粗细随标记的fontWeight，颜色随标记的color。以下字段只作用于任务项：

#无序列表的逐层覆盖

levels中的每一项针对一个层级（1–5），可以覆盖以下任意字段：

缩进级联。第1层总是从通用的indent值开始（默认0 em，项目符号贴住栏的边缘）。对第2–5层，如果不设indent，引擎把项目符号放在上一层文字的起点（上一层缩进 + 项目符号宽度 + gap）。在某一层显式设置indent，就会打断级联，把这一层固定在你想要的任何位置。

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#有序列表

orderedLists属性控制编号列表（1.、2)等）。最多支持五层嵌套，每一层可以使用不同的编号格式。

#有序列表默认值

#有序列表的逐层覆盖

levels中的每一项可以覆盖numberFormat、prefix、separator、fontFamily、fontSize、color、fontWeight、italic、indent、verticalOffset以及分隔符样式（separatorFontFamily、separatorFontWeight、separatorItalic、separatorColor、separatorGap），缩进级联规则与无序列表相同。某一层的分隔符样式沿用该层自己的编号样式，除非给出了整个列表的分隔符设置。

右对齐。排版流程会测量一个连续段中格式化后最宽的编号，并据此缩进该段的所有列表项，使编号的右边缘对齐。十项的列表渲染为1.–10.时，一位数编号的右侧会补齐，使分隔符保持在同一列。

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

得到的是经典的混合嵌套：

1. First item
   a. Sub-item
      i) Deep note
   b. Sub-item
2. Second item

中文公文的层次序数（GB/T 15834—2011，附录B.3）共五层，依次为“一、”“（一）”“1.”“（1）”“①”：

orderedLists: {
  levels: [
    { level: 1, numberFormat: 'simp-chinese-informal', separator: '、' },
    { level: 2, numberFormat: 'simp-chinese-informal', prefix: '（', separator: '）' },
    { level: 3, numberFormat: 'arabic', separator: '.' },
    { level: 4, numberFormat: 'arabic', prefix: '（', separator: '）' },
    { level: 5, numberFormat: 'circled-decimal', separator: '' },
  ],
}

#数学公式

math属性控制如何解析和渲染写在$...$（行内）和$$...$$（独立）定界符之间的LaTeX公式。底层引擎是MathJax（mathjax-full包），以SVG模式输出，在Canvas上栅格化，在PDF中以可缩放的字形嵌入。

interface MathConfig {
  enabled?: boolean;        // 渲染LaTeX。为false时，公式片段按原样输出TeX源码。
  fontSizeScale?: number;   // × 周围文字的字号（独立公式以正文字号为准）。
  color?: ColorValue;       // 公式颜色；省略时沿用正文颜色。
  marginTop?: Dimension;    // 独立公式块上方的间距。
  marginBottom?: Dimension; // 下方的最小间距；对齐基线网格时可能变大。
  indentAfterDisplay?: boolean; // 独立公式之后的段落首行缩进。
  keepWithLeadIn?: boolean; // 让独立公式与引出它的那一行在一起。
  equationNumbering?: {      // 为带\label的独立公式编号。
    enabled?: boolean;           // 默认true
    numberingTemplate?: string;  // '{n}'；'{h1}.{n}'按章编号
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})'：公式和\eqref印出的形式
  };
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

公式大小，postext 1.5起有变化。MathJax以ex给出公式的框，而它的TeX字体的1 ex等于0.442 em。postext 1.4及以前，引擎把它当作半个em，所以每个公式都比bodyText.fontSize × fontSizeScale大约13%。现在公式按文档说明的大小排出，含公式的行和页面会重新排版。为1.4用代码写的配置，可以把它原样传给postext/bundle中的pinLegacyMathSize一次，保留1.4的公式大小：

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // 公式及独立公式周围的间距，按1.4的排法

1.5的其他规则变化也可能让页面移动：标题的断行、行内图周围的间距（正文中和框内）、标题的行内标记、首字下沉的大小、冒号行之下为它引出的列表保留的空间、框的切口在段落或列表项中留下的行数、破折号之后的断行、齐左文字的断行、标题下段落的拆分、复合词连字符之后的断行，以及:::paragraphs容器下方的间距。migrateConfig与配置所排的markdown一起运行一次，就会固定这段文字需要的那些规则，公式大小也包括在内（见postext 1.4及以前写出的文件包）：

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // 标题断行、公式、行内间距、标题标记、首字下沉、冒号行、框的切口、破折号断行、复合词断行、齐左断行、标题下的拆分和容器间距，按1.4的排法

这样能挡住这些规则变化会造成的移动，但不能保住1.4的每一页。1.5还修正了排版错误，而修正没有固定开关：旧配置和新配置一样会得到修正，所以受影响的页面仍可能移动。其中包括：没有自己版面设计的通栏标题按整页宽度测量，并用所在层级的行距排；标题版面设计中，首字下沉的基线下面不再预留空间；首字下沉采用该部分的调色板颜色，即使设计文字的overflow不是'wrap'也会排出，此时文字折行；框内的段落按测量时的字距绘制；拆分的框在每个片段上都保留图标栏；框内某一行如果要把空格拉宽到3倍以上，就改为齐左，与正文一样；松散段落的调节手段不会让两端对齐的行宽于maxWordSpacing所允许的宽度；浮动的框保留比浮动体间距更大的marginBottom（在顶部区域）或marginTop（在底部区域）；带字距的居中或右对齐设计文字（书眉、章首页标题）按字母定位，不计最后一个字母之后的字距；在通栏章首页之下，第二栏开头的文字从紧接章首页下方的文字所在位置开始，章首页后面跟着标题时也是如此；在会把连续圆点的字偶间距拉开的字体中，目录的引导点也停在页码之前；书眉按标题的原文读取，标题某一行在连字符或破折号之后结束、或结束在因宽度而切开的单词内部时，不留空格（MEDIOAMBIENTALES，而不是MEDIOAMBIENTALE S），标题版面设计的{titleText}也同样读取（thousand-colour，而不是thousand- colour）；锚定在标题版面设计色带底部或中部的文字，会让色带保持足够的高度来容纳它，不再压到标题上方的文字上；比所在行更宽、在自带的连字符旁被切开的单词，从这个连字符之后切开，不再加第二个连字符；嵌套在另一列表中的列表之后的那一项，用它自己所在列表的itemSpacing，而不是嵌套列表的；因比所在行更宽而被切开的单词，其余部分保留自己的断点，所以网址继续在连接处断开，复合词继续在连字符处断开，而不是按词典的音节断开。

pinLegacyMathSize把缩放比例乘以1.1312（0.5 ÷ 0.442），并把以em计的独立公式外边距除以同一系数。对含独立公式的书，只改缩放比例不够：它们的外边距是以公式自身大小计的长度，会同样增大13%，把下面的文字往下推。按默认外边距写出来，这三个值是：

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // 公式与1.4排出的一样大，周围留出1.4留的间距

对于已保存的配置，引擎能识别出来并替你完成这一步：openBundle / readBundle处理1.5之前写出的.postext文件包（见postext 1.4及以前写出的文件包），沙盒处理当时保存的书、工作副本和postext-config.json文件（见沙盒 → 持久化）。它们都经过migrateConfig读取，由它固定公式大小（pinLegacyMathSize）：fontSizeScale变为保存的缩放比例（未设置时为1）× 1.1312，以em或rem计的独立公式外边距（以公式自身大小计的长度）除以同一系数，所以独立公式周围的间距保持1.4的样子（默认的0.8 em变为0.7072 em）。以页面单位（pt、mm……）计的外边距保持不变，enabled: false的配置或书中没有$的配置也保持不变。这样旧书就按1.4的方式排版，它的math部分显示实际使用的大小。要按现在的大小排这样的书，就把这些值重置：在沙盒中是公式 → 缩放比例、独立公式上边距和独立公式下边距，在代码中是：

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // 现在的大小和外边距

带编号的公式。带编号的独立公式占满它的行长（所在的栏，或所在标注框的内宽）：公式居中，编号右对齐排在公式所在的行上，align中每个带编号的行都是如此。编号来自\label{eq:x}（postext 1.19起）：带标签的公式，以及align、gather、alignat、flalign或eqnarray中带标签的行，按阅读顺序依equationNumbering编号，除非该行写了\nonumber或\notag。equation之类的环境本身不编号：没有标签的公式就没有编号。\tag{…}把你给的标签加上括号打印出来，\tag*{…}按原样打印；两者都不参与计数，与它并列的\label为它命名。比行长更宽的带编号公式向右溢出，与其他独立公式一样。（postext 1.4及以前，带\tag的公式根本不会绘制；1.18及以前，只有\tag能为公式编号。）

正文中的\eqref{eq:x}按format印出编号(3)，\ref{eq:x}印出不带括号的编号；:ref{id="eq:x"}和@eq:x也是如此（见交叉引用）。在公式内部，\eqref把编号作为文字印出。逐章排版的书中，计数器接着上一章继续：continuationAfter通过LayoutContinuation.statementCounters（equation）把它带过去，全书大纲为每个标签给出编号（OutlineEntry.numberLabel），所以对另一章中公式的引用也能印出编号。

math: {
  equationNumbering: { numberingTemplate: '{h1}.{n}', resetOn: 'h1' }, // (1.1)、(1.2)……(2.1)
}

解析函数和精简函数与其他部分一致：

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

#启动公式引擎

MathJax按需加载，不随引擎的其他部分一起加载。在主线程上排版时，要在构建含公式的文档之前启动它：

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // 只加载一次MathJax；之后的调用立即完成
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• 引擎运行之前，公式是占位符。每个公式排成一个估计大小的灰色框。如果在从未调用initMathEngine()的情况下排版含公式的文档，控制台会显示一条警告说明这一点。
• 排版工作线程会替你启动它。postext/worker中的构建在markdown包含$时会自行调用initMathEngine()。
• 先排版，就绪后再排一次。isMathReady()告诉你引擎是否在运行。onMathReady(fn)在引擎就绪后调用fn一次（已经就绪则立即调用），并返回一个取消这次调用的函数。编辑器可以先显示占位符，等MathJax加载完再重新排版；initMathEngine()加载期间不会打印警告。
• 失败。MathJax无法加载时，initMathEngine()返回的Promise会被拒绝，之后再次调用会重试。
• 任何打包工具、Node或CDN。MathJax作为一个预先打包的模块随包发布（压缩前约1.8 MB，只由initMathEngine获取）。直接写import { initMathEngine } from 'https://esm.sh/postext'就能用，不需要?bundle。mathjax-full包只在构建postext时需要，所以安装postext不会安装它。MathJax及其打包的mhchem解析器采用Apache-2.0许可证：它们的声明和许可证文本随模块一起发布，位于dist/math/THIRD_PARTY_LICENSES.txt。
• 一个页面一个引擎。同一JavaScript realm中所有导入postext的代码共享引擎及其已渲染公式的缓存（见同一页面共享的全局状态）。

文档一侧的语法（$...$、$$...$$、转义美元符号本身）见文档格式。