我可以使用 pandoc 中的 YAML 标头选项控制什么？

Question

我只是偶然看到一个示例文档，在要由 Pandoc 处理的 Markdown 文件中的 YAML 标头选项中使用

toc: true

行。并且 Pandoc 文档 没有提到使用 YAML 标头控制目录的此选项。此外，我在同一个 Pandoc 自述网站上的示例文档中看到了一些任意的行。

主要问题：

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

元问题：

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

注意：我的工作流程是使用 Markdown 文件（

.md

）并通过 Pandoc 处理它们以获得 PDF 文件。它用数学来分层组织手稿写作。如：

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

Answer 1

YAML 元数据中设置的几乎所有内容都只能通过使用中的 pandoc 模板 起作用。

Pandoc 模板可能包含变量。例如，在 HTML 模板中，您可以编写：

<title>$title$</title>

可以使用

--variable KEY[=VAL]

选项设置这些模板变量。

但是，它们也是从文档元数据中设置的，而文档元数据又可以通过使用以下方式设置：

• --metadata KEY[=VAL]

  选项，
• a YAML 元数据块，或

• --metadata-file

  选项。

--variable

选项将字符串逐字插入模板中，而

--metadata

转义字符串。 YAML 元数据中的字符串（也在使用

--metadata-file

时）被解释为 markdown，您可以通过使用 pandoc markdown 的 generic raw attribute 来规避这种情况。例如 HTML 输出：

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

请参阅此表了解原理图：

	--变量	--元数据	YAML 元数据和 --metadata-file
值可以是……	字符串和布尔值	字符串和布尔值	还有 YAML 对象和列表
琴弦是……	逐字插入	逃脱了	解释为降价
可通过过滤器访问：	不	是的	是的

回答您的问题：模板确定 YAML 元数据块中的哪些字段有效。例如，要查看默认的 Latex 模板，请使用：

$ pandoc -D latex

要查看 pandoc 自动设置的一些变量，请参阅手册。最后，pandoc 的其他行为（例如 Markdown 扩展等）只能设置为命令行选项（除非使用包装脚本）。

Answer 2

这是一个相当长的列表，您可以通过在命令行中运行

man pandoc

并导航到“模板”下的“pandoc 设置的变量”部分来浏览。

列表顶部包括以下许多其他选项：

Variables set by pandoc
   Some variables are set automatically by pandoc.  These vary somewhat depending  on  the
   output format, but include metadata fields as well as the following:

   title, author, date
          allow identification of basic aspects of the document.  Included in PDF metadata
          through LaTeX and ConTeXt.  These can be set through a pandoc title block, which
          allows for multiple authors, or through a YAML metadata block:

                 ---
                 author:
                 - Aristotle
                 - Peter Abelard
                 ...

   subtitle
          document subtitle; also used as subject in PDF metadata

   abstract
          document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx

   keywords
          list  of  keywords  to  be  included in HTML, PDF, and AsciiDoc metadata; may be
          repeated as for author, above

   header-includes
          contents specified by -H/--include-in-header (may have multiple values)

   toc    non-null value if --toc/--table-of-contents was specified

   toc-title
          title of table of contents (works only with EPUB and docx)

   include-before
          contents specified by -B/--include-before-body (may have multiple values)

   include-after
          contents specified by -A/--include-after-body (may have multiple values)

   body   body of document

```

Answer 3

您可以查看 pandoc 的文档以获取线索：http://pandoc.org/getting-started.html

但是要确切知道它将在哪里使用，您可以查找 pandoc 的模板源：https://github.com/jgm/pandoc-templates

例如，对于 html5 输出，文件为： https://github.com/jgm/pandoc-templates/blob/master/default.html5

这是代码的一部分：

<title>$if(title-prefix)$$title-prefix$ - $endif$$pagetitle$</title>

如您所见，它有

title-prefix

和

pagetitle

。

您可以查看文档，但最好的解决方案是查找您正在使用的版本的源代码。

Answer 4

pandoc 主页现在包含选项列表及其解释：

https://pandoc.org/MANUAL.html#variables

和看的时候好像是一样的

man pandoc

。