md2pdf 排版与渲染优化机制最佳实践

本指南以 Obsidian 渲染 Markdown 的核心优化内容项 作为基准线，逐项深度分析如何在 Pandoc + Typst 管线中对齐复现这些视觉效果，构建出印刷级别的 PDF 输出。每个章节均包含 Obsidian 的渲染行为描述、对应 Typst 实现方案，以及经过实战验证的代码。

v2.1 实战基准：本文档所有代码均已在 build_pdf.sh v2.1 管线中通过端到端验证（20 章 × 53 张 Mermaid 图表 × 170 页 × 8.1 MB PDF），而非理论推演。

一、 Skill 核心架构

1.1 技能包结构

.agent/skills/md2pdf/
├── SKILL.md                  # 核心定义（~185 行，渐进披露）
├── reference.md              # 深度参考：排错/避坑手册（按需读取）
└── scripts/
    ├── build_pdf.sh          # 主构建脚本 v2.1（8 步管线）
    ├── preprocess.sh         # Obsidian 语法预处理（sed/awk）
    ├── fix_ref_tables.py     # 参考文献表格 URL 列优化
    ├── typst-header.typ      # Healing Dream 主题样式 v2.1（109 行）
    ├── callout.lua           # Obsidian Callout → Typst 彩色卡片
    └── highlight.lua         # ==高亮== → Typst #highlight

1.2 完整转换管线

[多源 .md 文件]
  │
  ├─ 🔧 mmdc --scale 2             → Mermaid 代码块 → Retina PNG     [build_pdf.sh Step 3]
  ├─ 🔧 sed/awk 预处理              → 双链/水平线/Wiki-image 降级      [preprocess.sh]
  ├─ 🔧 Python 修表                 → 长 URL 表格列物理折叠            [fix_ref_tables.py]
  │
  ▼
[Pandoc AST]
  │
  ├─ 🔧 --lua-filter=callout.lua   → Callout → Typst 彩色卡片        [AST 层语义保真]
  ├─ 🔧 --lua-filter=highlight.lua → ==高亮== → Typst #highlight      [AST 层语义保真]
  ├─ --include-in-header=typst-header.typ → 注入 Healing Dream 样式
  ▼
[Typst 排版引擎]  → 高品质 PDF

三层对齐杠杆：

1.3 Obsidian 渲染的本质

Obsidian 通过 双引擎 架构实现渲染：Live Preview 基于 CodeMirror 6 动态隐藏 Markdown 令牌并注入 Widget；Reading View 经由 CommonMark → GFM → Obsidian Flavored 三级解析器链生成完整 HTML DOM，再由 PrismJS、MathJax、Mermaid.js 等专用库接管特定元素的精渲染，最后通过 MarkdownPostProcessor API 允许插件对 DOM 进行深度二次改造（如 Callouts、Dataview 等）。

二、 Healing Dream 主题色板

v2.1 统一使用暖色系，与 PingFang SC 在 macOS 上的自然渲染色温一致。

2.1 核心色值表

2.2 Callout 类型色板（callout.lua）

三、 逐项对齐 Obsidian 渲染优化

3.1 标题层级渲染 (Headings)

Obsidian 行为：H1 字号大且下方有分隔线，H2/H3 递次缩减字号，标题前后均有精心调校的呼吸间距。

// 编号由源 Markdown 手动控制，不使用 Pandoc -N 或 Typst numbering

// H1：底部暖色结构线 + 大间距
#show heading.where(level: 1): it => block(
  width: 100%, stroke: (bottom: 1.2pt + rgb("#D4C5B9")),
  inset: (bottom: 0.6em), above: 2em, below: 1.2em,
  text(fill: rgb("#1E293B"), weight: "bold", size: 1.4em, it)
)

// H2：深色中等字号
#show heading.where(level: 2): it => block(
  above: 1.5em, below: 0.8em,
  text(fill: rgb("#334155"), weight: "bold", size: 1.15em, it)
)

// H3：纤细克制
#show heading.where(level: 3): it => block(
  above: 1.2em, below: 0.6em,
  text(fill: rgb("#475569"), weight: "semibold", size: 1.05em, it)
)

双重编号陷阱

若源 Markdown 文件标题已包含手动编号（如 ## 9.2 产业政策），不得在 Pandoc 命令行使用 -N（--number-sections）或 Typst 中设置 #set heading(numbering: "1.1")，否则会产生 10.2 9.2 产业政策 双重编号。v2.1 中两者均已移除。

3.2 表格渲染 (Tables)

Obsidian 行为：表头浅色背景，行间极细分隔线，内容整洁。

// 允许表格跨页断开（Pandoc 将表格包裹为 figure）
#show figure: set block(breakable: true)

#set table(
  stroke: (x, y) => (
    left: 0.5pt + luma(200), right: 0.5pt + luma(200),
    top: if y == 0 { 1pt + luma(100) } else { 0.5pt + luma(220) },
    bottom: if y == 0 { 1pt + luma(100) } else { 0.5pt + luma(220) },
  ),
  // 表头暖米色底 + 奇数行极浅底色（斑马纹）
  fill: (x, y) => if y == 0 { rgb("#FAF5F0") } else if calc.odd(y) { rgb("#FDFCFB") },
  // 加宽水平内边距，配合左对齐提升阅读体验
  inset: (x, y) => (top: 8pt, bottom: 8pt, left: 10pt, right: 10pt),
  align: horizon + left,
)
#show table.header: set text(weight: "bold", size: 0.9em)
#show table: set text(size: 0.85em)

设计决策：左对齐 vs 居中

v2.0 使用 align: horizon + center，但实战发现文本密集列（如「核心逻辑」「意义」）居中后起点不一致，阅读跳跃感强。v2.1 切换为 left，配合加宽内边距（6pt→10pt）弥补视觉留白。

3.3 加粗文本强调 (Strong)

Obsidian 行为：加粗文字仅字重变化。

v2.1 增强：为 strong 元素追加颜色加深（#1F2937 → #111827），使关键数字（792 万、$1.189T、4.5%）在密集段落中更易被眼球捕获：

#show strong: set text(fill: rgb("#111827"))

差异虽微（仅色阶加深一档），但在 170 页长报告中扫描效率显著提升。

3.4 引用块与 Callout 渲染 (Blockquotes & Callouts)

Obsidian 行为：左侧彩色竖线 + 浅色背景 + 右圆角 + 顶部 Icon + 粗体标题行。

方案 A（默认）：Lua Filter 语义保真转换

callout.lua 在 Pandoc AST 层完成 8 种 Callout 类型→颜色→Icon 的映射，输出 Typst #block(fill: ..., stroke: ...) 彩色卡片。

方案 B（兜底）：Typst quote 样式拦截

未被 Lua filter 转换的普通 blockquote 走此规则：

#show quote.where(block: true): it => block(
  fill: rgb("#F8FAFC"), stroke: (left: 3pt + rgb("#CDB4DB")),
  inset: (x: 1.2em, y: 1em), radius: (right: 4pt),
  width: 100%, above: 1em, below: 1em,
  text(fill: rgb("#374151"), size: 0.92em, it.body)
)

双层防御架构

preprocess.sh 的 sed Callout 降级先于 Lua filter 执行。当前 v2.1 中 sed 已将 > [!NOTE] 转为 > **📝 NOTE**:，Callout 标记被剥离后 callout.lua 不再命中。若需启用 Lua filter 的语义保真模式（颜色区分），需注释 preprocess.sh 中 Callout sed 行。

3.5 代码块与语法高亮 (Code Blocks & Inline Code)

// 块级代码：浅灰背景 + 圆角卡片
#show raw.where(block: true): it => block(
  fill: rgb("#F8FAFC"), stroke: 0.5pt + rgb("#E2E8F0"),
  inset: 12pt, radius: 6pt, width: 100%,
  text(size: 0.82em, it)
)

// 行内代码：红字 + 浅灰背景胶囊
#show raw.where(block: false): it => box(
  fill: rgb("#F1F5F9"), inset: (x: 4pt, y: 0pt), outset: (y: 3pt),
  radius: 3pt, text(fill: rgb("#E63946"), size: 0.9em, it)
)

不要在 #show raw 中指定等宽字体

最初实现中使用 text(font: "Fira Code", ...) 包裹代码块。实战发现 macOS 未安装 Fira Code 时 Typst 静默回退到默认字体，行为不可预测。v2.1 决策：移除显式 font: 声明，依赖 Pandoc 命令行 -V monofont="Menlo" 统一控制——Menlo 是 macOS 内置字体，零安装风险。

3.6 超链接渲染 (Links)

PDF 中不存在”内部双链”。预处理已将 [[页面名]] 剥离为纯文本。所有超链接统一品牌蓝：

#show link: set text(fill: rgb("#4A90E2"))

3.7 分隔线渲染 (Horizontal Rules)

Obsidian 行为：极细灰色分隔线。

v2.1 实现（Pandoc 将 *** 转为 Typst #line()）：

#show line: it => block(
  above: 1.2em, below: 1.2em,
  line(length: 100%, stroke: 0.4pt + luma(210))
)

preprocess.sh 已将正文中的 --- 替换为 ***（避免 --file-scope 下被误识别为 YAML frontmatter 分隔符）。

3.8 段落间距与字体系统 (Typography)

#set text(
  font: ("PingFang SC", "Noto Sans CJK SC"),
  size: 10.5pt,
  fill: rgb("#1F2937"),
  lang: "zh", region: "cn",
)
#set par(leading: 0.85em, spacing: 1.2em, first-line-indent: 0em)

macOS 字体兼容性

Font fallback 链只能包含系统已安装字体。使用 typst fonts | grep "字体名" 验证。

3.9 页面布局与页码 (Page Layout)

#set page(
  margin: (top: 2.5cm, bottom: 2.5cm, left: 2.5cm, right: 2cm),
  footer: context [
    #set align(center)
    #set text(size: 9pt, fill: luma(150))
    #counter(page).display("1")
  ],
)

3.10 列表与参考文献

#set list(indent: 1.2em, body-indent: 0.5em, spacing: 0.65em)
#set enum(indent: 1.2em, body-indent: 0.5em, spacing: 0.65em)
#show bibliography: set text(size: 0.82em, fill: luma(80))

四、 预处理阶段的关键防御机制

4.1 Mermaid 图表静态化

mmdc -i input.mmd -o output.png --scale2--backgroundColor white

• --scale 2：Retina 2x 分辨率。
• --backgroundColor white：避免深色主题下的「幽灵图表」。
• 渲染失败时定位文件修复 Mermaid 语法，仅重处理出错文件。

4.2 Obsidian 私有语法双层处理

4.3 参考文献表格优化

fix_ref_tables.py 自动检测含 | URL | 列的表格，将 URL 列与标题列合并为 [标题](URL) 超链接，删除冗余列，防止 A4 纸面表格横向溢出。

五、 Shell 脚本工程实战教训

5.1 set -e 与条件表达式的致命交互

# ❌ set -e 下 test 失败 → 整个脚本退出
[-f mermaid-config.json ]&&MMDC_CMD="$MMDC_CMD -c mermaid-config.json"

# ✅ 安全写法
if[-f mermaid-config.json ];thenMMDC_CMD="$MMDC_CMD -c mermaid-config.json";fi

原理：POSIX shell 中 set -e 对 && 链的最终 exit code 生效。[ ... ] && ... 在 test 失败时链整体返回 1，触发 set -e 中止。

5.2 中文文件名的 Shell 引号地雷

# ❌ 终端陷入 dquote> 无限等待
FILES=$(ls .build_pdf/[0-9]*.md |sort)
pandoc -o output.pdf $FILES

# ✅ 直接使用通配符
pandoc -o output.pdf [0-9]*.md

5.3 Pandoc 工作目录必须是 .build_pdf/

mmdc 预渲染的 PNG 路径为相对路径 ./filename-N.png。Pandoc 必须从 .build_pdf/ 目录内执行，否则所有图片引用失效。

六、 完整 typst-header.typ v2.1

将以下所有规则整合到 .agent/skills/md2pdf/scripts/typst-header.typ，通过 pandoc --include-in-header=typst-header.typ 一次性注入：

// ═══════════════════════════════════════════════════════════════════════
// md2pdf Typst 增强样式 v2.1 — Healing Dream 主题
// ═══════════════════════════════════════════════════════════════════════

// ─── 全局基础 ─────────────────────────────────────────────────────────
#set text(
  font: ("PingFang SC", "Noto Sans CJK SC"),
  size: 10.5pt, fill: rgb("#1F2937"),
  lang: "zh", region: "cn",
)
#set par(leading: 0.85em, spacing: 1.2em, first-line-indent: 0em)
#set page(
  margin: (top: 2.5cm, bottom: 2.5cm, left: 2.5cm, right: 2cm),
  footer: context [
    #set align(center)
    #set text(size: 9pt, fill: luma(150))
    #counter(page).display("1")
  ],
)

// ─── 标题系统 ─────────────────────────────────────────────────────────
#show heading.where(level: 1): it => block(
  width: 100%, stroke: (bottom: 1.2pt + rgb("#D4C5B9")),
  inset: (bottom: 0.6em), above: 2em, below: 1.2em,
  text(fill: rgb("#1E293B"), weight: "bold", size: 1.4em, it)
)
#show heading.where(level: 2): it => block(
  above: 1.5em, below: 0.8em,
  text(fill: rgb("#334155"), weight: "bold", size: 1.15em, it)
)
#show heading.where(level: 3): it => block(
  above: 1.2em, below: 0.6em,
  text(fill: rgb("#475569"), weight: "semibold", size: 1.05em, it)
)

// ─── 加粗强调 ─────────────────────────────────────────────────────────
#show strong: set text(fill: rgb("#111827"))

// ─── 表格系统 ─────────────────────────────────────────────────────────
#show figure: set block(breakable: true)
#set table(
  stroke: (x, y) => (
    left: 0.5pt + luma(200), right: 0.5pt + luma(200),
    top: if y == 0 { 1pt + luma(100) } else { 0.5pt + luma(220) },
    bottom: if y == 0 { 1pt + luma(100) } else { 0.5pt + luma(220) },
  ),
  fill: (x, y) => if y == 0 { rgb("#FAF5F0") } else if calc.odd(y) { rgb("#FDFCFB") },
  inset: (x, y) => (top: 8pt, bottom: 8pt, left: 10pt, right: 10pt),
  align: horizon + left,
)
#show table.header: set text(weight: "bold", size: 0.9em)
#show table: set text(size: 0.85em)

// ─── 引用块 / Callout ────────────────────────────────────────────────
#show quote.where(block: true): it => block(
  fill: rgb("#F8FAFC"), stroke: (left: 3pt + rgb("#CDB4DB")),
  inset: (x: 1.2em, y: 1em), radius: (right: 4pt),
  width: 100%, above: 1em, below: 1em,
  text(fill: rgb("#374151"), size: 0.92em, it.body)
)

// ─── 代码块 ──────────────────────────────────────────────────────────
#show raw.where(block: true): it => block(
  fill: rgb("#F8FAFC"), stroke: 0.5pt + rgb("#E2E8F0"),
  inset: 12pt, radius: 6pt, width: 100%,
  text(size: 0.82em, it)
)
#show raw.where(block: false): it => box(
  fill: rgb("#F1F5F9"), inset: (x: 4pt, y: 0pt), outset: (y: 3pt),
  radius: 3pt, text(fill: rgb("#E63946"), size: 0.9em, it)
)

// ─── 超链接 / 列表 / 分隔线 / 参考文献 ──────────────────────────────
#show link: set text(fill: rgb("#4A90E2"))
#set list(indent: 1.2em, body-indent: 0.5em, spacing: 0.65em)
#set enum(indent: 1.2em, body-indent: 0.5em, spacing: 0.65em)
#show line: it => block(
  above: 1.2em, below: 1.2em,
  line(length: 100%, stroke: 0.4pt + luma(210))
)
#show bibliography: set text(size: 0.82em, fill: luma(80))

七、 技术参考资料

八、 演进路线

已完成 ✅

1. Lua Filter 集成（callout.lua + highlight.lua）
2. Wiki-image ![[image]] 支持
3. 完整 Healing Dream 主题（109 行 typst-header.typ v2.1）
4. 表格暖色系 + 斑马纹 + 左对齐
5. Strong 文本颜色加深
6. 页脚页码
7. 分隔线淡灰色
8. 双重编号修复

下一步 🔮

1. 模板封装：升级为独立 healing-dream-report.typ 根骨模板，内置封面页、页眉、双面打印留白。
2. Callout 语义保真开关：提供 sed 降级 / Lua filter 彩色卡片两种模式切换。
3. PDF 压缩：接入 ghostscript -dPDFSETTINGS 优化体积（8 MB → 3-4 MB）。
4. Linux 兼容性：适配 Noto Sans CJK SC 在 Ubuntu 上的 fontconfig 路径。
5. TOC 样式：拦截 Typst 目录元素，添加 Healing Dream 主题色。