# 文档排版、目录、分页、编号与脚注 以下功能沿用 HTML → DOCX 转换流程，CLI、DSH 项目模式和附件模式共用。无需增加命令行参数。完整例子见 [分页编号与脚注](../fixtures/分页编号与脚注.md)。 ## 统一文档配置 在文档第一个内容块放一行 JSON 配置；只允许一条，不放进引用、列表、脚注或代码块。未指定时保留原有中文排版，不新增目录、标题、页眉或页码。 ```markdown # 项目概况 ``` 预设为 `chinese-report`（中文报告，正文宋体 12pt、标题黑体、1.5 倍行距、首行两字符）或 `technical`（技术文档，微软雅黑 11pt、1.3 倍行距、首行不缩进、标题左对齐）。均为 A4，默认四边 25mm。选择预设后再应用覆盖参数： | 参数 | 含义与范围 | | --- | --- | | `font` / `headingFont` | 正文/标题字体名称，非空；字体需安装在阅读器所在系统 | | `fontSize` | 正文和表格字号，8～24pt；代码、题注、脚注保留各自字号 | | `lineSpacing` | 正文行距倍数，1～3；标题、代码、脚注有独立行距 | | `firstLineIndent` | 正文首行缩进字符数，0～4；不影响列表、图片、表格 | | `margins` | `top`、`bottom`、`left`、`right`，各 10～50mm，可只覆盖部分边距 | | `title` | 文档开头显示的标题及文件标题属性，不参加标题编号和目录 | | `header` / `footer` | 每页的页眉/页脚短文字，独立于文档标题，使用 10pt 单倍行距 | | `toc` / `tocDepth` | 是否生成目录（默认 false）；收录标题级别 1～6，默认 3 | | `pageNumbers` | 是否在页脚显示“第 N 页 / 共 M 页”，默认 false | | `headingNumbering` | 是否给顶层 Markdown 标题添加原生多级编号，默认 false | 文字参数最长 256 字符，不接受换行等控制字符。未知字段、类型或范围错误会整条回退默认配置，保留指令源文本并报告 `LAYOUT_DIRECTIVE_INVALID`；严格模式拒绝发布。 ```markdown ``` 目录使用 Word 原生 TOC 域，正文从目录后的新页开始。页码使用 PAGE/NUMPAGES 域，包括目录页，跨分节连续。文档请求打开时更新域，但首次显示可能尚无目录内容；请在 Word/WPS 中更新整个目录和全部域，再检查页码。编辑、移动图表后，前向引用可能需要再次更新。不同阅读器分页不要求一致，目录必须与当前阅读器的实际页面一致。 ## 标题编号、自动题注与交叉引用 `headingNumbering: true` 为文档顶层的一至六级标题生成 `1 / 1.1 / 1.1.1` 多级编号，与正文列表互不干扰。源标题不要重复手写编号，建议从一级开始且不跳级。引用或列表内的标题不参与自动编号。 自动题注扩展现有 `word:caption`，紧邻对应图片或表格；`id` 在整个文档中唯一，规则与命名列表相同。图与表分别从 1 开始，使用原生 SEQ 域。题注正文只写名称，不重复写“表 1”： ```markdown 见[表号](#ref:results)。 验收结果 | 项目 | 结果 | | --- | --- | | 域更新 | 通过 | ``` `kind=figure` 用于图片。`[占位文字](#ref:id)` 生成带链接的 REF 域，显示“图 N”或“表 N”，支持前向引用。不存在的目标保留占位文字并报告 `LINK_UNAVAILABLE`；重复 id、类型不匹配或无相邻图表报告 `LAYOUT_DIRECTIVE_INVALID`，保留题注正文。旧的无参数 `word:caption` 仍仅处理分页，不自动编号。 ## 宽表横向分节 在文档顶层显式划定横向范围，将题注与表格一起放入；结束后切回纵向。每次方向切换新起一页，表格按该节实际可用宽度排版，页眉页脚与页码继续生效。 ```markdown | 字段一 | 字段二 | 字段三 | | --- | --- | --- | | 内容 | 内容 | 内容 | 恢复纵向的正文。 ``` 不写 `portrait` 时后续内容继续使用横向。重复相同方向不产生额外分节；末尾空的方向切换不生成空白页。表格不会自动判断并切换方向。若正文一开始就是横向，自动生成的文档标题和目录仍放在独立的纵向前置分节中，正文从下一页开始，页码保持连续；没有标题和目录时不增加前置页。 ## 表格列宽与跨页 默认根据各列文本长度估算列宽：给短编号、状态留出基本空间，为长说明分配更多空间。列宽总和始终等于当前容器可用宽度，仍保留 Markdown 的显式对齐、重复表头和单元格图片宽度限制。 需要确定比例时，在表格前单独放一行指令： ```markdown | 编号 | 状态 | 说明 | | --- | --- | --- | | A-01 | 完成 | 较长的说明文字 | ``` 每个比例必须大于 0、不超过 1000，数量与列数相同。计算后列宽小于 480 twips（24pt）时改用自动列宽并报告降级。该最小值仅限制显式比例，极多列的自动表格仍需人工检查或拆分。 短文本行（估计每个单元格不超过 8 行）设置“不跨页拆行”；长行、含图片或公式的行允许跨页，以免超高内容无法正常分页。这是近似布局策略，不是对 Word 页数的预测。 相邻独立表格之间会插入小间隔，避免阅读器把两张表合并。表格使用固定列宽布局，文字可在列内换行。超宽表格不会自动切换横向页面。 ## 标题、图题和代码分页 - 标题设置“与下段同页”和“段中不分页”。 - 正文启用孤行控制。 - 代码块按容器宽度估计换行，预计不超过 12 行时尽量保持同页；更长代码块允许分页。 - 不给所有段落设置保持同页，避免长文档产生过多空白。 图题或表题必须显式标记，不根据“图 1”等文字猜测： ```markdown 图 1：处理流程 ![流程](assets/flow.png) ``` 指令作用于紧随其后的普通段落；该段必须紧邻图片或表格，可放在前面或后面。图片在 Markdown 中必须独占段落。题注前后都存在图表时，优先关联前面的图表。这个无参数形式不自动生成序号；需要自动编号时使用上面的 `kind` 与 `id`。 图片加题注如果本身比一页还高，阅读器仍可能拆开，应缩小图片或缩短题注。分页最终由 Word/WPS/LibreOffice 和字体决定。 ## 编号：默认不变，显式选择续接 没有指令时：独立 Markdown 列表使用各自首项起点；父列表退出子列表后续号；同一列表后续项手写数字不作为强制跳号。章节标题编号与正文编号互不关联，标题自动编号由文档配置单独开启。 ### 命名列表 ```markdown 3. 第三步。 4. 第四步。 插入说明文字。 1. 自动继续为第五步。 ``` - `id` 为 1～64 位，以英文字母开头，后续可用字母、数字、下划线、连字符。 - `restart` 创建新的编号实例；省略动作等价于 `restart`。 - `continue` 复用作用域中最近一次同名列表，要求层级与缩进相同。默认作用域是整个文档，可以跨章节续接。 - 续接列表用 `1.` 开头。Markdown 解析器不保留默认起点 1 的显式与隐式区别；其他起点会与 `continue` 冲突并报告降级，按源起点新建实例。 - 没有可续接实例时报告 `LIST_CONTINUATION_UNAVAILABLE`，按源 Markdown 新建列表；严格模式拒绝发布。 - 命名列表与未命名列表不共享编号。 ### 按章节自动续接、重启 ```markdown ## 第一节 1. 第一步。 插入说明。 1. 自动继续为第二步。 ### 小节 1. 自动继续为第三步。 ## 第二节 1. 重新从第一步开始。 ``` `section=1`～`section=6` 指定标题级别。遇到该级或更高级标题时重置作用域；更低级标题不重置。节内未命名的顶层有序列表自动续接；引用、子列表不参与自动续接。显式非 1 起点创建新序列，后续自动续接该序列。 此模式下命名列表也限定在当前节内，不能跨节 `continue`。`source` 退出章节模式，恢复独立列表；每次切换策略会重置自动序列。 ## Word 原生脚注 ```markdown 正文[^note]，再次引用[^note]。 [^note]: 支持 **加粗**、链接和 $x^2$ 等行内公式。 第二段缩进四个空格，仍属于同一条脚注。 ``` 首处引用创建 Word 原生脚注，重复引用使用指向首处书签的 `NOTEREF` 域，缓存结果为上标；文档设置了打开时更新域。编辑引用顺序后，应在阅读器中更新域。不同阅读器更新域的行为可能不同。 支持多段内容、常见行内格式、链接、数学公式及图片。脚注中的表格降级为按行顺序排列的单元格段落，报告 `FOOTNOTE_TABLE_FLATTENED`；暂不支持嵌套脚注引用/定义，保留文字并报告 `FOOTNOTE_NESTED`。 - 未定义引用：保留记法，报告 `FOOTNOTE_UNDEFINED`，严格模式失败。 - 重复定义：使用第一条，重复正文保留并报告 `FOOTNOTE_DUPLICATE`，严格模式失败。 - 未引用定义：保留在正文，报告信息级 `FOOTNOTE_UNUSED`，不阻止严格导出。 - 每次转换最多 1000 个不同的脚注定义，仍受总 Markdown 字节数、输出和任务超时限制。 - `^[行内脚注]` 简写未启用，请使用命名脚注。 ## 指令范围与错误 `` 必须独占一行；表格、列表、题注指令作用于同一容器中紧随其后的对应块。章节策略指令只允许文档顶层。脚注内的布局指令不执行。 不认识的指令、错误参数或放错位置，会保留源文本并报告 `LAYOUT_DIRECTIVE_INVALID`。代码块中的指令按代码显示，不执行。这里的有限指令解析不启用任意 HTML。 ## 阅读器验收 回归样例：[长文档排版验收](../fixtures/长文档排版验收.md)、[分页编号与脚注](../fixtures/分页编号与脚注.md)。实际阅读器结果和复现步骤见 [Word/WPS 验收记录](word-acceptance.md)。结构测试不能代替真实阅读器的分页与域更新验收。