厚缊

Pandoc 用户手册(二)

厚缊 / 2018-09-02


选项

通用选项

-f FORMAT-r FORMAT--from=FORMAT--read=FORMAT指定输入格式,可以是以下任何一种格式:

commonmark,creole,docbook,docx,epub,fb2,gfm,haddock,html,
html4,icml,jats,json,latex,man,markdown,markdown_mmd,
arkdown_phpextra,markdown_strict,mediawiki,ms,muse,native,
odt,opml,opendocument,org,plain,pptx,rst,rtf,texinfo,
textile,slideous,slidy,dzslides,revealjs,s5,tei,zimwiki,
自定义lua写出设备路径,查看后文自定义写出设备。

注意,odtdocxepub输出除非强制使用-o -选项,否则不会输出到标准输出。

扩展可以通过在格式名后追加+EXTENSION-EXTENSION选项独立地开启或者关闭。查看后文扩展部分的扩展列表、--list-output-formats--list-extensions

-o FILE, –output=FILE 把输出写入到文件FILE而不是默认的标准输出。如果FILE文件为-,即使指定的是非文本输出格式(docx, odt, epub2, epub3),结果也会输出到标准输出。

–data-dir=DIRECTORY 指定用户的数据文件夹供pandoc搜索数据文件,若该选项没有设定,将会使用默认的数据文件夹搜索路径。在UNIX中:

$HOME/.pandoc

在Windows XP系统中:

C:\Documents And Settings\USERNAME\Application Data\pandoc

在Windows Vista或更高版本中:

C:\Users\USERNAME\AppData\Roaming\pandoc

可以通过查看pandoc --version输出结果找到你的系统上默认的数据文件夹。该目录下的reference.odt, reference.docx, epub.css, templates, slidy, slideous, s5 文件夹会覆盖pandoc一般的默认设置。

–bash-completion 生产bash自动补全脚本。要使bash支持pandoc自动补全,需要添加如下脚本到.bashrc文件中:

eval "$(pandoc --bash-completion)"

–verbose 给出详细的调试结果输出(debugging output)。目前这只对PDF输出格式起作用。

–quiet 抑制警告信息。

–fail-if-warnings 若有任何警告,以错误状态退出程序。

–log=FILE 把日志信息以机器可读的JSON格式输出到FILE文件。上面所有调试级别的信息都会输出,会忽略详细设定(--verbose, --quiet)。

–list-input-formats 列出所有支持的输入格式。

–list-output-formats 列出所有支持的输出格式。

–list-extensions[=FORMAT] 列出支持的扩展,前缀+-表示在FORMAT格式中该扩展默认是开启还是关闭。若没有指定FORMAT,默认是pandoc markdown格式。

–list-highlight-languages 列出支持语法高亮的语言。

–list-highlight-styles 列出支持的语法高亮风格。查看--highlight-style

-v, –version 打印版本信息。

-h, –help 显示帮助信息。

读取器选项

–base-header-level=NUMBER 指定标题的基准层,默认是1。

–strip-empty-paragraphs 相对的,可以使用--strip-empty-paragraphs选项。忽略空的段落。该选项在转换用户用空段落增加段间距的文字处理文档时非常有用。

–indented-code-classes=CLASSES 指定代码块缩进类型,例如perlnumberLineshaskell。多种类型之间用空格或逗号分隔。

–default-image-extension=EXTENSION 指定当路径、URL地址不带扩展名时默认的图片扩展名。这一特性使我们能针对需要不同类型图片的格式使用相同的原文本。当前这一选项仅对markdown和LaTeX起作用。

–file-scope 在合并多个文档前单独解析每一个文档。这是不同文件中的脚注拥有预期一样的相同标识符。如果设定了这个选项,在跨文件时,脚注和链接均不起作用。读取二进制文件(docx, odt, epub)意味着设定--file-scope选项。

-F PROGRAM, –filter=PROGRAM 指定一个可执行文件,在输入解析之后和输出写出之前,用作对pandoc AST进行转换的过滤器。可执行文件能从标准输入读取JSON数据,也能将JSON写到标准输出。JSON格式须被格式化为pandoc自身的JSON输入输出。输出格式的名字传递给过滤器作为第一个参数。因此,

pandoc --filter ./caps.py -t latex

等价于:

pandoc -t json | ./caps.py latex | pandoc -f json -t latex

后一种形式对于调试过滤器是很有用的。

过滤器可以用任何语言来写。Text.Pandoc.JSON导出了toJSONFilter使得用Haskell写过滤器变得容易。更愿意用Python写过滤器的可使用pandocfilters模块,需要从PyPI安装。当然,还有PHPperlJavaScript/node.js等语言的pandoc过滤器库。

按照优先等级,pandoc将会按照以下顺序搜索过滤器:

  1. 指定完整或相对路径(可执行或不可执行的)
  2. $DATADIR/filters(可执行或不可执行的),其中$DATADIR是用户数据文件夹(查看前文--data-dir)。
  3. $PATH(必须是可执行的)

过滤器和LUA过滤器按命令行指定的顺序使用。

–lua-filter=SCRIPT 以和JSON过滤器类似的样式转换文档(查看--filter),但使用的是pandoc内置的lua过滤器系统。给定的lua脚本会返回lua过滤器列表,这些过滤器会按顺序使用。每个lua过滤器都必须包含由使用过滤器函数的AST元素名索引的元素转换函数。

pandoc lua模块为元素创建提供帮助函数。它总是加载到脚本的Lua环境中。

下面是lua脚本宏扩展的示例。

function expand_hello_world(inline)
  if inline.c == '{{helloworld}}' then
    return pandoc.Emph{ pandoc.Str "Hello, World" } 
  else
    return inline
  end
end

return {{Str = expand_hello_world}}

在优先级顺序上,pandoc将按如下顺序搜索lua过滤器:

  1. 指定完整或相对路径(可执行或不可执行的)
  2. $DATADIR/filters(可执行或不可执行的),其中$DATADIR是用户数据文件夹(查看前文--data-dir)。

-MKEY[=VAL],–metadata=KEY[:VAL] 设置元数据字段KEY的值为VAL。命令行中指定的值将覆盖文档YAML元数据块中的设定的值。值会被解析为YAML布尔值或字符串。若没有指定值,将被视为布尔值true。和--variable类似,--metadata导致模板变量的设置。但和--variable不同的是,--metadata影响后续文档的元数据(可从过滤器访问,并且可以以某种输出格式输出),元数据值将在插入模板时被转义。

-p, –preserve-tabs 保留制表符(tabs),而不是将它们转换为空格(默认值)。请注意,这只会影响literal code spans和代码块中的制表符;常规文本中的制表符将被视为空格。

–tab-stop=NUMBER 指定每一个制表符代表的空格数(默认是4)。

–track-changes=accept|reject|all 指定如何处理由MS Word“跟踪修订”功能生成的插入、删除和注释。accept(默认),插入所有的插入的内容,忽略所有删除的内容。reject插入所有的删除的内容,忽略所有插入的内容。all放入插入、删除和注释,分别用insertiondeletioncomment-startcomment-end类进行修饰包装。作者和改变时间包括在内。all对写脚本是有用的:只接受某个审阅者,或在某个日期之前的更改。如果一个段落被插入或删除,--track-changes=all在受影响的段落中断之前生成一个paragraph-insertion/paragraph-deletion类的span。此选项仅影响Dox读取器。

–extract-media=DIR 提取包含在或由源文档链接到的路径DIR的图片和其他多媒体,必要时创建该路径,并调整文档中的图像引用,以便它们指向提取的文件。如果源格式是二进制容器(docx、epub或odt),则从容器中提取媒体并使用原始文件名。否则,从文件系统读取或下载媒体,并基于内容的SHA1 hash值创建新的文件名。

–abbreviations=FILE 指定自定义的缩写文件,其中每个缩写为一行。如果未指定此选项,pandoc将从用户数据目录读取数据文件abbreviations,或依赖于系统默认值。若要查看系统默认值,请使用pandoc --print-default-data-file=abbreviations。pandoc产生这些列表的唯一用途是在markdown读取器中。在这个列表中找到的以句点结尾的字符串后跟一个不间断空白,因此该句点不会像LaTeX格式那样,产生句子结尾空白。

一般写出器选项

-s, –standalone 用适当的页眉和页脚生成输出(例如独立的HTML、LATEX、TEI或RTF文件,而不是片段)。此选项对PDF、EPUB、EPUB3、FB2、DOX和ODT输出会自动设置。对于本地输出,此选项会将导致输出中包含元数据;否则,元数据将被抑制。

–template=FILE|URL 使用指定的文件作为生成文档的自定义模板。意味着--standalone。有关模板语法的说明,请参阅下文的模板部分。如果没有指定扩展,则将添加与写入器对应的扩展,以便--template=special查找用于HTML输出的special.html。如果没有找到模板,pandoc将在用户数据目录的templates子目录中搜索它(参见--data-dir)。如果不使用此选项,将使用适合于输出格式的默认模板(参见-D/--print-default-template)。

-VKEY[=VAL],–variable=KEY[:VAL] 在独立模式下渲染文档时,将模板变量KEY设置为Val。这通常只在用--template选项指定自定义模板时才有用,因为pandoc自动设置默认模板中使用的变量。如果没有指定VAL,则KEY该将被赋予该值为true

-D FORMAT, –print-default-template=FORMAT 打印输出格式的系统默认模板(用-t查看可用的格式列表),忽略用户数据目录中的模板。

–print-default-data-file=FILE 打印系统默认数据文件,用户数据目录中的文件被忽略。

–eol=crlf|lf|native 手动指定行结束符:crlf(Windows)、lf(macOS/Linux/UNIX)或native(适合运行pandoc的OS的行结束符)。默认是native

–dpi=NUMBER 对从像素到英寸/厘米的转换指定dpi(点/英寸)值,反之亦然的。默认值是96 dpi。从技术上讲,正确的术语是ppi(像素/英寸)。

–wrap=auto|none|preserve 决定文本是如何包装在输出中的(源代码,而不是渲染版本)。使用auto(默认值),pandoc将尝试将行包装到由--columns指定的列宽度(默认值72)。使用none,pandoc根本不会包装输出。使用preserve,pandoc将尝试从源文档中保存包装(即,在源文档中存在非语义换行的情况下,输出中也将存在非语义换行)。自动包装在HTML输出中目前不起作用。

–columns=NUMBER 指定行的字符长度。这会影响生成的源代码中的文本包装(见--wrap)。它还影响纯文本表的列宽度的计算(见下文表格部分)。

–toc, –table-of-contents 在输出文档中包括自动生成的目录(或者在latex、context、docx、odt、opendocument、rst或ms中,创建内容的指令)。除非使用-s/--standalone,否则该选项对man、DoBooC4、DoBooD5或JATS输出没有影响。

–toc-depth=NUMBER 指定目录深度,默认值是3(这意味着1、 2和3级标题将被列在目录中)。

–strip-comments 删除Markdown或Textile源文件中的HTML注释,而不是将它们作为原HTML传递给Markdown、Textile或HTML输出。当未设置markdown_in_html_blocks扩展时,这不适用于原始HTML块内的HTML注释。

–no-highlight 禁用代码块和行内代码的语法高亮,即使在给出语言属性时也是如此。

–highlight-style=STYLE|FILE 指定源代码语法高亮的颜色样式。选项是pygments(默认)、katemonochromebreezeDarkespressozenburnhaddocktango。有关pandoc语法高亮的更多信息,请参见下文的语法高亮部分。也可以查看--list-highlight-styles

除了指定样式名,可以提供带有.theme扩展名的JSON文件。这将被解析为KDE语法高亮主题和(如果有效)用作语法高亮样式。

若要生成现有样式的JSON版本,请使用--print-highlight-style

–print-highlight-style=STYLE|FILE 打印一个语法高亮样式的JSON版本,该样式可以被修改,保存.theme扩展,并与--highlight-style一起使用。

–syntax-definition=FILE 指示pandoc加载KDE XML语法定义文件,该文件将用于适当标记的代码块的语法高亮。这可用于添加对新语言的支持或使用更改现有语言语法定义。

-H FILE, –include-in-header=FILE 在文档正文的开头(例如,在HTML中的<body>标记之后,或LaTeX中的begin{document}命令之后)逐字包含FILE的内容。这可以用于在HTML文档中包含导航栏或横幅。此选项可重复使用以包含多个文件。它们将被包括在指定的顺序中。意味着--standalone

-A FILE, –include-after-body=FILE 在文档主体的末尾(在HTML中的</body>标记之前,或LaTeX中的\end{document}命令之前)逐字包含FILE的内容。此选项可重复使用以包含多个文件。它们将按指定顺序列入。意味着--standalone

–resource-path=SEARCHPATH 搜索图像和其他资源的路径列表。在Linux、UNIX和MACOS系统上,路径应该用“:”分开,在Windows上用“;”分开。如果--resource-path未设定,则默认资源路径是工作目录。注意,如果指定了--resource-path,必须明确列出工作目录,否则将不会搜索工作目录。例如--resource-path=.:test将按顺序查找工作目录和test子目录。

–request-header=NAME:VAL 当进行HTTP请求时(例如,当在命令行上给出URL时,或者当必须下载文档中使用的资源时),将请求头NAME设置为值VAL。如果使用代理,还需要将环境变量http_proxy设置为http://...

特殊输出器选项

–self-contained 使用data:URI生成没有外部依赖关系的独立HTML文件,以合并链接的脚本、样式表、图像和视频的内容。意味着--standalone。所得到的文件应该是“自包含的”,即它不需要外部文件,也不需要浏览器正确显示的网络访问权限。这个选项只适用于HTML输出格式,包括html4html5html+lhshtml5+lhss5、slidy、slideousdzslidesrevealjs。绝对URL处的脚本、图像和样式表会被下载下来;相对URL处的脚本、图像和样式表将相对于工作目录(如果第一个源文件是本地的)或相对于根URL(如果第一个源文件是远程的)进行搜索。具有属性data-external="1"的元素将被单独保留;它们链接到的文档将不会被合并到文档中。限制:通过JavaScript动态加载的资源不能被合并;作为结果,--self-contained对于mathjax不起作用,而且一些高级特性(例如,缩放或扬声器注释)可能无法在离线的“自包含”reveal.js幻灯片中使用。

–html-q-tags 在HTML引用中使用“q>标签”。

–ascii 在输出中只使用ASCII字符。目前支持XML、HTML(在选择此选项时使用数字字符实体而不是UTF-8编码)、groff ms和man(使用十六进制转义)。

–reference-links 在markdown或re-StructuredText中使用外部样式链接,而不是内联链接。默认情况下使用内联链接。链接引用的放置受--reference-location选项的影响。

–reference-location = block|section|document 指定是否在当前(最高级)块、当前节或文档的末尾放置脚注(以及引用,如设置了reference-links)。默认是document。当前只影响markdown写出器。

–atx-headers 在markdown和ASCIDOC输出中使用ATX样式标题。默认是1-2级标题使用setext样式,然后使用ATX样式。(注意:对于gfm输出,总是使用ATX标题)。

–top-level-division=[default|section|chapter|part] LaTeX、ConTeXt、DocBook、TEI输出中,将一级标题视为给定的分区类型。层次结构顺序是部、章,然后是节;一级标题为指定的类型时,所有标题都被相应位移。默认行为是通过启发式确定最佳分区类型:除非应用其他条件,否则选择section。当LaTeX文档类被设置为reportbookmemoir(除了指定了article选项之外)时,chapter被隐含为该选项的设置。如果是beamer输出格式,那么指定chapterpart将导致一级标题变成part{..},而二级标题保持默认类型。

-N, –number-sections 对LaTeX、ConTeXt、HTML或EPUB输出中的节标题进行编号。默认情况下,节没有编号。带有unnumbered类的节永远不会被编号,即使指定了--number-sections选项。

–number-offset=NUMBER[,NUMBER,…] HTML输出中的区节标题的偏移量(其他输出格式中忽略)。添加到节标题的第一个数字代表一级标题编号,第二个代表二级标题,等等。因此,例如你希望文档中的第一个一级标题编号为“6”,则指定--number-offset=5。如果您的文档从一个要被编号为“1.5”的二级标题开始,则指定--number-offset=1,4。默认情况下,偏移量为0。意味着--number-sections

–listings 使用LaTeX代码块listings宏包。

-i, –incremental 使幻灯片放映中的列表项目逐一显示(逐一)。默认值是同时显示。

–slide-level=NUMBER 设定具有指定层级的标题创建幻灯片(beamers5slidyslideousdzslides)。层次结构中高于此层级的标题用于将幻灯片放映划分为多个部分(指分为多页幻灯片);低于此层级的在幻灯片中创建子标题。注意,不包括低于含幻灯片层级标题的内容,这些内容也不会出现幻灯片中。默认是根据文档的内容设置幻灯片层级;请参幻灯片结构。

–section-divs 节用<section>标签包装(或在html4中用<div>),并用标识符<section>(或<div>)关闭,而不是标题本身。见下文标题标识符。

–email-obfuscation=none|javascript|references 指定一个用于模糊邮件地址的方法:HTML文档中的链接。none即使邮箱本身。javascript使用JavaScript对它们进行模糊处理。references将它们的字母打印为十进制或十六进制字符引用来混淆它们。默认值为none

–id-prefix=STRING 指定要添加到HTML和DocBook输出中的所有标识符和内部链接,以及markdown和Haddock输出中的脚注编号的前缀。这对于在生成要包含在其他页中的部分时防止重复标识符是有用的。

-TSTRING,–title-prefix=STRINGSTRING设定为出现在HTML标题中的的前缀(但不指定为出现在HTML体开头的标题)。意味着--standalone

-cURL,–css=URL

–reference-doc=FILE

–epub-cover-image=FILE

–epub-metadata=FILE

–epub-embed-font=FILE

–epub-chapter-level=NUMBER

–epub-subdirectory=DIRNAME

–pdf-engine=pdflatex|lualatex|xelatex|wkhtmltopdf|weasyprint|prince|context|pdfroff

–pdf-engine-opt=STRING

参考文献渲染

–bibliography=FILE 将文档元数据中的bibliography字段设置为FILE,覆盖元数据中设置的任何值,并使用pandoc-citeproc处理引用。(这相当于--metadata bibliography=FILE --filter pandoc-citeproc。)如果还提供--natbib--biblatex,则不使用pandoc-citeproc,因此相当于--metadata bibliography=FILE。如果您多次提供此参数,则每个FILE将被添加到参考目录中。

–csl=FILE 将文档元数据中的csl字段设置为FILE,会覆盖元数据中的任何值集。(这相当于--metadata csl=FILE。)这个选项只与pandoc-citeproc有关。

–citation-abbreviations=FILE 将文档的元数据中的citation-abbreviations字段设置为FILE,覆盖元数据中的任何值集。(这相当于--metadata citation-abbreviations=FILE。)这个选项只与pandoc-citeproc有关。

–natbib 使用natbib处理LaTeX输出中的引用。此选项不适用于pandoc-citeproc过滤器或PDF输出。它的目的是用于生成可用bibtex进行处理的LaTeX文件。

–biblatex 使用biblatex处理LaTeX输出中的引用。此选项不适用于pandoc-citeproc过滤器或PDF输出。它的目的是用于生成可用bibtexbiber进行处理的LaTeX文件。

HTML中数学公式渲染

默认是尽可能使用Unicode字符渲染TeX数学。公式被放置在一个类为math的span中,因此,如果需要它们可以不同于周围的文本样式。然而,这仅对基本数学公式给出可接受的结果,通常希望使用--mathjax或其他以下选项。

–mathjax[=URL] 使用MaTjax在HTML输出中显示嵌入的TeX数学公式。TeX数学公式置于\(...\)(对于行内公式)或\[…\](用于行间公式),并放在math类的span标签中。然后,MathJJax JavaScript将渲染它。URL应该指向MathJax.js加载脚本。如果没有提供URL,将插入Cloudflare CDN链接。

–mathml 将TeX数学转换为MathML(在epub3docbook4docbook5jatshtml4html5)中。这是odt输出中的默认值。请注意,目前只有Firefox和Safari(以及选择电子书阅读器)本身支持MathML。

–webtex[=URL] 将TeX公式转换为链接到将公式转换成图像的外部脚本的标签。公式将是URL编码,并与提供的URL串接。对于SVG图像,你可以使用例如--webtex https://latex.codecogs.com/svg.latex?。若不指定URL,将使用CodeCogs 链接生成PNGS图片(https://latex.codecogs.com/png.latex?)。注意:`--webtex`选项将影响markdown及HTML输出,如果您的目标是没有本地数学公式支持的markdown的版本,那么这个选项很有用。

–katex[=URL] 使用KaTeX在HTML输出中显示嵌入式TeX数学。URL是KaTeX库的URL地址。如果没有提供URL,将插入KaTeX CDN链接。

–katex-stylesheet=URL URL应该指向KaTeX.css样式表。如果这个选项不指定,将插入KaTeX CDN链接。请注意,此选项并不意味着--kateX

–gladtex 在HTML输出中把TeX公式封装在的<eq>标签中。然后,GladTeX可以对得到的HTML进行处理,以生成公式排版的图像,以及具有这些图像的链接的HTML文件。因此,程序是:

pandoc -s --gladtex input.md -o myfile.htex gladtex -d myfile-images myfile.htex
# 生成myfile.html文件和myfile-images 图像文件夹

脚本封装选项

–dump-args 将命令行参数的信息打印到标准输出,然后退出。此选项主要用于封装脚本。第一行输出包含用-o选项指定的输出文件的名称,或者没有指定输出文件-(对于标准输出)。剩下的行包含命令行参数,每个一行,按它们出现的顺序排列。这些选项不包括常规的pandoc选项及其参数,但是包括任何出现在行尾的--分隔符之后的选项。

–ignore-args 忽略命令行参数(封装脚本时)。常规pandoc选项不被忽略。因此,

pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1

等价于

pandoc -o foo.html -s