release: 发布 v0.5.1

新增能力：内置 4 套红头、3 套正式文档和 3 套标书主题，支持主题推荐页边距、页面装饰、页眉页脚和页码；增加结构化公文、项目报告及标书 Front Matter，内置 Fandol 中文字体、两份教程和 14 份主题示例。桌面工作流：重组更多菜单，增加新建、保存、另存为快捷键和未保存确认；另存为后跟随新路径，主题示例自动切换主题，Desktop 发行包完整携带教程、示例与字体。问题修复：修正红头标题居中与正式文档字体；围栏代码按正文宽度自动换行，长内容安全断行，至少两行即可在当前页分页，并统一保留 8px 左侧内容留白；Docker Web 镜像正确打包 samples。兼容与部署：未声明主题推荐设置时继续使用 16mm 默认页边距；Web 隐藏不适用的另存为。正式镜像 yixiong/md-to-pdf:v0.5.1 内容 ID 为 sha256:72f519a69bfd6cb2f6df30c2be938e58ceb6f20e4748a32551874de3d436b276，Compose 健康运行。验证结果：最终修复前 65 个测试文件、286 项测试通过，最终代码块与主题定向测试 27 项通过；全项目类型检查、生产构建和 git diff --check 通过。容器检出 14 套主题、17 份 Markdown，代码块回归 PDF 为 2 页且无越界。NSIS SHA-256 为 676CCE73D782B0B15AC6BC68F253CFBC4740383583E4DAA98F746EDF9999C5CC，ZIP SHA-256 为 82BF6ADF1200604F145CC86FA3ED193955CF6741EBEE3DF8953483515CFF621F。
2026-07-29 16:58:17 +08:00
parent 58087d0c7e
commit 83e6559c2c
111 changed files with 8274 additions and 173 deletions
@@ -0,0 +1,470 @@
+---
+title: Markdown ECharts 图表教程
+author: Markdown PDF 导出器
+keywords: [ECharts, Markdown, 图表, 教程]
+---
+
+# Markdown ECharts 图表教程
+
+本教程介绍如何在 Markdown 中通过 `echarts` 围栏插入可打印的 ECharts
+图表。围栏内容使用 YAML，图表会以 SVG 渲染，并与正文一起进入快速
+预览、精确预览和最终 PDF。
+
+> `echarts` 围栏不是普通的 `yaml` 代码块。请保留开头和结尾的三个反引号，
+> 并将开头写成 `echarts`。
+
+## 一、最小可用示例
+
+下面的内容可以直接复制到 Markdown 正文中：
+
+````markdown
+```echarts
+version: 1
+caption: 各部门季度完成量
+height: 58mm
+theme: document
+option:
+  xAxis:
+    type: category
+    data: [研发, 产品, 设计, 运营]
+  yAxis:
+    type: value
+  series:
+    - name: 完成量
+      type: bar
+      data: [28, 22, 17, 25]
+```
+````
+
+实际渲染效果如下：
+
+```echarts
+version: 1
+caption: 各部门季度完成量
+height: 58mm
+theme: document
+option:
+  xAxis:
+    type: category
+    data: [研发, 产品, 设计, 运营]
+  yAxis:
+    type: value
+  series:
+    - name: 完成量
+      type: bar
+      data: [28, 22, 17, 25]
+```
+
+## 二、围栏外层字段
+
+围栏最外层只支持下表中的字段，其他字段必须放入 `option`。
+
+| 字段 | 类型 | 必填 | 功能 | 默认值 | 示例 |
+| --- | --- | --- | --- | --- | --- |
+| `version` | 整数 | 否 | ECharts 围栏协议版本，目前只能是 `1` | `1` | `version: 1` |
+| `height` | 长度字符串 | 否 | 固定图表高度，支持 `mm`、`cm`、`in`、`px` | `80mm` | `height: 65mm` |
+| `aspectRatio` | 正数 | 否 | 按内容宽度计算宽高比，最大为 `10` | 无 | `aspectRatio: 1.6` |
+| `theme` | 枚举 | 否 | 图表配色，可选 `document`、`light`、`dark` | `document` | `theme: light` |
+| `caption` | 字符串 | 否 | 显示在图表下方的图注，最长 500 个字符 | 无 | `caption: 图1 月度趋势` |
+| `option` | 对象 | 是 | ECharts 的纯数据配置对象 | 无 | `option: { ... }` |
+
+尺寸规则：
+
+- 未设置 `height` 和 `aspectRatio` 时，高度默认为 `80mm`；
+- 同时设置两者时，以显式 `height` 作为固定高度；
+- 普通统计图建议使用 `50mm`～`85mm`；
+- 关系图或层级图可使用 `80mm`～`120mm`；
+- 图表超过单页内容区时，系统会等比例缩小到一页内。
+
+## 三、`option` 常用字段
+
+`option` 使用 ECharts 官方的纯数据结构。下表列出正式文档最常用的字段，
+不是 ECharts 全部能力的穷举。
+
+| 字段 | 类型 | 功能 | 示例 |
+| --- | --- | --- | --- |
+| `title` | 对象 | 图内标题、副标题及位置 | `title: { text: 月度趋势, left: center }` |
+| `legend` | 对象 | 系列图例、方向和位置 | `legend: { top: 0 }` |
+| `tooltip` | 对象 | 浏览器预览中的提示方式 | `tooltip: { trigger: axis }` |
+| `grid` | 对象 | 直角坐标图的绘图区边距 | `grid: { left: 48, right: 24 }` |
+| `xAxis` | 对象或数组 | 横轴类型、类目和标签 | `xAxis: { type: category }` |
+| `yAxis` | 对象或数组 | 纵轴类型、范围和名称 | `yAxis: { type: value }` |
+| `dataset` | 对象或数组 | 多系列共享的表格型数据源 | `dataset: { source: [...] }` |
+| `series` | 数组 | 图表系列；每项必须有受支持的 `type` | `series: [{ type: line, data: [...] }]` |
+| `radar` | 对象 | 雷达图指标名称和最大值 | `radar: { indicator: [...] }` |
+| `visualMap` | 对象 | 热力图等数值到颜色的映射 | `visualMap: { min: 0, max: 100 }` |
+
+建议用 `caption` 表示“图 1、数据来源、统计口径”等打印说明；`title`
+适合需要在图形内部显示的标题。两者同时使用时会分别显示。
+
+### 三种标题不要混用
+
+| 位置 | 写法 | 用途 |
+| --- | --- | --- |
+| 文档章节标题 | Markdown 的 `## 标题` | 组织整篇文档的章节层级 |
+| 图表内部标题 | `option.title.text` | 显示在 SVG 图形内部，可带副标题 |
+| 图表下方图注 | 围栏外层的 `caption` | 图号、数据来源、统计口径和补充说明 |
+
+`option.title` 常用字段：
+
+| 字段 | 功能 | 示例 |
+| --- | --- | --- |
+| `text` | 图内主标题 | `text: 上半年项目交付趋势` |
+| `subtext` | 主标题下方的副标题 | `subtext: 统计周期：2026年1—6月` |
+| `left` | 水平位置，可用像素、百分比、`left`、`center`、`right` | `left: center` |
+| `top` | 垂直位置，可用像素、百分比、`top`、`middle`、`bottom` | `top: 4` |
+| `textStyle` | 主标题字体样式 | `textStyle: { fontSize: 18 }` |
+| `subtextStyle` | 副标题字体样式 | `subtextStyle: { fontSize: 12 }` |
+
+`option.legend` 会从 `series[].name` 或 `dataset` 列名生成图例。多系列
+图表应为每个系列设置清晰的 `name`，并给标题、图例和绘图区留出互不
+重叠的空间。
+
+## 四、图表标题与顶部图例：折线图
+
+````markdown
+```echarts
+version: 1
+caption: 图1 项目交付统计；数据来源：项目管理系统
+height: 76mm
+option:
+  title:
+    text: 上半年项目交付趋势
+    subtext: 统计周期：2026年1—6月
+    left: center
+    top: 4
+    textStyle:
+      fontSize: 18
+    subtextStyle:
+      fontSize: 12
+  tooltip:
+    trigger: axis
+  legend:
+    data: [计划, 实际]
+    top: 48
+  grid:
+    left: 48
+    right: 24
+    bottom: 32
+    top: 82
+    containLabel: true
+  xAxis:
+    type: category
+    boundaryGap: false
+    data: [一月, 二月, 三月, 四月, 五月, 六月]
+  yAxis:
+    type: value
+    name: 项目数
+  series:
+    - name: 计划
+      type: line
+      smooth: true
+      data: [12, 15, 18, 20, 24, 28]
+    - name: 实际
+      type: line
+      smooth: true
+      data: [10, 16, 17, 22, 23, 31]
+```
+````
+
+```echarts
+version: 1
+caption: 图1 项目交付统计；数据来源：项目管理系统
+height: 76mm
+option:
+  title:
+    text: 上半年项目交付趋势
+    subtext: 统计周期：2026年1—6月
+    left: center
+    top: 4
+    textStyle:
+      fontSize: 18
+    subtextStyle:
+      fontSize: 12
+  tooltip:
+    trigger: axis
+  legend:
+    data: [计划, 实际]
+    top: 48
+  grid:
+    left: 48
+    right: 24
+    bottom: 32
+    top: 82
+    containLabel: true
+  xAxis:
+    type: category
+    boundaryGap: false
+    data: [一月, 二月, 三月, 四月, 五月, 六月]
+  yAxis:
+    type: value
+    name: 项目数
+  series:
+    - name: 计划
+      type: line
+      smooth: true
+      data: [12, 15, 18, 20, 24, 28]
+    - name: 实际
+      type: line
+      smooth: true
+      data: [10, 16, 17, 22, 23, 31]
+```
+
+## 五、底部图例：使用 `dataset` 的柱状图
+
+`dataset.source` 适合把数据集中写成一张表，多个系列再按列读取。
+
+````markdown
+```echarts
+version: 1
+caption: 图2 分区域合同额与回款额（单位：万元）
+height: 70mm
+option:
+  title:
+    text: 分区域合同执行情况
+    left: center
+    top: 4
+  legend:
+    bottom: 2
+  tooltip:
+    trigger: axis
+  grid:
+    left: 48
+    right: 24
+    top: 48
+    bottom: 52
+    containLabel: true
+  dataset:
+    source:
+      - [区域, 合同额, 回款额]
+      - [东区, 820, 690]
+      - [南区, 760, 610]
+      - [西区, 540, 480]
+      - [北区, 680, 570]
+  xAxis:
+    type: category
+  yAxis:
+    type: value
+  series:
+    - type: bar
+    - type: bar
+```
+````
+
+```echarts
+version: 1
+caption: 图2 分区域合同额与回款额（单位：万元）
+height: 70mm
+option:
+  title:
+    text: 分区域合同执行情况
+    left: center
+    top: 4
+  legend:
+    bottom: 2
+  tooltip:
+    trigger: axis
+  grid:
+    left: 48
+    right: 24
+    top: 48
+    bottom: 52
+    containLabel: true
+  dataset:
+    source:
+      - [区域, 合同额, 回款额]
+      - [东区, 820, 690]
+      - [南区, 760, 610]
+      - [西区, 540, 480]
+      - [北区, 680, 570]
+  xAxis:
+    type: category
+  yAxis:
+    type: value
+  series:
+    - type: bar
+    - type: bar
+```
+
+## 六、饼图：名称与数值
+
+饼图数据项使用 `{ name, value }` 结构。正式文档中建议控制分类数量，
+避免标签过密。
+
+````markdown
+```echarts
+version: 1
+caption: 图3 年度预算构成
+height: 68mm
+option:
+  title:
+    text: 年度预算构成
+    subtext: 单位：%
+    left: "62%"
+    top: 6
+    textAlign: center
+  tooltip:
+    trigger: item
+  legend:
+    orient: vertical
+    left: left
+  series:
+    - name: 预算
+      type: pie
+      radius: ["35%", "68%"]
+      center: ["62%", "50%"]
+      data:
+        - { name: 软件采购, value: 36 }
+        - { name: 基础设施, value: 28 }
+        - { name: 运维服务, value: 22 }
+        - { name: 培训推广, value: 14 }
+```
+````
+
+```echarts
+version: 1
+caption: 图3 年度预算构成
+height: 68mm
+option:
+  title:
+    text: 年度预算构成
+    subtext: 单位：%
+    left: "62%"
+    top: 6
+    textAlign: center
+  tooltip:
+    trigger: item
+  legend:
+    orient: vertical
+    left: left
+  series:
+    - name: 预算
+      type: pie
+      radius: ["35%", "68%"]
+      center: ["62%", "50%"]
+      data:
+        - { name: 软件采购, value: 36 }
+        - { name: 基础设施, value: 28 }
+        - { name: 运维服务, value: 22 }
+        - { name: 培训推广, value: 14 }
+```
+
+## 七、雷达图：指标与最大值
+
+雷达图必须提供非空的 `radar.indicator`。每组 `series.data[].value`
+至少要包含与指标数量相同的数值。
+
+````markdown
+```echarts
+version: 1
+caption: 图4 项目综合评价
+height: 72mm
+option:
+  legend:
+    data: [项目甲, 项目乙]
+  radar:
+    indicator:
+      - { name: 进度, max: 100 }
+      - { name: 质量, max: 100 }
+      - { name: 成本, max: 100 }
+      - { name: 风险, max: 100 }
+      - { name: 满意度, max: 100 }
+  series:
+    - type: radar
+      data:
+        - name: 项目甲
+          value: [86, 92, 78, 81, 90]
+        - name: 项目乙
+          value: [91, 84, 88, 76, 85]
+```
+````
+
+## 八、关系图：节点与连线
+
+关系图使用 `data` 或 `nodes` 描述节点，使用 `links` 或 `edges` 描述关系。
+连线的 `source`、`target` 必须引用已存在的节点名称或 ID。
+
+````markdown
+```echarts
+version: 1
+caption: 图5 项目协同关系
+height: 78mm
+option:
+  series:
+    - type: graph
+      layout: force
+      roam: false
+      label:
+        show: true
+      force:
+        repulsion: 260
+        edgeLength: 90
+      data:
+        - { id: pm, name: 项目经理, symbolSize: 58 }
+        - { id: dev, name: 研发组, symbolSize: 48 }
+        - { id: test, name: 测试组, symbolSize: 48 }
+        - { id: ops, name: 运维组, symbolSize: 48 }
+      links:
+        - { source: pm, target: dev, value: 3 }
+        - { source: pm, target: test, value: 2 }
+        - { source: dev, target: ops, value: 1 }
+        - { source: test, target: ops, value: 2 }
+```
+````
+
+## 九、系列类型与数据形状
+
+当前支持 17 种系列。下表重点说明每种系列最容易写错的数据结构。
+
+| `series[].type` | 主要数据结构 | 示例或要求 |
+| --- | --- | --- |
+| `line`、`bar` | 数值数组或 `dataset.source` | `data: [12, 18, 24]` |
+| `scatter` | 坐标二元数组 | `data: [[12, 18], [16, 25]]` |
+| `pie`、`funnel`、`gauge` | 名称和有限数值 | `{ name: 已完成, value: 72 }` |
+| `radar` | 指标值数组 | `{ name: 项目甲, value: [86, 92, 78] }` |
+| `heatmap` | x、y、值三元数组 | `data: [[0, 0, 32], [1, 0, 48]]` |
+| `boxplot` | 最小值、Q1、中位数、Q3、最大值 | `data: [[5, 12, 18, 24, 36]]` |
+| `candlestick` | 开盘、收盘、最低、最高 | `data: [[20, 24, 18, 28]]` |
+| `tree` | 递归 `children` 节点 | `data: [{ name: 总部, children: [...] }]` |
+| `treemap`、`sunburst` | 带数值的递归叶节点 | `{ name: 产品线A, value: 36 }` |
+| `graph` | 节点和关系边 | `data: [...]` 配合 `links: [...]` |
+| `sankey`、`chord` | 节点和带权关系边 | 关系边需要有限数值 `value` |
+| `pictorialBar` | 与柱状图相同 | 可使用安全的内嵌 `path://` 矢量路径 |
+
+每个系列必须直接提供非空 `series[].data`，或者通过有效的
+`dataset.source` 提供数据。部分关系图使用 `nodes` 和 `links`，不采用
+普通 `data` 数组。
+
+## 十、安全与错误处理
+
+为了确保离线、可复现和安全渲染，配置只能包含纯数据：
+
+- 不支持 JavaScript 函数、自定义脚本或 HTML formatter；
+- 不允许外部图片、跳转链接和远程资源；
+- 不支持 `custom` 系列；
+- YAML 锚点、别名和自定义标签会被拒绝；
+- `option` 中的原型污染属性会被拒绝；
+- 单个围栏 YAML 不能超过 512 KiB；
+- 配置错误只会显示局部错误占位，不会中断整篇文档。
+
+下面是一个会产生局部错误提示的示例，请勿在正式文档中使用：
+
+````markdown
+```echarts
+version: 1
+option:
+  series:
+    - type: pie
+      data: []
+```
+````
+
+错误信息会指出类似 `option.series.0.data` 的配置路径，便于定位问题。
+
+## 十一、排版建议
+
+1. `caption` 用于图号、数据来源和统计口径，正文标题用于章节结构。
+2. 正式报告优先使用少量稳定颜色，并确保黑白打印仍能区分系列。
+3. 横轴类目过多时，优先拆图、旋转标签或改用横向柱状图。
+4. 图表、图注会作为一个不可拆分媒体块参与分页。
+5. 导出前使用“精确”预览检查最终分页、图例和标签。
@@ -0,0 +1,376 @@
+---
+title: 公文与正式文档主题使用教程
+author: Markdown PDF 导出器
+keywords: [公文, 红头文件, 正式文档, 标书, 教程]
+---
+
+# 公文与正式文档主题使用教程
+
+本教程介绍政企红头、政企正式和标书主题的选择方法，以及如何通过文档
+开头的 Front Matter YAML 生成红头、发文字号、签发人、简报刊头、项目
+封面、投标封面和文末版记。
+
+## 一、Front Matter 是什么
+
+Front Matter 是 Markdown 文件最前面的 YAML 配置，必须由两行 `---`
+包围。结束标记之后才开始写正文。
+
+```yaml
+---
+title: 关于进一步规范项目管理工作的通知
+author: 示例市人民政府办公室
+subject: 项目管理工作通知
+keywords: [公文, 通知, 项目管理]
+document:
+  profile: official
+  issuer: 示例市人民政府办公室
+  number: 示例办发〔2026〕12号
+  date: 2026年7月29日
+---
+```
+
+注意：
+
+- YAML 使用空格缩进，不要使用 Tab；
+- `document` 下的字段需要比 `document:` 多缩进两个空格；
+- 日期建议写成明确的中文字符串，例如 `2026年7月29日`；
+- 教程或主题示例从“更多”菜单打开时会自动切换主题；
+- 普通 Markdown 文件中的 Front Matter 只描述文档结构，不会自动选择主题。
+
+## 二、选择合适的主题
+
+### 政企红头
+
+- **政企红头·国家标准**：适合通知、决定、请示、报告等较完整的党政机关公文结构。
+- **政企红头·信函格式**：适合函、征求意见、答复等信函式公文。
+- **政企红头·企业简版**：适合企业内部通知、制度和管理文件。
+- **政企红头·工作简报**：适合工作动态、专题简报和阶段性通报。
+
+### 政企正式
+
+- **政企正式·规章制度**：适合制度、办法、细则和管理规范。
+- **政企正式·工作报告**：适合总结、汇报、调研和会议材料。
+- **政企正式·可研报告**：适合可行性研究、项目建议书和建设方案。
+
+### 标书正式
+
+- **标书正式·经典版**：适合常规投标文件和技术方案。
+- **标书正式·商务蓝**：适合企业方案、汇报材料和商务投标。
+- **标书正式·暗标版**：适合需要弱化投标人识别信息的技术暗标。
+
+## 三、通用元数据字段
+
+这些字段位于 YAML 最外层，可用于所有主题和 profile。
+
+| 字段 | 类型 | 功能 | 示例 |
+| --- | --- | --- | --- |
+| `title` | 字符串 | 文档标题；结构化主题会将其用于红头标题或封面标题 | `title: 关于开展专项检查的通知` |
+| `author` | 字符串 | 作者或编制单位，同时可写入 PDF 作者元数据 | `author: 示例市人民政府办公室` |
+| `subject` | 字符串 | 文档主题，可写入 PDF 主题元数据 | `subject: 专项检查工作通知` |
+| `keywords` | 字符串数组 | 文档关键词，可写入 PDF 关键词元数据 | `keywords: [公文, 通知, 检查]` |
+| `document` | 对象 | 启用并配置结构化公文、简报、项目报告或标书 | `document: { profile: official }` |
+
+`title` 是结构化主题最重要的通用字段。使用 `official`、`project-report`
+或 `tender` 时，正文通常不再重复书写同名一级标题。
+
+字段路径也可以用点号快速定位，例如 `document.profile: official` 表示
+YAML 中 `document` 对象下的 `profile: official`，点号路径仅用于说明，
+不能直接照此写入 YAML。
+
+## 四、红头公文：`official`
+
+### 最小配置
+
+最小配置适合企业简版红头或暂不需要文号、签发人的文件：
+
+```yaml
+---
+title: 关于调整项目评审流程的通知
+document:
+  profile: official
+  issuer: 示例科技集团有限公司
+  date: 2026年7月29日
+---
+```
+
+### 完整配置
+
+```yaml
+---
+title: 关于进一步规范项目管理工作的通知
+author: 示例市人民政府办公室
+subject: 项目管理工作通知
+keywords: [公文, 通知, 项目管理]
+document:
+  profile: official
+  issuer: 示例市人民政府办公室
+  number: 示例办发〔2026〕12号
+  secrecy: 秘密
+  urgency: 加急
+  signatory: 张三
+  date: 2026年7月29日
+  copyTo:
+    - 市发展改革委
+    - 市财政局
+    - 市审计局
+  printingOffice: 示例市人民政府办公室
+---
+```
+
+### `official` 字段表
+
+| 字段 | 类型 | 必填 | 功能 | 示例 |
+| --- | --- | --- | --- | --- |
+| `profile` | 固定字符串 | 是 | 启用红头公文结构，必须为 `official` | `profile: official` |
+| `issuer` | 字符串 | 否 | 红头发文机关名称，并用于文末落款机关 | `issuer: 示例市人民政府办公室` |
+| `number` | 字符串 | 否 | 发文字号 | `number: 示例办发〔2026〕12号` |
+| `secrecy` | 字符串 | 否 | 密级或保密期限 | `secrecy: 秘密` |
+| `urgency` | 字符串 | 否 | 紧急程度 | `urgency: 加急` |
+| `signatory` | 字符串 | 否 | 签发人姓名 | `signatory: 张三` |
+| `date` | 字符串 | 否 | 成文日期，并用于版记日期 | `date: 2026年7月29日` |
+| `copyTo` | 字符串或数组 | 否 | 文末抄送机关，最多 30 项 | `copyTo: [市财政局, 市审计局]` |
+| `printingOffice` | 字符串 | 否 | 文末版记中的印发机关 | `printingOffice: 市政府办公室` |
+
+`copyTo` 支持两种写法：
+
+```yaml
+document:
+  profile: official
+  copyTo: 市发展改革委, 市财政局, 市审计局
+```
+
+```yaml
+document:
+  profile: official
+  copyTo:
+    - 市发展改革委
+    - 市财政局
+    - 市审计局
+```
+
+抄送信息不需要手工写在正文末尾，结构化主题会自动生成；印发机关和日期
+也会进入标准化版记区域。
+
+## 五、工作简报：`briefing`
+
+工作简报使用独立的刊头、期号、编发单位和报送说明。
+
+```yaml
+---
+title: 重点项目建设工作推进情况
+author: 示例市重点项目办公室
+subject: 重点项目工作简报
+keywords: [简报, 项目建设, 工作推进]
+document:
+  profile: briefing
+  masthead: 工作简报
+  issue: 2026年第12期
+  publisher: 示例市重点项目办公室
+  signatory: 王五
+  date: 2026年7月29日
+  contact: "报送：市政府领导；发送：各区人民政府、市直有关单位。编辑：综合协调处，电话：0000-12345678。"
+---
+```
+
+| 字段 | 类型 | 必填 | 功能 | 示例 |
+| --- | --- | --- | --- | --- |
+| `profile` | 固定字符串 | 是 | 启用简报结构，必须为 `briefing` | `profile: briefing` |
+| `masthead` | 字符串 | 否 | 简报顶部刊头名称 | `masthead: 工作简报` |
+| `issue` | 字符串 | 否 | 期号 | `issue: 2026年第12期` |
+| `publisher` | 字符串 | 否 | 编发单位 | `publisher: 市重点项目办公室` |
+| `signatory` | 字符串 | 否 | 签发或审核人员 | `signatory: 王五` |
+| `date` | 字符串 | 否 | 编发日期 | `date: 2026年7月29日` |
+| `contact` | 字符串 | 否 | 报送、发送、编辑及联系方式说明，最长 500 字符 | `contact: "报送：市政府领导；编辑：综合处。"` |
+
+## 六、可研与项目报告：`project-report`
+
+`project-report` 会生成项目报告封面，适合可行性研究报告、项目建议书和
+建设方案。
+
+```yaml
+---
+title: 可行性研究报告
+author: 示例工程咨询有限公司
+subject: 智慧园区建设项目可行性研究
+keywords: [可行性研究, 项目建设, 投资估算]
+document:
+  profile: project-report
+  projectName: 智慧园区一体化平台建设项目
+  documentType: 可行性研究报告
+  owner: 示例产业园区管理委员会
+  preparedBy: 示例工程咨询有限公司
+  version: 送审稿 V1.0
+  date: 2026年7月
+---
+```
+
+| 字段 | 类型 | 必填 | 功能 | 示例 |
+| --- | --- | --- | --- | --- |
+| `profile` | 固定字符串 | 是 | 启用项目报告封面，必须为 `project-report` | `profile: project-report` |
+| `projectName` | 字符串 | 否 | 项目完整名称 | `projectName: 智慧园区一体化平台建设项目` |
+| `documentType` | 字符串 | 否 | 报告类型 | `documentType: 可行性研究报告` |
+| `owner` | 字符串 | 否 | 建设、委托或申报单位 | `owner: 示例产业园区管理委员会` |
+| `preparedBy` | 字符串 | 否 | 编制单位 | `preparedBy: 示例工程咨询有限公司` |
+| `version` | 字符串 | 否 | 文件版本或送审状态 | `version: 送审稿 V1.0` |
+| `date` | 字符串 | 否 | 编制日期 | `date: 2026年7月` |
+
+封面之后直接从第一章开始书写，例如：
+
+```markdown
+# 第一章 总论
+
+## 一、项目概况
+
+本项目拟建设统一的园区管理、企业服务和运行监测平台。
+```
+
+## 七、投标文件：`tender`
+
+### 常规投标文件
+
+```yaml
+---
+title: 投标文件
+author: 示例科技有限公司
+subject: 数据中心建设项目投标文件
+keywords: [投标文件, 技术方案, 项目实施]
+document:
+  profile: tender
+  copyMark: 正本
+  projectName: 数据中心基础设施建设项目
+  projectNumber: ZB-2026-001
+  volume: 技术及商务文件
+  bidder: 示例科技有限公司
+  representative: 李四
+  date: 2026年7月29日
+---
+```
+
+### 技术暗标
+
+暗标通常省略投标人和代表信息，具体要求应以招标文件为准：
+
+```yaml
+---
+title: 技术文件
+subject: 城市运行管理平台技术暗标
+keywords: [技术暗标, 技术方案, 项目实施]
+document:
+  profile: tender
+  copyMark: 技术暗标
+  projectName: 城市运行管理平台建设项目
+  projectNumber: JS-2026-009
+  volume: 技术文件
+  date: 2026年7月
+---
+```
+
+### `tender` 字段表
+
+| 字段 | 类型 | 必填 | 功能 | 示例 |
+| --- | --- | --- | --- | --- |
+| `profile` | 固定字符串 | 是 | 启用标书封面，必须为 `tender` | `profile: tender` |
+| `copyMark` | 字符串 | 否 | 正本、副本或技术暗标标记 | `copyMark: 正本` |
+| `projectName` | 字符串 | 否 | 招标或采购项目名称 | `projectName: 数据中心基础设施建设项目` |
+| `projectNumber` | 字符串 | 否 | 项目或招标编号 | `projectNumber: ZB-2026-001` |
+| `volume` | 字符串 | 否 | 分册名称 | `volume: 技术及商务文件` |
+| `bidder` | 字符串 | 否 | 投标人名称 | `bidder: 示例科技有限公司` |
+| `representative` | 字符串 | 否 | 法定代表人或授权代表 | `representative: 李四` |
+| `date` | 字符串 | 否 | 投标或编制日期 | `date: 2026年7月29日` |
+
+## 八、普通正式文档
+
+规章制度和工作报告不一定需要结构化封面。只使用通用元数据，并在正文中
+正常书写一级标题即可：
+
+```yaml
+---
+title: 信息系统项目管理办法
+author: 示例集团有限公司
+subject: 信息系统项目管理制度
+keywords: [规章制度, 项目管理, 信息系统]
+---
+
+# 信息系统项目管理办法
+
+## 第一章 总则
+```
+
+这种写法适用于“政企正式·规章制度”和“政企正式·工作报告”。不要添加
+不存在的 `document.profile`，否则文档会显示配置错误。
+
+## 九、正文写法
+
+红头公文的 Front Matter 结束后直接书写主送机关和正文，不要再次添加
+与 `title` 相同的一级标题，否则会重复显示公文标题。
+
+```markdown
+各区人民政府，市政府各部门、各直属机构：
+
+为进一步加强全市重点项目全过程管理，现将有关事项通知如下。
+
+## 一、完善项目分级管理机制
+
+各单位应当按照投资规模、建设周期和社会影响建立动态管理台账。
+
+## 二、规范项目建设过程
+
+（一）严格执行项目建设程序。
+
+（二）建立月度调度机制。
+```
+
+## 十、页边距、页眉页脚和页码
+
+这些项目不属于 Front Matter 的 `document` 字段，而由主题推荐值和
+“导出设置”控制：
+
+| 配置 | 默认行为 | 自定义方式 |
+| --- | --- | --- |
+| 页边距 | 主题有推荐值时跟随主题，否则四边 `16mm` | 导出设置 → 页边距 → 自定义 |
+| 页眉 | 正式主题可提供推荐内容和字体 | 导出设置 → 页眉 |
+| 页脚 | 正式主题可提供推荐内容和字体 | 导出设置 → 页脚 |
+| 页码 | 红头主题可推荐 `— 1 —` 等公文式页码 | 导出设置 → 页码 |
+| 纸张与方向 | 默认 A4 纵向 | 导出设置 → 纸张 |
+
+- 国家标准红头主题使用公文式页码；
+- 双面文档页码可按奇偶页放在外侧；
+- 信函格式首页可以不显示页码；
+- 切换为“自定义”后，导出设置会覆盖主题推荐值。
+
+不要在 Front Matter 中填写 `margin`、`header`、`footer` 或 `pageNumber`
+并期待其生效；当前版本不把这些字段作为文档结构协议解析。
+
+## 十一、字体说明
+
+正式主题内置可再分发的 Fandol 中文字体资源，以减少不同电脑之间的显示
+差异：
+
+- 正文以宋体风格为主；
+- 一级结构标题使用黑体风格；
+- 二级结构标题使用楷体风格；
+- 红头机关名称使用项目内置的小标宋近似字体方案；
+- 页眉页脚使用正式文档主题规定的对应字体。
+
+内置字体用于稳定排版效果，但不声称等同于需要单独授权的商业字体。对
+字体有强制采购或归档要求的单位，应按本单位规定配置经授权字体。
+
+## 十二、常见错误
+
+| 现象 | 原因 | 处理方法 |
+| --- | --- | --- |
+| YAML 被显示成正文 | 文件开头不是 `---`，或缺少结束的 `---` | 确保 Front Matter 位于文件第一行 |
+| 提示未知字段 | `document` 使用严格字段校验 | 对照对应 profile 的字段表删除拼写错误或多余字段 |
+| 标题出现两次 | `title` 已生成结构标题，正文又写了同名 `#` 标题 | 删除正文中重复的一级标题 |
+| 抄送未显示 | `copyTo` 写在了 `document` 外层 | 将其缩进到 `document:` 下面 |
+| 主题没有自动切换 | 普通文件不能通过 Front Matter 选主题 | 手动选择主题，或从“更多 → 主题示例”打开 |
+| 页边距字段无效 | 页边距不属于文档 profile | 在导出设置中选择“跟随主题”或“自定义” |
+
+## 十三、导出前检查
+
+1. 确认标题、发文机关、发文字号和日期无误。
+2. 检查主送机关、落款和抄送信息是否完整。
+3. 暗标文件必须再次对照招标要求检查身份信息和版式限制。
+4. 使用“精确”预览核对页码、页边距和分页边界。
+5. 检查表格、图片、图表和附件说明是否跨页异常。
+6. 最终 PDF 应保持文字可搜索，并在归档前完成内容复核。