Pandoc User Guide 中文版

ZhuYuanxiang 2020-05-01 00:00:00
Categories： Tags：

Author: John MacFarlane

翻译：zYx.Tom

March 23,2020

Pandoc 用户手册

对 Pandoc V 2.9.2 的英文帮助的翻译，翻译的过程会随着使用的需要而增加，翻译的内容会增加部分使用过程中的感悟。

大纲

pandoc[_options_] [_input-file_]…

描述

Pandoc 是基于 Haskell 库开发文档格式转换工具，只能命令行模式下执行。

Pandoc 可以转换许多种文档格式，包括但不限于： Markdown、HTML、LaTeX 和 Word docx 文档。文档格式列表请参考--from和--to属性 ( 选项 ) 中的说明。Pandoc 还能输出 PDF 格式的文件，详细参考创建 PDF。

Pandoc’s Markdown 可以支持许多高级功能，包括：表格 ( tables )、定义列表 ( definition lists )、元数据块 ( 元数据块 )、脚注 ( footnotes )、引用 ( citations )、数学公式 ( math ) 等等。详情参考 Pandoc’s Markdown 部分。

Pandoc 基于模块化设计：一组阅读者，用于解析给定的格式和生成文档的本地表达 ( 抽象的语法树或者 AST )；一组书写者，转换本地表达到目标格式。因此，增加输入和输出格式仅需要增加阅读者和书写者的实例。用户可以运行自定义的 Pandoc 过滤器 来修改中间格式的 AST。

因为 Pandoc 的中间格式相比需要转换的格式来说无法提供足够丰富的表达能力，因此完美的格式转换是无法实现的。Pandoc 尝试保留文档的结构化元素，但是无法保留格式化的细节 ( 例如：边缘的宽度 )。一些文档元素 ( 例如：复杂的表格 ) 可能无法匹配到 Pandoc 的简单的模型中。然后，Pandoc 由自己支持的 Markdown 格式向其他格式转换时效果是很好的，但是从其他格式向 Pandoc 自己支持的 Markdown 格式转换时会有所不足。

使用 pandoc

pandoc

pandoc input.txt -o output.html

使用-o命令定义输出文件，输入文件根据文件名确定，默认为 Markdown 格式。生成的 HTML 只是一个片段。

pandoc input.txt -o output.html -s

使用-s或者--standlone命令输出的是个独立的文档 ( 例如：HTML 文件就包括了<head>和<body>)。关于独立文档的更多信息可以参考 模板 部分。

`pandoc input1.md input2.md -o output.html’

如果有多个输入文件，pandoc会自动将它们连接起来 ( 中间使用空行分隔 ) 再进行解析。

注：使用---file-scope可以强制单独解析。

定义格式

输入和输出的格式可以使用命令行选项单独定义。

--f/--from：定义输入格式
--t/--to：定义输出格式

例如：

支持的文件格式参考 选项 (-f是输入格式，-t是输出格式 )。还可以使用pandoc --list-input-formats和pandoc --list-output-formats显示支持的文件格式。如果文件格式没有被显式定义，pandoc将会基于文件名的后缀猜测。
例如：下面的例子试图将hello.txt从 Markdown 转换为 LaTeX。

pandoc -o hello.tex hello.txt

字符编码

Pandoc 使用 UTF-8 字符来编码输入和输出。如果你的文件编码格式不是 UTF-8，你需要基于管道技术使用 iconv 将字符转换编码后再输出给 pandoc 处理 ( Linux 环境下，Windows 下用 VSCode 等工具 )。

iconv -t utf-8 input.txt | pandoc | iconv -f utf-8

注：在某些输出格式中 ( 例如：HTML, LaTeX, ConTeXt, RTF, OPML, DocBook, and Texinfo ) , 使用-s/-standlone选项可以将字符编码的信息包含在文档头。

创建 PDF

例如：下面的语句将 Markdown 格式的test.txt转换成 PDF 格式test.pdf

pandoc test.txt -o test.pdf

默认情况下，Pandoc 使用 LaTeX 创建 PDF，因此需要安装 LaTeX 引擎 ( 参考--pdf-engine)。作为替换，Pandoc 也可以使用 ConTeXt、roff ms、HTML 作为中间格式。

不同的中间格式，基于变量控制 PDF 风格的方式不同，具体参考

如果需要调试 PDF 的创建过程，可以先生成 LaTeX 格式的文件，再使用 pdflatex测试。

pandoc test.txt -s -o test.tex
pdflatex test.tex

注：如果是中文，则使用xelatex测试。

使用 LaTeX 建议安装 TeX Live )，从而包括以下各种包 : amsfonts , amsmath , lm , unicode-math , ifxetex , ifluatex , listings (--listings选项设置 ) , fancyvrb , longtable , booktabs , graphicx ( 支持文档包含图片 ) , hyperref , xcolor , ulem , geometry (geometry变量设置 ) , setspace ( 用于变量linestretch) , 和 babel ( 用于 变量lang) .
使用xelatex或者lualatex作为 PDF 引擎时需要 fontspec .xelatex使用
polyglossia ( 用于变量lang) , xecjk , 和 bidi ( 用于dir变量 )。设置mathspec变量时，xelatex需要 mathspec 代替 unicode-math。upquote 和 microtype 是必须的，并且 csquotes 将被用于 typography 如果设置csquotes为true在变量 或者 元数据域。natbib , biblatex , bibtex , 和 biber 包用于 citation rendering . 下面的包用于 改善输出的质量，但是对于 pandoc 它们不是必须的 : upquote ( for straight quotes in verbatim environments ) , microtype ( 更好的空间调整 ) , parskip ( 更好的段落空间调整 ) , xurl ( URL 里面更好的行分隔 ) , bookmark ( 更好的 PDF 标签显示 ) , 和footnotehyper 或 footnote ( 表格中的脚注 )

读取 Web

不使用输入文件，而使用绝对 URI 来作为输入源，pandoc 通过 HTTP 直接取得内容

pandoc -f html -t markdown https://www.fsf.org

在通过 URL 获取文档时，还可以定制 User-Agent 或者 其他文件头

pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" https://www.fsf.org

选项

一般选项

-fFORMAT,-rFORMAT,--from=FORMAT,--read=FORMAT

: 定义输入格式。FORMAT can be:

使用+EXTENSION或者-EXTENSION可以将文件格式中的某些扩展打开或者关闭。详细参考 扩展 。具体参考--list-input-formats和--list-extensions。

-tFORMAT,-wFORMAT,--to=FORMAT,--write=FORMAT

: 定义输出格式。 FORMAT can be:

注：odt,docx,epub, 和pdf输出不会直接指向 stdout 除非使用-o -。

使用+EXTENSION或者-EXTENSION可以将支持的文件格式单独打开或者关闭。详细参考 Extensions 了解支持的扩展以及他们的名字。具体参考--list-output-formats和--list-extensions。

-oFILE,--output=FILE

: 将输出写入 FILE 而不是 stdout. 如果 FILE 是-, 则输出依然是_stdout_, 哪怕是定义的是非文本类文件 (例如：docx,odt,epub2,epub3)

--data-dir=DIRECTORY

: 定义的用户数据路径，用于搜索 pandoc 的数据文件。如果这个选项没有设置，则默认的数据路径将会被使用。在 *nix 和 macOS 系统上 XDG 数据目录的路径($HOME/.local/share, 由XDG_DATA_HOME环境变量设置)将会是pandoc 子目录的路径。如果这个目录的路径不存在， 则$HOME/.pandoc将会被使用。在 Windows 上默认的用户目录的路径是C: \Users\USERNAME\AppData\Roaming\pandoc。使用 pandoc --version可以查看这个默认目录的路径。文件reference.odt,reference.docx,epub.css, templates,slidy,slideous, 或者s5目录存放在这个用户目录下较会覆盖 pandoc 的默认设置。

-dFILE,--defaults=FILE

: 定义默认属性设置的的集合。 FILE 是一个 YAML 文件，文件中的域对应于命令行的属性设置。所有的文档转换的选项，包括输入和输出文件都可以被设置为默认文件。这个文件先在工作目录中搜索，然后是默认的用户目录(--data-dir)的defaults子目录中搜索。这个.yaml扩展可以被省略。参考 默认文件 获取更多文件格式的信息。来自于默认文件的设置将会扩展或者替代命令行中的后序选项。

--bash-completion

: Generate a bash completion script. To enable bash completion with
pandoc, add this to your.bashrc:

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

--verbose

给出详细的调试输出。这个仅对 PDF 输出时有效。

--quiet

安静模式。抑制所有的警告信息。

--fail-if-warnings

遇到警告就退出转换过程。

--log=FILE

: FILE 日志文件，格式是机器可以读出的 JSON 格式。所有 DEBUG 级别以上的信息都会被写入，不受详细信息的设置影响 (--verbose,--quiet) 。

--list-input-formats

: 列出所有的输入格式，一种占一行。

--list-output-formats

: 列出所有的输出格式，一种占一行。

--list-extensions[=_FORMAT_]

: 列出 _FORMAT_支持的所有扩展，一种占一行。每行的前面使用 + 或者 - 表示 FORMAT 对于这种扩展的默认设置。

例如

--list-highlight-languages

: 列出所有支持语法高亮的语言，一种占一行

--list-highlight-styles

: 列出所有语法高亮的风格，一种占一行，详情参考--highlight-style

-v,--version

: Print version.

-h,--help

: Show usage message.

阅读者选项

--shift-heading-level-by=NUMBER

: Shift heading levels by a positive or negative integer. For example, with --shift-heading-level-by=-1, level 2 headings become level 1 headings, and level 3 headings become level 2 headings. Headings cannot have a level less than 1, so a heading that would be shifted below level 1 becomes a regular paragraph. Exception: with a shift of -N, a level-N heading at the beginning of the document replaces the metadata title. --shift-heading-level-by=-1 is a good choice when converting HTML or Markdown documents that use an initial level-1 heading for the document title and level-2+ headings for sections. --shift-heading-level-by=1 may be a good choice for converting Markdown documents that use level-1 headings for sections to HTML, since pandoc uses a level-1 heading to render the document title.

--base-header-level=NUMBER

: Deprecated. Use--shift-heading-level-by=X instead, where X =- 1. Specify the base level for headings ( defaults to 1 ) .

--strip-empty-paragraphs

: Deprecated. Use the+empty_paragraphsextension instead. Ignore with no content. This option is useful for converting word processing documents where users have used empty paragraphs to inter-paragraph space.

--indented-code-classes=CLASSES

缩进代码块中的类： perl,numberLinesorhaskell.多个类可以被空格或者逗号分开。

--default-image-extension=EXTENSION

当图片的 paths/URLs 没有定义时，可以使用定义的默认扩展。这个允许使用同样的源当需要使用不同类型的图片格式时，当前这个选项仅仅影响 Markdown and LaTeX 阅读者.

--file-scope

在混合多文件文档时，先单独解析每个文件。这个将允许脚注在不同文件中伴随着相同的标识符如预期工作。如果这个选项被设置，脚注和链接将会跨文件工作。读取二进制文件 (docx, odt, epub) 暗示 --file-scope.

-FPROGRAM,--filter=PROGRAM

定义一个可以执行程序作为变换过滤器，用于转换 pandoc AST 在输入被解析后和输出被写出前。这个可执行程序用于从 stdin 中读取 JSON 和 向 stdout 中写入 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`](https://github.com/jgm/pandocfilters) ( 从 PyPI 中安装)。pandoc 过滤器库在 PHP , perl , and JavaScript/node.js 中也有。

为了满足偏爱， pandoc 将会搜索过滤器：

  1. a specified full or relative path (executable or non-executable)

  2. $DATADIR/filters (executable or non-executable) where $DATADIR is the user data directory (see --data-dir, above).

  3. $PATH (executable only)

过滤器 和 基于 Lua 的过滤器的应用顺序基于命令行的顺序。

-LSCRIPT,--lua-filter=SCRIPT

: Transform the document in a similar fashion as JSON filters (see --filter), but use pandoc’s build-in Lua filtering system. The given Lua script is expected to return a list of Lua filters which will be applied in order. Each Lua filter must contain element-transforming functions indexed by the name of the AST element on which the filter function should be applied.

The pandoc Lua module provides helper functions for element creation. It is always loaded into the script’s Lua environment.

The following is an example Lua script for macro-expansion:

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

In order of preference, pandoc will look for Lua filters in

  1. a specified full or relative path (executable or non-executable)

  2. $DATADIR/filters (executable or non-executable) where $DATADIR is the user data directory (see --data-dir, above).

-M_KEY_[=_VAL_],--metadata=_KEY_[:_VAL_]

设置元数据域的关键字 KEY 为值 _VAL_。定义在命令行的值会覆盖定义在文档中的值，文档定义基于YAML metadata blocks . 值会被解析为 YAML boolean 或者 string . 如果没有值被定义，则默认为 Boolean true. 例如：--variable,--metadata 会影响模板变量，但是不像--variable,--metadata 影响着潜在文档的元数据，潜在文档是可以被通过过滤器访问，也可以按照某种格式输出。 元数据的值在被插入模板时将会被转义。

--metadata-file=FILE

从 YAML(或者 JSON)文件中读取元数据。这个选项可以基于任何输入格式，但是YAML文件中的字符串总被作为 Markdown的格式解析。通常情况下，输入的处理方式如 [YAML metadata blocks] ( #extension-yaml_metadata_block ) 描述。这个选项可以用于包括多个元数据文件；文件中的值由最后一个文件来最终确定。元数据值可以被定义在文档中，也可以使用 -M 来覆盖文件中的定义。

-p,--preserve-tabs

保留制表符而不是转成空格。(默认情况下，pandoc 在解析输入前就将制表符转成空格)。

注：这个设置只会影响纯文本代码和代码块中的制表符。制表符在正则表达式文本中总被看作空格。

--tab-stop=NUMBER

定义每个制表符的空格数目(默认是4)。

--track-changes=accept|reject|all

: Specifies what to do with insertions, deletions, and comments produced by the MS Word “Track Changes” feature.accept( the default ) , inserts all insertions, and ignores all deletions. rejectinserts all deletions and ignores insertions. Bothacceptandrejectignore comments.allputs in insertions, deletions, and comments, wrapped in spans withinsertion,deletion, comment-start, andcomment-endclasses, respectively. The author and time of change is included.allis useful for scripting: only accepting changes from a certain reviewer, say, or before a certain date. If a paragraph is inserted or deleted,track-changes=all produces a span with the class paragraph-insertion/paragraph-deletionbefore the affected paragraph break. This option only affects the docx reader.

--extract-media=DIR

: Extract images and other media contained in or linked from the source document to the path DIR, creating it if necessary, and adjust the images references in the document so they point to the extracted files. If the source format is a binary container ( docx, epub, or odt ) , the media is extracted from the container and the original filenames are used. Otherwise the media is read from the file system or downloaded, and new filenames are constructed based on SHA1 hashes of the contents.

--abbreviations=FILE

: Specifies a custom abbreviations file, with abbreviations one to a line. If this option is not specified, pandoc will read the data file abbreviations from the user data directory or fall back on a system default. To see the system default, use pandoc --print-default-data-file=abbreviations. The only use pandoc makes of this list is in the Markdown reader. Strings ending in a period that are found in this list will be followed by a nonbreaking space, so that the period will not produce sentence-ending space in formats like LaTeX.

书写者选项

-s,--standalone

: 输出文件包括合适的头和尾 ( 例如：独立的 HTML, LaTeX, TEI, 或 RTF 文件，而不是个片段) . 这个选项对于pdf,epub,epub3,fb2,docx, 和odt文件输出是自动设置为真的. 对于native`输出, 这个选项将元数据也被包括进去；其他类型，元数据会被抑制。

--template=_FILE_|URL

: 生成文档时使用特定的模板。隐含设置了--standalone. 详情参考模板 了解模板的语法。如果扩展被定义，扩展对应的书写者会被加入，例如--template=special 就会自动搜索special.html满足 HTML 输出。如果模板没有找到，pandoc 会在用户目录( see
--data-dir)的templates子目录搜索。如果这个选项没有被设置，则输出格式会使用对应的默认模板 ( see
-D/--print-default-template) .

-V_KEY_[=_VAL_],--variable=_KEY_[:_VAL_]

: 当输出文档在 standalone 模式下，设置模板变量 KEY 的值 _VAL_。如果没有 VAL 被设置，则模板的变量 KEY 会设置为 true。

-DFORMAT,--print-default-template=FORMAT

: 依照 FORMAT 输出系统的默认模板。( See-t 列出支持的格式 FORMAT. ) 用户数据目录下的模板将会被忽略。这个选项可以被用于 -o/–output从而重指向到文件中, 但是-o/–output必须在命令行模式下位于–print-default-template`前面。

注：某些模板是有偏好的，例如：styles.html. 可以使用--print-default-data-file显示偏好。 例如：--print-default-data-file=templates/styles.html.

--print-default-data-file=FILE

: 显示系统默认数据文件。用户数据目录下的文件会被忽略。这个选项可以被用于 -o/--output从而重指向到文件中, 但是-o/--output必须在命令行模式下位于--print-default-data-file前面。

--eol=crlf|lf|native

手工定义行结束符。

--dpi=NUMBER

: Specify the default dpi (dots per inch) value for conversion from pixels to inch/centimeters and vice versa. (Technically, the correct term would be ppi: pixels per inch.) The default is 96dpi. When images contain information about dpi internally, the encoded value is used instead of the default specified by this option.

--wrap=auto|none|preserve

确定文件在输出(是源代码，不是绘制的版本)中是否换行。默认设置是 auto，pandoc 基于 --columns(默认为72) 来换行。设置 none，pandoc 就不自动换行。设置 preserve，pandoc 试图保留源代码文档中的换行(也就是源文件中的非语义换行，在输出文件中也会如此)。自动换行在HTML输出中不被使用。在ipynb输出中，选项只会影响 markdown cell 中的内容。

--columns=NUMBER

定义每行字符的长度。这个设置会影响生成代码中的文本换行 (see --wrap)。同样还会影响简单的文本表格 (see 表格中列宽度的计算

--toc, --table-of-contents

输出文档中包括一个自动生成的目录(或者，在 latex, context, docx, odt, opendocument, rst, 或者ms, 用于指导创建) 。这个选项在 -s/--standalone 使用时才有效，在 man, docbook4, docbook5, 或者jats 输出时无效。

注：如果通过 ms创建 PDF，目录会出现在文档的最前(标题前面)。如果想放到文档的最后，使用选项 --pdf-engine-opt=--no-toc-relocation.

--toc-depth=NUMBER

定义目录的深度(包括的节的层次，默认是3)。

--strip-comments

: Strip out HTML comments in the Markdown or Textile source, rather than passing them on to Markdown, Textile or HTML output as raw HTML. This does not apply to HTML comments inside raw HTML blocks when the markdown_in_html_blocks extension is not set.

--no-highlight

关闭代码块和内联块中的语法高亮。

--highlight-style=_STYLE_|FILE

定义语法高亮的形式。

设置 _STYLE_，默认设置 pygments，其他还有： kate, monochrome, breezeDark, espresso, zenburn, haddock, 和tango.更多信息参考 Syntax highlighting 和 --list-highlight-styles.

设置_FILE_，需要以.theme作为后缀，使用 JSON 作为文件格式。这个文件将会采用 KDE 语法高亮主题的方式解析和使用。

如果想生成 JSON 格式的文件可以使用 --print-highlight-style.

--print-highlight-style=_STYLE_|FILE

输出符合 JSON 格式的用于语法高亮风格的文件，文件后缀为.theme，用于 --highlight-style。这个选项用于-o/--output输出文件，并且在命令行模式下 -o/--output 必须在–print-highlight-style` 之前。

--syntax-definition=FILE

指导 pandoc 载入一个 KDE XML 语法定义的文件，这个文件将被用于语法高亮某个被标注的代码块。也可以被用于支持新的语言 或者 用来替代已经定义的语言。这个选项可以被重复加入多个语法定义。

-H FILE, --include-in-header=_FILE_|URL

将 FILE 中的内容(原始文本)加在 header 的后面。这个应用的例子：将 CSS 和 JavaScript 加在 HTML 文档中。这个选项可以将多个文件包含在 header 中，包含的顺序取决于定义的顺序。参考： --standalone.

-B FILE, --include-before-body=_FILE_|URL

将 FILE 中的内容(原始文本)加在文档的 body 前面(例如：HTML的 <body> 后面；LaTeX的 \begin{document}命令后面)。这个应用的例子：将导引条(navigation bar)或者 横幅(banner) 加入 HTML 文档。这个选项可以将多个文件包括进来，包含的顺序取决于定义的顺序，参考： --standalone.

-A FILE, --include-after-body=_FILE_|URL

将 FILE 中的内容(原始文本)加在文档的 body 后面(例如：HTML的 </body> 前面；LaTeX的 \end{document}命令前面)。这个选项可以将多个文件包括进来，包含的顺序取决于定义的顺序，参考： --standalone.

--resource-path=SEARCHPATH

: List of paths to search for images and other resources. The paths should be separated by : on Linux, UNIX, and macOS systems, and by ; on Windows. If --resource-path is not specified, the default resource path is the working directory. Note that, if --resource-path is specified, the working directory must be explicitly listed or it will not be searched. For example: --resource-path=.:test will search the working directory and the test subdirectory, in that order.

--resource-path only has an effect if (a) the output format embeds images (for example, docx, pdf, or html with --self-contained) or (b) it is used together with --extract-media.

--request-header=NAME:VAL

当发起 HTTP 请求时(例如：当在命令行中给定 URL 时；或者，当文档中的资源必须在下载时)设置请求头的内容 NAME 和 VAL 。如果你在 proxy 后面，还需要参考环境变量 http_proxy 访问 http://....

Options affecting specific writers

笔记软件选择
2020 年 04 月日记