我可以使用 pandoc 中的 YAML 标头选项控制什么? [英] What can I control with YAML header options in pandoc?

问题描述

我偶然看到了一个示例文档，该示例文档在要由 Pandoc 处理的 Markdown 文件中的 YAML 标头选项中使用 toc: true 行.Pandoc docs 没有提到这个选项来使用 YAML 标头控制目录.此外，我在同一个 Pandoc 自述站点上的示例文档中看到了一些随意的行.

Only by chance did I see an example document using the toc: true line in their YAML header options in a Markdown file to be processed by Pandoc. And the Pandoc docs didn't mention this option to control table of contents using the YAML header. Furthermore, I see somewhat arbitrary lines in example documents on the same Pandoc readme site.

主要问题:

• 使用 YAML 标头可以使用哪些 Pandoc 选项?

元问题:

• 什么决定了可使用 YAML 标头设置的可用 Pandoc 选项?

注意:我的工作流程是使用 Markdown 文件(.md)，通过 Pandoc 处理得到 PDF 文件.它具有分层组织的数学手稿写作.如:

Note: my workflow is to use Markdown files (.md) and process them through Pandoc to get PDF files. It has hierarchically organized manuscript writing with math. Such as:

pandoc --standalone --smart \
    --from=markdown+yaml_metadata_block \
    --filter pandoc-citeproc \
    my_markdown_file.md \
    -o my_pdf_file.pdf

推荐答案

在 YAML 元数据中设置的几乎所有内容都只通过 pandoc 模板正在使用中.

Almost everything set in the YAML metadata has only an effect through the pandoc template in use.

Pandoc 模板可能包含变量.例如，在您的 HTML 模板中，您可以编写:

Pandoc templates may contain variables. For example in your HTML template, you could write:

<title>$title$</title>

这些模板变量可以使用 --variable KEY[=VAL] 选项设置.

These template variables can be set with the --variable KEY[=VAL] option.

但是，它们也是从文档元数据中设置的，而后者又可以通过以下方式进行设置:

However, they are also set from the document metadata, which in turn can be set either by using:

• --metadata KEY[=VAL] 选项，
• a YAML 元数据块，或
• --metadata-file 选项.

• the --metadata KEY[=VAL] option,
• a YAML metadata block, or
• the --metadata-file option.

--variable 选项将字符串逐字插入模板，而 --metadata 将字符串转义.YAML 元数据中的字符串(也在使用 --metadata-file 时)被解释为 Markdown，您可以使用 pandoc markdown 的 通用原始属性.例如对于 HTML 输出:

The --variable options inserts strings verbatim into the template, while --metadata escapes strings. Strings in YAML metadata (also when using --metadata-file) are interpreted as markdown, which you can circumvent by using pandoc markdown's generic raw attributes. For example for HTML output:

`<script>alert()</script>`{=html}

请参阅此原理图表格:

|                        | --variable        | --metadata        | YAML metadata and --metadata-file |
|------------------------|-------------------|-------------------|-----------------------------------|
| values can be…         | strings and bools | strings and bools | also YAML objects and lists       |
| strings are…           | inserted verbatim | escaped           | interpreted as markdown           |
| accessible by filters: | no                | yes               | yes                               |

回答您的问题:模板决定了 YAML 元数据块中的哪些字段会产生影响.例如，要查看默认的 Latex 模板，请使用:

To answer your question: the template determines what fields in the YAML metadata block have an effect. To view, for example, the default latex template, use:

$ pandoc -D latex

要查看 pandoc 自动设置的一些变量，参见手册.最后，pandoc 的其他行为(例如降价扩展等)只能设置为命令行选项(使用 包装脚本).

To see some variables that are set automatically by pandoc, see the Manual. Finally, other behaviours of pandoc (such as markdown extensions, etc) can only be set as command-line options (except when using a wrapper script).

这篇关于我可以使用 pandoc 中的 YAML 标头选项控制什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！