/md2word

配置架构参考

本文档提供 md2word 配置系统的快速参考。

配置概述

md2word 使用 YAML 格式的配置文件来控制 Word 文档的格式化输出。配置采用层级结构，支持以下顶级分组：

配置分组

页面设置 (page)

page:
  orientation: portrait    # 页面方向: portrait(纵向,默认) / landscape(横向)
  width: 21.0              # 纸张宽度 (cm)
  height: 29.7             # 纸张高度 (cm)
  margin_top: 2.54         # 上边距 (cm)
  margin_bottom: 2.54      # 下边距 (cm)
  margin_left: 3.18        # 左边距 (cm)
  margin_right: 3.18       # 右边距 (cm)

字体设置 (fonts)

fonts:
  default:
    name: "仿宋_GB2312"    # 中文字体名称
    ascii: "Times New Roman"  # 英文字体名称
    size: 12               # 字号 (pt)
    color: "#000000"       # 字体颜色 (十六进制)

标题格式 (titles)

titles:
  level1:
    size: 15               # 字号 (pt)
    bold: true             # 是否加粗
    align: "center"        # 对齐方式 (left/center/right/justify)
    space_before: 6        # 段前间距 (pt)
    space_after: 6         # 段后间距 (pt)
    indent: 0              # 首行缩进 (pt)
  level2:                  # 二级标题配置
  level3:                  # 三级标题配置
  level4:                  # 四级标题配置

标题分页 (pagination)

pagination:
  page_break_before_headings:
    - "本章小结"
    - "动手练习"

列表项与 Markdown 标题去除首尾空白后的完整文字精确匹配，支持 # 至 #### 标题层级；普通正文、HTML 表题、代码块和“本章小结与展望”等包含或近似文字不会触发。命中时只在标题段自身写入 Word 原生 w:pageBreakBefore，不插入空段、w:br type="page" 或新 section，因此标题本就在页首时不会多造空白页，原有字号、粗体、缩进和段前段后保持不变。

book-publish 默认配置上述两个标题，单章与 --book 模式均生效；其他内置预设、fallback、配置模板和模板提取基底默认空列表。自定义配置设为空列表即可完全关闭。

段落格式 (paragraph)

paragraph:
  line_spacing: 1.5        # 行距倍数
  first_line_indent: 24    # 首行缩进 (pt)
  align: "justify"         # 对齐方式

页码设置 (page_number)

page_number:
  enabled: true            # 是否启用页码
  format: "1/x"            # 格式 ("1", "x", "1/x")
  font: "Times New Roman"  # 字体
  size: 10.5               # 字号 (pt)
  position: "center"       # 位置 (left/center/right)

表格格式 (table)

table:
  border_enabled: true     # 是否显示边框
  border_color: "#000000"  # 边框颜色
  border_width: 4          # 边框宽度
  line_spacing: 1.2        # 行距
  space_after: 6           # 表格组件后的固定高度留白，单位 pt（exact 空段）
  row_height_cm: 0.8       # 行高 (cm)
  alignment: "center"      # 表格对齐
  cell_margin:             # 单元格边距
    top: 30
    bottom: 30
    left: 60
    right: 60
  vertical_align: "center" # 垂直对齐 (top/center/bottom)
  header:                  # 标题行格式
    font: "Times New Roman"
    size: 10.5
    bold: true
    color: "#000000"
  body:                    # 正文格式
    font: "仿宋_GB2312"
    size: 10.5
    color: "#000000"

代码块格式 (code_block)

code_block:
  label:                   # 语言标签格式
    font: "Times New Roman"
    size: 10
    color: "#808080"
  content:                 # 代码内容格式
    font: "Times New Roman"
    size: 10
    color: "#333333"
    left_indent: 24
    line_spacing: 1.2

行内代码格式 (inline_code)

inline_code:
  font: "Times New Roman"
  size: 10
  color: "#333333"

引用块格式 (quote)

所有连续的 Markdown > 行统一渲染为段落型 callout，不根据“本章导读”“案例”等文字标签切换样式。段落底纹天然与正文左右边界齐平，不创建 w:tbl，因此 Word 的“查看网格线”不会显示虚线外框。与底纹同色的实线段落边界只用于承载文字内边距：首段承担上内边距、末段承担下内边距，每段承担左右内边距；线条与灰底同色，不形成可见轮廓。内部空引用行生成一个同底色、段前段后为 0 的 paragraph_spacing exact 空段，避免 Word 不给内容段段后距着色而产生白缝。连续多个内部空引用行确定性折叠为一个；首尾空引用行忽略，由 padding 承担块边缘留白。

quote:
  background_color: "#F5F5F5" # 段落背景色；与 code_block.content 背景完全一致
  padding:                     # 文字到灰底边缘的留白，单位 pt
    top: 5
    bottom: 5
    left: 6
    right: 6
  space_before: 6              # callout 外部段前间距，单位 pt
  space_after: 6               # callout 外部段后间距，单位 pt
  paragraph_spacing: 6         # 同底色内部 exact 空段高度，单位 pt
  font_size: null              # null = 继承正文
  line_spacing: null           # null = 继承正文
  first_line_indent: 0         # 引用段首行缩进，单位 pt
  align: justify               # left/center/right/justify

内置预设把 quote.background_color 与 code_block.content.background_color 分别显式写为同一个中性浅灰 #F5F5F5，便于独立覆盖配置，同时确保引用框与 text 等 fenced code block 的背景颜色完全一致。

兼容迁移：若自定义配置仍只有 v1.3.0 的 quote.cell_margin，转换器会按 20 twips = 1 pt 映射到 padding，保持原物理留白。width_percent、border_color、border_size 与 v1.2.x 的 left_indent_inches 不再参与段落型引用框渲染；引用框固定为正文宽、无可见轮廓。新配置应直接使用 padding。

table.space_after 归属于数据表组件本身：每个成功生成的 Markdown 或 HTML 表格后恰好追加一个段前/段后均为 0、行高为配置值的 exact 空段。后续正文继续使用普通正文格式；无数据表时不生成该间隔，图片与图注链路也不应用。

数学公式格式 (math)

math:
  font: "Times New Roman"
  size: 11
  italic: true
  color: "#00008B"

图片设置 (image)

image:
  display_ratio: 0.92      # 相对于页面可用宽度的比例
  max_width_cm: 14.2       # 最大显示宽度 (cm)
  target_dpi: 260          # 目标 DPI
  show_caption: true       # 是否显示标题

分割线设置 (horizontal_rule)

horizontal_rule:
  style: "border"           # border=段落底边框（默认，自适应栏宽不折行）；character=重复字符（旧实现）
  border_size: 6            # 边框粗细，单位 1/8 pt（6=0.75pt）——仅 border 模式
  border_space: 1           # 边框与文字间距 pt——仅 border 模式
  character: "─"            # 分割线字符——仅 character 模式
  repeat_count: 55          # 重复次数——仅 character 模式
  font: "Times New Roman"
  size: 12
  color: "#808080"
  alignment: "center"

character 模式的历史缺陷：U+2500（─）不在 Times New Roman 字库内，Word 字体回退后常按全角宽度渲染，55 个字符 ≈ 385–405pt，在 legal/report 等预设的正文栏宽（≤415pt）内必然折成两行。1.3.8 起默认改用段落底边框，与字体度量无关；如需复现旧样式可显式设 style: "character"。

列表设置 (lists)

lists:
  bullet:                  # 无序列表
    marker: "•"            # 标记符号
    indent: 24
  numbered:                # 有序列表
    indent: 24
    preserve_format: true
  task:                    # 任务列表
    unchecked: "☐"
    checked: "☑"

引号设置 (quotes)

quotes:
  convert_to_chinese: true  # 是否自动转换英文引号为中文引号

自定义配置

方法一：修改配置模板

1. 复制配置模板：

   cp assets/config-template.yaml my-config.yaml

2. 编辑配置文件，修改需要的参数

3. 使用自定义配置：

   python scripts/md2word.py input.md --config=my-config.yaml

方法二：基于预设修改

1. 复制预设文件：

   cp assets/presets/legal.yaml my-config.yaml

2. 在复制的文件基础上修改

3. 使用自定义配置

预设列表

运行以下命令查看所有预设详情（从 YAML 动态读取）：

python scripts/config.py --list

完整配置文件位于 assets/presets/ 目录，设计说明位于 assets/theme-notes/。