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

文章目录

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

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

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

一、基本转换命令

1. 最基本的转换命令

bash 复制代码

pandoc input.md -o output.docx

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

2. 模板导出命令

bash 复制代码

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

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

3. 自定义模板转换命令

bash 复制代码

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 个 # 符号后接一个空格来定义不同级别的标题。

markdown 复制代码

# 一级标题 (Word 中的 "标题 1")

## 二级标题 (Word 中的 "标题 2")

### 三级标题 (Word 中的 "标题 3")

注意事项与常见错误：

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

2. 正文 (Body Text)

正确写法：

段落之间由一个或多个空行分隔，

markdown 复制代码

这是第一个段落。这是一些示例文本。只需要连续书写，在需要换段时留出一个空行。

这是第二个段落。请注意上面的空行将它们分成了两个独立的段落。

注意事项与常见错误：

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

3. 列表 (Lists)

无序列表 (Unordered Lists)

正确写法：

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

markdown 复制代码

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

注意事项与常见错误：

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

有序列表 (Ordered Lists)

正确写法：

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

markdown 复制代码

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

注意事项与常见错误：

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

4. 表格 (Tables)

表格标题

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

写法

markdown 复制代码

: 表格标题

| 表格 | 表格 |
| --- | --- |

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

表格内容

正确写法：

Pandoc 支持多种表格语法，推荐使用"管道表"因为它最清晰。

markdown 复制代码

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

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

注意事项与常见错误：

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

5. 图片 (Images)

正确写法：

markdown 复制代码

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

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

注意事项与常见错误：

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

6. 公式 (Equations)

正确写法：

Pandoc 支持 LaTeX 数学公式。

行内公式： 使用单个 $ 包裹。
markdown 复制代码
```
勾股定理是 $a^2 + b^2 = c^2$。
```
块公式： 使用两个 $$ 包裹并独立成行。
markdown 复制代码
```
$$
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 的纯粹性。

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. 通用避免错误识别的技巧

一、基本转换命令