Pandoc 用户使用指南 - 自定义样式

可以在 docx、odt 和 ICML 格式中使用自定义样式。

输出

默认情况下，Pandoc 在生成 odt、docx 和 ICML 格式的输出时会应用一组预定义的样式给段落和块引用等块元素，并主要使用默认格式化（如斜体、加粗）给内联元素。这在大多数情况下都是适用的，尤其是在配合 参考文档文件 使用时。但是，如果你需要将自定义样式应用于块元素，或匹配已有的样式集，Pandoc 允许你使用 div 和 span 分别为块和文本定义自定义样式。

如果你定义了一个带有 custom-style 属性的 div 或 span，Pandoc 将会将你指定的样式应用于包含的元素（除了那些依赖于特定样式的元素，如标题、代码块、块引用或链接）。因此，例如，使用括号包围的 spans 语法，

[Get out]{custom-style="Emphatically"}, he said.

将会产生一个文件，其中 "Get out" 被应用了名为 "Emphatically" 的字符样式。类似地，使用带围栏的 divs 语法，

Dickinson 开始这首诗很简单：

::: {custom-style="Poetry"}
| A Bird came down the Walk---
| He did not know I saw---
:::

将会使这两行文本以 "Poetry" 段落样式呈现。

如果这些样式还没有出现在你的 参考文档文件 中，那么在输出文件中它们会被定义为继承自正常文本（docx）或默认段落样式（odt）。如果它们已经被定义，Pandoc 不会对这些定义进行更改。

此特性与 Pandoc 过滤器 结合使用时可提供最大程度的定制性。如果你想让所有块引用后的段落都缩进，你可以编写一个过滤器来应用必要的样式。如果你想把所有的斜体文字转换为 Emphasis 字符样式（也许是为了改变其颜色），你可以编写一个过滤器将所有的斜体文本转换为带有 Emphasis 自定义样式的 span 中的文本。

对于 docx 或 odt 输出，你不需要启用任何扩展即可让自定义样式生效。

输入

docx 读取器默认只读取它可以转换成 Pandoc 元素的样式，这些转换可以通过直接转换或者解释输入文档样式之间的派生关系来完成。

通过在 docx 读取器中启用 styles 扩展 ( -f docx+styles )，你可以生成保持输入文档样式的输出，使用 custom-style 类来实现这一点。段落样式被解释为 div，而字符样式则被解释为 span。

例如，使用测试目录中的 custom-style-reference.docx 文件，我们会有以下不同的输出：

没有使用 +styles 扩展的情况下：

$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
This is some text.

This is text with an *emphasized* text style. And this is text with a
**strengthened** text style.

> Here is a styled paragraph that inherits from Block Text.

而使用了扩展的情况下：

$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown

::: {custom-style="First Paragraph"}
This is some text.
:::

::: {custom-style="Body Text"}
This is text with an [emphasized]{custom-style="Emphatic"} text style.
And this is text with a [strengthened]{custom-style="Strengthened"}
text style.
:::

::: {custom-style="My Block Style"}
> Here is a styled paragraph that inherits from Block Text.
:::

使用这些自定义样式，你可以在创建 docx 输出时将你的输入文档作为参考文档（见下文），并在输入和输出文件中保持相同的样式。