抠丁客 抠丁客
项目
编辑 (2024/8/4)

Pandoc 用户使用指南 - Defaults 文件

--defaults 选项可以用来指定一个 YAML 格式的选项包。

省略的字段将采用其常规的默认值。因此，defaults 文件可以简单到只有一行：

verbosity: INFO

在期望文件路径（或文件路径列表）的字段中，可以使用以下语法来插值环境变量：

csl: ${HOME}/mycsldir/special.csl

也可以使用 ${USERDATA}；这将总是解析为解析 defaults 文件时的用户数据目录，无论环境变量 USERDATA 的设置如何。

${.} 将解析为包含 defaults 文件本身的目录。这允许你引用该目录中的资源：

epub-cover-image: ${.}/cover.jpg
epub-metadata: ${.}/meta.xml
resource-path:
  - . # pandoc运行时的工作目录
  - ${.}/images # 包含此defaults文件的目录下的images子目录

这种环境变量插值语法 仅 在期望文件路径的字段中有效。

可以在用户数据目录的 defaults 子目录中放置 defaults 文件，并从任何目录使用。例如，可以创建一个用于撰写信件的 defaults 文件，将其保存为 letter.yaml 在用户数据目录的 defaults 子目录中，然后从任何目录使用 pandoc --defaults letter 或 pandoc -dletter 调用这些 defaults。

当使用多个 defaults 时，它们的内容将会合并。

请注意

在可以重复命令行参数的地方（如 --metadata-file、--css、--include-in-header、--include-before-body、--include-after-body、--variable、--metadata 和 --syntax-definition），命令行上指定的值将与 defaults 文件中的值合并，而不是替换它们。

以下表格展示了命令行与 defaults 文件条目之间的映射。

命令行 defaults 文件
foo.md input-file: foo.md
foo.md bar.md input-files:
    - foo.md
    - bar.md

input-files 的值可以留空以表示从标准输入（stdin）读取输入，也可以是一个空序列 [] 表示没有输入。

常规选项

命令行 defaults 文件
--from markdown+emoji from: markdown+emoji
reader: markdown+emoji
--to markdown+hard_line_breaks to: markdown+hard_line_breaks
writer: markdown+hard_line_breaks
--output foo.pdf output-file: foo.pdf
--output - output-file:
--data-dir dir data-dir: dir
--defaults file defaults:
    - file
--verbose verbosity: INFO
--quiet verbosity: ERROR
--fail-if-warnings fail-if-warnings: true
--sandbox sandbox: true
--log=FILE log-file: FILE

在 defaults 文件中指定的选项总是优先于通过 defaults: 条目包含的另一个文件中的选项。

verbosity 可以取以下值：ERROR、WARNING 或 INFO。

读取选项

命令行 defaults 文件
--shift-heading-level-by -1 shift-heading-level-by: -1
--indented-code-classes python indented-code-classes:
    - python
--default-image-extension ".jpg" default-image-extension: '.jpg'
--file-scope file-scope: true
--citeproc \<br>&nbsp;&nbsp;--lua-filter count-words.lua \<br>&nbsp;&nbsp;--filter special.lua filters:
  - citeproc
  - count-words.lua
  - type: json
  path: special.lua
--metadata key=value \<br>&nbsp;&nbsp;--metadata key2 metadata:
  key: value
  key2: true
--metadata-file meta.yaml metadata-files:
  - meta.yaml
metadata-file: meta.yaml
--preserve-tabs preserve-tabs: true
--tab-stop 8 tab-stop: 8
--track-changes accept track-changes: accept
--extract-media dir extract-media: dir
--abbreviations abbrevs.txt abbreviations: abbrevs.txt
--trace trace: true

在默认配置文件中指定的元数据值会被解析为字面字符串文本，而不是 Markdown 格式。

过滤器如果具有 .lua 扩展名，则会假定其为 Lua 过滤器；否则，会认为是 JSON 过滤器。但是也可以明确指定过滤器类型，如示例所示。过滤器按指定的顺序运行。要包含内置的 citeproc 过滤器，请使用 citeproc 或 {type: citeproc}。

常规写入器选项

命令行 defaults 文件
--standalone standalone: true
--template letter template: letter
--variable key=val \<br>&nbsp;&nbsp;--variable key2 variables:
  key: val
  key2: true
--eol nl eol: nl
--dpi 300 dpi: 300
--wrap 60 wrap: 60
--columns 72 columns: 72
--table-of-contents table-of-contents: true
--toc toc: true
--toc-depth 3 toc-depth: 3
--strip-comments strip-comments: true
--no-highlight highlight-style: null
--highlight-style kate highlight-style: kate
--syntax-definition mylang.xml syntax-definitions:
  - mylang.xml

syntax-definition: mylang.xml
--include-in-header inc.tex include-in-header:
  - inc.tex
--include-before-body inc.tex include-before-body:
  - inc.tex
--include-after-body inc.tex include-after-body:
  - inc.tex
--resource-path .:foo resource-path: ['.','foo']
--request-header foo:bar request-headers:
  - ["User-Agent", "Mozilla/5.0"]
--no-check-certificate no-check-certificate: true

影响特定写入器的选项

命令行 defaults 文件
--self-contained self-contained: true
--html-q-tags html-q-tags: true
--ascii ascii: true
--reference-links reference-links: true
--reference-location block reference-location: block
--markdown-headings atx markdown-headings: atx
--list-tables list-tables: true
--top-level-division chapter top-level-division: chapter
--number-sections number-sections: true
--number-offset=1,4 number-offset: [1,4]
--listings listings: true
--incremental incremental: true
--slide-level 2 slide-level: 2
--section-divs section-divs: true
--email-obfuscation references email-obfuscation: references
--id-prefix ch1 identifier-prefix: ch1
--title-prefix MySite title-prefix: MySite
--css styles/screen.css \<br>&nbsp;&nbsp;--css styles/special.css css:
  - styles/screen.css
  - styles/special.css
--reference-doc my.docx reference-doc: my.docx
--epub-cover-image cover.jpg epub-cover-image: cover.jpg
--epub-title-page=false epub-title-page: false
--epub-metadata meta.xml epub-metadata: meta.xml
--epub-embed-font special.otf \<br>&nbsp;&nbsp;--epub-embed-font headline.otf epub-fonts:
  - special.otf
  - headline.otf
--split-level 2 split-level: 2
--chunk-template="%i.html" chunk-template: "%i.html"
--epub-subdirectory="" epub-subdirectory: ''
--ipynb-output best ipynb-output: best
--pdf-engine xelatex pdf-engine: xelatex
--pdf-engine-opt=--shell-escape pdf-engine-opts:
  - '-shell-escape'
pdf-engine-opt: '-shell-escape'

引文呈现

命令行 defaults 文件
--citeproc citeproc: true
--bibliography logic.bib bibliography: logic.bib
--csl ieee.csl csl: ieee.csl
--citation-abbreviations ab.json citation-abbreviations: ab.json
--natbib cite-method: natbib
--biblatex cite-method: biblatex

cite-method 可以是 citeproc、natbib 或 biblatex。这仅影响 LaTeX 输出。如果您想使用 citeproc 来格式化引文，您还应该设置 citeproc: true。

以下是您提供的英文 Markdown 内容翻译成中文并去掉 HTML 标签的版本：

如果你需要控制 citeproc 处理与其他过滤器执行的相对顺序，你应该在 filters 列表中使用 citeproc（参见 [阅读器选项]）。

HTML 中的数学呈现

命令行 defaults 文件
--mathjax html-math-method:
  method: mathjax
--mathml html-math-method:
  method: mathml
--webtex html-math-method:
  method: webtex
--katex html-math-method:
  method: katex
--gladtex html-math-method:
  method: gladtex

除了上面列出的值之外，method 还可以取值 plain。

如果命令行选项接受一个 URL 参数，可以在 html-math-method: 中添加一个 url: 字段。

包装器脚本选项

命令行 defaults 文件
--dump-args dump-args: true
--ignore-args ignore-args: true
在本文档中