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

Question

我只是偶然地看到一个示例文档,它使用toc: trueMarkdown文件中的YAML头选项中的行来由Pandoc处理.并且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

实际上,它都包含在Pandoc的手册中.特别:

模板可能包含变量.

例如,在HTML 模板中,您可以编写:

<title>$title$</title>

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

但是,它们也是根据文档元数据设置的,而元数据又可以通过以下方式设置:

• 该--metadata KEY[=VAL]选项,
• 一个YAML元数据块,或
• 该--metadata-file选项.

该--variable选项插入串逐字到模板,而--metadata逃逸的字符串.YAML元数据中的字符串(也在使用时--metadata-file)被解释为markdown,您可以通过使用pandoc markdown的通用原始属性来规避它.例如,对于HTML输出:

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

有关vs vs YAML元数据的示意图,--variable KEY[=VAL]--metadata KEY[=VAL]请参阅此表.

要回答您的问题:模板确定YAML元数据块中的哪些字段有效.例如,要查看乳胶模板,请使用:

|                        | --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                               |

要查看由pandoc自动设置的某些变量,请参阅手册.最后,pandoc的其他行为(例如markdown扩展等)只能设置为命令行选项(使用包装器脚本时除外).

Answer 2

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

```