我可以用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]选项设置这些模板变量。

然而，它们也是从文档元数据中设置的，而文档元数据又可以通过使用来设置

• CCD_ 4选项
• YAML元数据块，或
• CCD_ 5选项

--variable选项将字符串逐字插入到模板中，而--metadata转义字符串。YAML元数据中的字符串（也在使用--metadata-file时）被解释为markdown，您可以通过使用pandoc markdown的通用原始属性来规避它。例如HTML输出：

`<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元数据块中的哪些字段具有效果。例如，要查看默认的乳胶模板，请使用：

$ pandoc -D latex

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

Answer 2

这是一个相当长的列表，您可以通过在命令行中运行man pandoc并导航到"TEMPLATES"下的"Variables set by 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时的一样。