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> --lua-filter count-words.lua \<br> --filter special.lua |
filters: - citeproc - count-words.lua - type: json path: special.lua |
--metadata key=value \<br> --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> --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> --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> --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 |