Quarto 中文书稿 docx 模板与滤镜

scripts/quarto-docx 目录索引：Word 参考文档 + Lua 滤镜

Quarto

docx

Lua

书稿

Author

Harness 技术文档

Published

September 29, 2026

本目录是一套可整体复制到其他 Quarto 中文书稿 / 报告 项目的配置资产：用 Word reference-doc + Lua 滤镜，把表题/图题拆出 1×1 浮层表，并按中文显示宽度排表列。编号滤镜按项目类型二选一：网站用手写前缀 图2- 的收紧滤镜，book 用 图3-1 改写滤镜。横向页只属于 book 剖面。

长文（前提条件、必备 YAML、验收）见 Quarto 中文书稿 docx：图题、表题与交叉引用滤镜。

与 templates/ 的区别：这里是要拷进业务仓的源文件（与 Docker Selenium 同类）；templates/ 只放消费这些源的微型示例。业务仓落到 lua/ 与 template/reference-doc.docx（Pandoc 参考文档目录名），与 harness 源路径无关。

经验来源：report-tech2026 第2/5章书稿 docx。

可交付文件

本目录文件	落到业务仓库	说明
`lua/linebreak.lua`	`lua/linebreak.lua`	`<br>` → 软换行；不要 `post-render`；两个剖面都要
`lua/crossref-tight-num.lua`	`lua/crossref-tight-num.lua`	网站：`图2- 13` → `图2-13`；必须 `post-render`
`lua/crossref-book-num.lua`	`lua/crossref-book-num.lua`	book：`图 3.1` → `图3-1`；必须 `post-render`；不要与上一行同时挂
`lua/docx-table-caption.lua`	`lua/docx-table-caption.lua`	拆 1×1 表壳；认 `图N-` 与 `图N-M` / `图N.M`；仅 docx；`post-render`
`lua/docx-table-layout.lua`	`lua/docx-table-layout.lua`	列宽与表头五号加粗；仅 docx；排在 caption 之后
`lua/docx-landscape.lua`	`lua/docx-landscape.lua`	book 可选：class `landscape` 独占一页横向 A4；`at: pre-quarto`
`reference-doc.docx`	`template/reference-doc.docx`	含「表题」「图题」、Table `firstRow` 五号加粗。页边距与纸型仍由业务仓自己的参考文档决定
`filters.yml`	合并进网站 docx YAML	网站滤镜顺序，勿整文件覆盖已有 `filters`
`filters-book.yml`	合并进 book 的 docx profile	book 滤镜顺序；不要和 `filters.yml` 的编号滤镜叠用

原理笔记（从业务仓 topic 抽出，路径已改成本目录）：

从 harness 安装到业务项目

在 harness 仓库根：

.\scripts\powershell\Install-Harness.ps1 `
  -InstallProfile quarto-docx `
  -ProjectRoot "D:\path\to\your-repo"

网站剖面得到四个网站滤镜、template/reference-doc.docx、_quarto.harness-docx-filters.yml。book 剖面改用 -InstallProfile quarto-docx-book，得到 book 编号滤镜、横向页滤镜和 _quarto.harness-docx-book-filters.yml，不包含 crossref-tight-num.lua。两个剖面都要把滤镜片段与 format.docx.reference-doc 手工合并进该书自己的 YAML。参数见 Install-Harness 指南。

最小 YAML：网站（拷贝后必须改章号）

crossref:
  title-delim: ""
  fig-title: "图2-"
  fig-prefix: "图2-"
  tbl-title: "表2-"
  tbl-prefix: "表2-"
filters:
  - lua/linebreak.lua
  - path: lua/crossref-tight-num.lua
    at: post-render
  - path: lua/docx-table-caption.lua
    at: post-render
  - path: lua/docx-table-layout.lua
    at: post-render
format:
  docx:
    reference-doc: template/reference-doc.docx

图2- / 表2- 换成该章号。不要改成 图 2-（前缀里不要空格）。源文件正文写 见 @fig-id（@ 两侧留空格）。

最小 YAML：book

前缀只写「图」「表」。章号由 Quarto book 的 章.序号 生成，再由 crossref-book-num.lua 收成 图3-1。不要把网站的 图2- 写进 book 前缀。

crossref:
  title-delim: ""
  fig-title: "图"
  fig-prefix: "图"
  tbl-title: "表"
  tbl-prefix: "表"
filters:
  - path: lua/docx-landscape.lua
    at: pre-quarto
  - lua/linebreak.lua
  - path: lua/crossref-book-num.lua
    at: post-render
  - path: lua/docx-table-caption.lua
    at: post-render
  - path: lua/docx-table-layout.lua
    at: post-render
format:
  docx:
    reference-doc: template/reference-doc.docx

横向页在浮层及其表注外面包一层 ::: {.landscape}，或只在 chunk 上写 #| classes: landscape。不要两处同时写。页脚关系默认 rId14；参考文档若不是这个 id，在 YAML 里设 docx-landscape-footer。纸型与页边距仍用业务仓自己的 reference-doc，本包不改页面设置。

本地验证沙盒

晋升或升级 Quarto 前，在仓库内跑标准验收（不通过 Install-Harness 分发）：

cd scripts\quarto-docx\test
.\scripts\run-check-all.ps1

规程：test/quarto-docx-test-guide.md · 总览：资产效果展示与标准验收

版本记录： 底线 Quarto 1.8+。文档于 2026-09-08 记载在 1.8.26 验证；2026-09-29 本机升级到 1.10.18 后重跑 sync-mirror.ps1 与 run-check-all.ps1，L0 与 L1 结构门禁通过，列宽与五号表头未做 Word 目视。明细见长文验收记录。

不要拷走的东西

业务仓的 chpt*.R、年鉴数据、ragg_png / theme_tech（出图问题，不是这套滤镜；见 scripts/book-plot/）
本目录 notes/、test/output/ 不必拷进业务仓；业务仓用自己的 topic 或链回 harness 文档即可