专业PDF的Markdown格式设置技巧

格式良好的Markdown能生成格式良好的PDF。本指南涵盖了能对最终输出产生最大影响的技巧 — 从标题结构到表格设计再到代码块样式。

标题层级很重要

标题结构决定了文档大纲。请使用逻辑层级：

# 文档标题（h1）
## 主要部分（h2）
### 子部分（h3）
#### 细节层级（h4）

提示：

每个文档一个 h1 — 它将作为 PDF 的标题。
使用 h2 表示主要部分（引言、方法、结果、结论）。
在每个部分内使用 h3 表示子部分。
避免跳级（h2 直接到 h4，中间没有 h3）。

Legal 模板会自动为顶级章节编号，因此清晰的标题层级能让这种编号保持有意义。在任何模板中，合理的层级都能生成更清晰的文档大纲。

外观出色的表格

表格是最强大的功能之一。以下是如何让它们在 PDF 中良好运行的方法：

| 项目 | 状态 | 预算 | 负责人 |
| --- | --- | --- | --- |
| 网站重新设计 | 进行中 | ¥45,000 | 王明 |
| 移动应用 | 规划中 | ¥30,000 | 李华 |
| API 迁移 | 已完成 | ¥15,000 | 张伟 |

列对齐

在分隔行中使用冒号来控制对齐方式：

| 项目 | 数量 | 价格 |
| :--- | ---: | :---: |
| 左对齐 | 右对齐 | 居中 |
| 小部件 | 5 | ¥240 |
| 服务 | 12 | ¥1,200 |

:--- — 左对齐（默认）
---: — 右对齐（适合数字）
:---: — 居中对齐

转义管道字符

如果单元格内容包含 |，请使用反斜杠进行转义：

| 命令 | 描述 |
| --- | --- |
| `cat file \| grep error` | 在日志中查找错误 |

提示：

保持列标签简短：过长的标题会创建可能溢出的宽列。
限制在 4-5 列：列数过多在 A4/Letter 纸上难以阅读。
导出前预览：宽表格可能需要更短的标签。

带语法高亮的代码块

用三个反引号和语言标签包裹代码。PDF 会自动应用语法高亮。

基本语法

```python
def calculate_growth(revenue: list[float]) -> float:
    if len(revenue) < 2:
        return 0.0
    return (revenue[-1] - revenue[-2]) / revenue[-2] * 100
```

常见语言

语言	标签
Python	`python`
JavaScript	`javascript`
TypeScript	`typescript`
Bash / Shell	`bash`
SQL	`sql`
JSON	`json`
YAML	`yaml`
HTML	`html`
CSS	`css`
Rust	`rust`
Go	`go`
Java	`java`
C++	`cpp`

示例：JSON 配置

```json
{
  "name": "quarterly-report",
  "templateId": "executive",
  "options": {
    "pageNumbers": true
  }
}
```

示例：Shell 命令

```bash
curl -X POST https://api.example.com/v1/reports \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"period": "Q3", "format": "pdf"}'
```

提示：

始终包含语言标签 — 没有标签则不会有高亮。
对于简短的引用，使用内联反引号 `代码`，例如 文件名 或 true。
为保持页面整洁，代码块控制在 50 行以内。

PDF 中的图像

![公司标志](https://example.com/logo.png)

要求：

图像必须是可公开访问的 URL（而非本地文件）。
支持的格式：PNG、JPEG、WebP。
图像会自动缩放以适应页面宽度。

提示：

对于自定义模板中的标志，请使用图片上传功能而非 Markdown 图片。
保持图像在 2MB 以下以实现快速渲染。
使用描述性的替代文本 — 当图像加载失败时会显示该文本。

用于标注的块引用

> **关键发现**：营收同比增长 15%，超出我们第三季度预测 3 个百分点。

块引用带有左边框和缩进。用于：

关键发现或要点
客户引用或推荐语
重要说明或警告
外部来源的摘录

列表 — 项目符号和编号

### 主要交付物

- 第四季度营销计划
  - 社交媒体日历
  - 电子邮件活动安排
- 预算分配
  - 部门明细
  - 应急储备金

### 行动项目

1. 与利益相关者审阅草案
2. 在周五前整合反馈意见
3. 提交最终版本以供审批
4. 存档以前版本

提示：

对于无序项目使用项目符号列表。
对于顺序步骤使用编号列表。
列表最多可嵌套 3 层。
在列表前后留空行以确保适当的间距。

链接和引用

详情请参阅 [API 文档](https://markdowntopdfconverter.com/api-docs)。

如有疑问，请联系 [support@markdowntopdfconverter.com](mailto:support@markdowntopdfconverter.com)。

链接在 PDF 中可点击。请使用描述性的链接文本 — 避免使用"点击此处"。

Mermaid 图表

使用 Mermaid 语法直接在 Markdown 中添加图表。它们在 PDF 中呈现为清晰的矢量图形。Mermaid 渲染需要高级计划。

每个图表以 ```mermaid 开头，下一行紧跟类型关键字。

流程图

展示流程、决策和工作流。

```mermaid
graph TD
    A[Start] --> B{Is approved?}
    B -->|Yes| C[Publish]
    B -->|No| D[Revise]
    D --> B
    C --> E[Done]
```

关键点：graph TD = 从上到下。使用 LR 表示从左到右。[] = 矩形，() = 圆角，{} = 菱形，--> = 箭头，-->|标签| = 带标签的箭头。

时序图

展示参与者之间随时间变化的交互。

```mermaid
sequenceDiagram
    Client->>Server: POST /api/convert
    Server->>Gotenberg: Render PDF
    Gotenberg-->>Server: PDF binary
    Server-->>Client: 200 OK (PDF)
```

关键点：->> = 实线箭头，-->> = 虚线响应。参与者根据名称自动创建。

甘特图

使用时间条规划项目。

```mermaid
gantt
    title Q3 Launch
    dateFormat  YYYY-MM-DD
    section Design
    Wireframes    :2026-07-01, 7d
    Prototype     :2026-07-08, 5d
    section Build
    Frontend      :2026-07-13, 10d
    Backend       :2026-07-13, 12d
    section Launch
    QA            :2026-07-25, 4d
    Go Live       :milestone, 2026-07-30, 0d
```

关键点：section 对任务进行分组。格式：任务名称 :开始, 持续时间。milestone 标记单一日期。

饼图

简单的比例数据。

```mermaid
pie title Revenue by Region
    "North America" : 45
    "Europe" : 30
    "APAC" : 25
```

类图

展示技术文档的对象关系。

```mermaid
classDiagram
    User <|-- Admin
    User : +String email
    User : +login()
    Admin : +manageUsers()
    Report *-- User
    Report : +String title
    Report : +generatePdf()
```

关键点：<|-- = 继承，*-- = 组合。+ = 公共方法/字段。

其他类型

还支持：状态图、实体关系图、旅程地图、Git 图谱和象限图。完整语法参考请访问 mermaid.js.org。

提示：

Mermaid 以 SVG 格式渲染 — 在任何缩放级别下都保持清晰。
对于图表密集的文档，请使用 Creative 模板（它会预先设置图表容器的大小）。
图表会自动适应页面宽度。保持节点标签简洁以避免溢出。
导出前在实时预览中测试复杂图表。

文档结构检查清单

导出前，请验证：

顶部有一个 h1 标题
逻辑标题层级（h1 → h2 → h3）
表格列数一致
代码块包含语言标签
图像包含描述性替代文本
链接使用描述性文本
列表前后有空行
无 HTML 标签（使用纯 Markdown）

下一步

在带实时预览的转换器中尝试这些技巧。
了解如何设计使用您品牌字体的自定义模板。
比较全部九种内置模板，为您的内容找到最合适的模板。