Markdown转换为Word：Pandoc模板使用指南 - 实践

文章目录

一、基本转换命令
- 1. 最基本的转换命令
- 2. 模板导出命令
- 3. 自定义模板转换命令
二、各部分语法详解与注意事项
- 1. 标题 (Headings)
- 2. 正文 (Body Text)
- 3. 列表 (Lists)
- - 无序列表 (Unordered Lists)
  - 有序列表 (Ordered Lists)
- 4. 表格 (Tables)
- - 表格标题
  - 表格内容
- 5. 图片 (Images)
- 6. 公式 (Equations)
- 7. 代码块 (Code Blocks)
- 8. 通用避免错误识别的技巧

在上篇文章中《一文丝滑使用Markdown：从写作、绘图到转换为Word与PPT》，我们介绍了Markdown的使用，并简单介绍了如何将Markdown文档转换为Word文档。

现在我们更深入的了解一下Pandoc模板，正确地编写 Markdown 语法，以便在使用 Pandoc 的默认模板转换为 Word 文档 (.docx) 时，获得与预期一致的格式。Pandoc 是一个非常强大的文档转换工具，但为了获得最佳效果，遵循其预期的 Markdown 语法至关重要。

一、基本转换命令

1. 最基本的转换命令

pandoc input.md -o output.docx

这条命令会使用 Pandoc 的内置默认模板将 input.md 文件转换为 output.docx 文件。所有格式都依赖于 Pandoc 对 Markdown 的解析和 Word 模板的默认样式。

2. 模板导出命令

pandoc -o custom-reference.docx --print-default-data-file reference.docx

这条命令可以将Pandoc默认模板导出到当前文件夹。导出模板后，我们就可以在这个模板上将样式设置为我们需要的格式，在后续的转换中，作为自定义模板使用。

3. 自定义模板转换命令

pandoc my-document.md --reference-doc=custom-reference.docx -o my-final-document.docx

这条命令会使用我们的自定义模板将 my-document.md 文件转换为 my-final-document.docx 文件。所有格式都依赖于 Pandoc 对 Markdown 的解析和自定义模板的样式。

二、各部分语法详解与注意事项

1. 标题 (Headings)

正确写法：
使用 1-6 个 # 符号后接一个空格来定义不同级别的标题。

# 一级标题 (Word 中的 "标题 1")
## 二级标题 (Word 中的 "标题 2")
### 三级标题 (Word 中的 "标题 3")

注意事项与常见错误：

空格是必须的：#标题 不会被识别为标题，必须写成 # 标题。
不要跳过级别： 虽然 Markdown 本身不强制，但为了良好的结构和在 Word 中生成正确的目录，建议按顺序使用标题级别（例如，不要在一级标题后直接使用三级标题）。

2. 正文 (Body Text)

正确写法：
段落之间由一个或多个空行分隔，

这是第一个段落。这是一些示例文本。只需要连续书写，在需要换段时留出一个空行。
这是第二个段落。请注意上面的空行将它们分成了两个独立的段落。

注意事项与常见错误：

硬换行（单行换行）： 在 Markdown 中，单一的换行符不会在最终输出中显示为换行。如果你需要强制换行，可以在行尾添加两个空格，或者使用   标签。
- 行尾两个空格 （不直观，但标准）
- 行尾的 HTML 标签 （更直观）
避免意外连接： 如果没有空行，两行文本会被合并成一个段落，可能导致格式混乱。

3. 列表 (Lists)

无序列表 (Unordered Lists)

正确写法：

使用 *, +, 或 - 后接一个空格；
无序列表前有一个或多个空行与上文其他内容进行分割，否则word中不会被转换为无序列表

- 项目一
- 项目二- 子项目二（缩进两个或四个空格）
- 项目三

注意事项与常见错误：

一致性： 在同一份文档中，最好使用同一种符号（推荐使用 -）。
缩进： 子列表的符号必须与父列表的文本对齐，通常缩进 2 或 4 个空格。
空行： 无序列表项之间如果有空行，转换后，Word中也会相应有空行。
空格： 无序列表项结尾空两格，若下一行为正文段落，则转换后正文与无序列表保持相同缩进。

有序列表 (Ordered Lists)

正确写法：

使用数字后接一个点和一个空格。
有序列表前有一个或多个空行与上文其他内容进行分割，否则word中不会被转换为有序列表

1. 第一项
2. 第二项1. 第二项的子项（缩进四个空格）
3. 第三项

注意事项与常见错误：

数字顺序无关紧要： Pandoc 会自动校正数字顺序。即使你全部写成 1.，输出也会是正确的顺序。但为了源文件的可读性，建议使用正确的数字。
缩进规则： 与无序列表相同，子列表需要正确缩进。

4. 表格 (Tables)

表格标题

markdown中没有表格标题这一样式，但是在模板中可以设置

写法

: 表格标题
| 表格 | 表格 |
| --- | --- |

表标题需要前后各有一个空行，方可在转换时识别为表标题。

表格内容

正确写法：
Pandoc 支持多种表格语法，推荐使用“管道表”因为它最清晰。

| 左对齐 | 居中对齐 | 右对齐 |
| :------ | :------: | -----: |
| 单元格 | 单元格   | 单元格 |
| 第二行 | 数据     |  $100  |

:- 表示左对齐，:-: 表示居中对齐，-: 表示右对齐。

注意事项与常见错误：

管道 | 并非绝对必须： 但强烈建议使用，可以极大地提高源文件的可读性。
表头分隔线必须存在： 第二行的 |---| 是必须的，用于区分表头和表格主体。
单元格内换行： 在 Markdown 单元格内换行比较困难，通常建议在 Word 中后期微调，或者使用简单的 HTML   标签。

5. 图片 (Images)

正确写法：

![图片的替代文本(描述文字)](path/to/your/image.jpg "可选标题")

替代文本：图片无法显示时的文字描述，对于无障碍访问至关重要。
path/to/your/image.jpg：图片文件的路径（相对路径或绝对路径）。
"可选标题"：鼠标悬停时显示的文本，在 Word 中通常会被转换为图片下方的题注。

注意事项与常见错误：

路径错误： 这是最常见的问题。确保图片路径相对于 Markdown 文件是正确的。建议将图片和 .md 文件放在同一目录或附近的子目录中。
Pandoc 不会嵌入图片： 使用默认命令转换时，Pandoc 只会告诉 Word 图片的路径。如果 Word 打不开这个路径，图片就会丢失。解决方案：使用 --extract-media 参数让 Pandoc 将图片提取并嵌入到 .docx 中。
```
pandoc input.md --extract-media=. -o output.docx
```

6. 公式 (Equations)

正确写法：
Pandoc 支持 LaTeX 数学公式。

行内公式： 使用单个 $ 包裹。
```
勾股定理是 $a^2 + b^2 = c^2$。
```
块公式： 使用两个 $$ 包裹并独立成行。
```
$$
E = mc^2
$$
```

注意事项与常见错误：

空格： 在 $ 和公式内容之间不要加空格，例如 $ formula $ 是错误的。
Word 需要支持： 转换后的 Word 文档中的公式是 Office 的本地公式格式（OMML），所有现代版本的 Microsoft Word 都支持。

7. 代码块 (Code Blocks)

正确写法：

围栏代码块 (推荐)： 使用三个反引号 ```````````或三个波浪号 ~~~ 包裹代码，并可在开头指定语言以实现语法高亮。
```
```python
def hello_world():print("Hello, World!")
```
```
缩进代码块： 缩进四个空格或一个制表符。这种方式不易读，尤其是在列表内部时缩进容易混乱。

注意事项与常见错误：

指定语言： 即使 Pandoc 转换到 Word 时不进行语法高亮，指定语言也是一个好习惯，有助于保持文档的语义。
避免转义： 如果你需要在代码块中包含围栏本身，可以使用更多数量的反引号来包裹，例如 ```````。

8. 通用避免错误识别的技巧

空行是分隔符： 几乎所有格式错误都是由于缺少空行导致的。在标题、列表、代码块等块级元素之后，务必用空行将其与后面的内容分开。
转义特殊字符： 如果你需要文本中显示 Markdown 的特殊字符（如 *, #, _），请在它们前面加上反斜杠 \ 进行转义。
- 例如：\*这不是斜体\* 会显示为 这不是斜体。
使用原始 HTML 作为最后手段： 如果某种格式 Pandoc 无法直接支持（例如，复杂的多列布局、特定颜色），可以在 Markdown 中直接使用 HTML 标签（如 红色文字）。Pandoc 会将这些 HTML 传递给 Word。但应谨慎使用，因为这破坏了 Markdown 的纯粹性。