Pandoc User’s Guide 日本語版

注釈

現在の翻訳は プレリリース版 です。不完全な翻訳を含んでいます。 （ユーザーズガイド以外のページについてはほぼ翻訳されていません。現在翻訳を進めています）

原著者:

  • John MacFarlane

原著バージョン: 2.18

更新日: 2022/04/29

翻訳者（アルファベット順）:

目次

概要

pandoc [options] [input-file]…

説明

Pandocは、あるマークアップ形式から他の形式へ変換する Haskell ライブラリと、そのライブラリを用いたコマンドラインツールです。

Pandoc は、 Markdown 、 HTML 、LaTeX 、 Word docx など、これに限定されない多数のマークアップとワープロ形式の間で変換することができます。入力および出力形式の完全なリストについては、下記 (options below) の --from と --to を参照してください。 Pandoc は PDF 出力を生成することもできます。下記の creating a PDF を参照してください。

"Markdown の Pandoc 拡張バージョンには、 tables 、 definition lists 、 metadata blocks、 footnotes 、citations 、 math をはじめ多数の構文を含みます。下記の Pandoc’s Markdown を参照してください。

Pandoc はモジュール設計されています。 Pandoc は、与えられた形式のテキストをパースして文書のネイティブ表現 (抽象構文木 またはAST) に変換する Reader 群、およびネイティブ表現をターゲットの出力形式に変換する Writer 群で構成されています。つまり、入力または出力形式を追加するには、 Reader または Writer を追加するだけで済みます。ユーザは、カスタムの pandoc filters を実行することで、中間の AST を書き換えることもできます。

Pandoc での文書の中間表現は、変換するほとんどの形式より表現力が劣ることから、すべての形式と他の形式との間で、完全に変換できるわけではありません。 Pandoc は、文書の構造要素を保とうとしますが、マージンサイズのような緻密なフォーマッティングは行いません。また、複雑なテーブルなどの一部の文書要素は、 Pandoc の単純な文書モデルにフィットしない場合があります。 Pandoc 拡張 Markdown からは、他のすべての形式へ完全に変換されることを目指していますが、 Pandoc 拡張 Markdown よりも表現力が豊富な形式から変換する場合は、表現が劣化することは否めません。

pandoc の使い方

入力ファイルとして input-files が指定されていない場合は、入力は標準入力 stdin から読まれます。 出力はデフォルトでは標準出力 stdout に出力されます。ファイルへ出力したい場合は -o オプションを使用してください：

pandoc -o output.html input.txt

既定では、 Pandoc は分割された文書群を生成します。スタンドアロン文書（例えば、 <head> と <body> を含む有効な HTML ファイル）を生成するには、 -s または -standalone フラグを使います:

pandoc -s -o output.html input.txt

スタンドアロン文書がどのように生成されるかについての詳細は、下記の Templates を参照してください。

If multiple input files are given, pandoc will concatenate them all (with blank lines between them) before parsing. (Use --file-scope to parse files individually.)

形式の指定

入出力の形式はオプションを使うことで明確に指定できます。入力形式の指定は -f/--from オプションを、出力形式の指定は -t/--to オプションを使います。したがって、 hello.txt を Markdown から LaTeX に変換する場合は以下のようにします。

pandoc -f markdown -t latex hello.txt

hello.html を HTML から Markdown に変換するには以下のようにします。

pandoc -f html -t markdown hello.html

サポートされている入力および出力の形式は、 Options に挙げています（入力形式については -f の項を、出力形式については -t の項をご覧ください）。また pandoc --list-input-formats および pandoc --list-output-formats を実行することで、サポートされている形式の一覧を得られます。

If the input or output format is not specified explicitly, pandoc will attempt to guess it from the extensions of the filenames. Thus, for example,

pandoc -o hello.tex hello.txt

hello.txt は Markdown から LaTeX へ変換されるでしょう。もし（標準出力するために）出力ファイルが指定されていない場合、または出力ファイルの拡張子が不明の場合は、出力形式のデフォルトは HTML になります。そして、もし（標準入力するために）入力ファイルが指定されていない場合、または入力ファイルの拡張子が不明の場合は、入力形式は Markdown になります。

文字コード

Pandoc は入力と出力の両方に UTF-8 文字コードを使用します。あなたのローカルの文字コードが UTF-8 ではない場合、 ```iconv```_ を通して入力と出力をパイプすべきです:

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

いくつかの出力フォーマット(HTML 、 LaTeX 、 ConTeXt 、 RTF 、 OPML 、 DocBook 、 Texinfo など)の中には、文字コードに関する情報が文書のヘッダに含まれているものがあり、その場合は -s/ --standalone オプションを使用するだけでヘッダを挿入することができます。

PDFの生成

PDFを生成するには、出力ファイルに拡張子 .pdf を指定してください。

pandoc test.txt -o test.pdf

既定では、PandocはPDFを生成するためにLaTeXを用います。そのためにはLaTeXエンジンがインストールされている必要があります(下記の --pdf-engine を参照)。替わりに、PandocではConTeXt, roff, ms, HTMLといった中間書式を利用できます。替わりの方法で出力するには、前述のとおり出力ファイルに拡張子 ``.pdf`` を指定した上で --pdf-engine オプションまたは -t context, -t html, -t ms のいずれかをコマンドラインに指定します。中間書式からPDFを生成するツールを指定するには --pdf-engine を指定します。

ユーザはPDFのスタイルを制御するために変数を利用できます。この変数は中間書式に依存します(variables for LaTeX, variables for ConTeXt, variables for ``wkhtmltopdf``, variables for ms を参照)。中間書式がHTMLの場合は --css を用いて出力の書式を指定できます。

PDF 作成におけるデバッグを行うには、中間生成物を確認することが有効です。 例えば -o test.pdf``の代わりに、 -s -o test.tex``を使って生成された LaTeX 出力で確認することができます。その後、 ``pdflatex test.tex``でテストすることができます。

When using LaTeX, the following packages need to be available (they are included with all recent versions of TeX Live): `amsfonts```_, ```amsmath```_, ```lm```_, ```unicode-math```_, ```iftex```_, ```listings```_ (if the ``--listings option is used), `fancyvrb```_, ```longtable```_, ```booktabs```_, ```graphicx```_ (if the document contains images), ```hyperref```_, ```xcolor```_, ```ulem```_, ```geometry```_ (with the ``geometry variable set), `setspace```_ (with ``linestretch), and `babel```_ (with ``lang). If CJKmainfont is set, `xeCJK```_ is needed. The use of ``xelatex or lualatex as the PDF engine requires `fontspec```_. ``lualatex uses `selnolig```_. ``xelatex uses `bidi```_ (with the ``dir variable set). If the mathspec variable is set, xelatex will use `mathspec```_ instead of ```unicode-math```_. The ```upquote```_ and ```microtype```_ packages are used if available, and ```csquotes```_ will be used for `typography`_ if the ``csquotes variable or metadata field is set to a true value. The ```natbib```_, ```biblatex```_, ```bibtex```_, and ```biber```_ packages can optionally be used for citation rendering. The following packages will be used to improve output quality if present, but pandoc does not require them to be present: ```upquote```_ (for straight quotes in verbatim environments), ```microtype```_ (for better spacing adjustments), ```parskip```_ (for better inter-paragraph spaces), ```xurl```_ (for better line breaks in URLs), ```bookmark```_ (for better PDF bookmarks), and ```footnotehyper```_ or ```footnote```_ (to allow footnotes in tables).

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

オプション

一般的なオプション

-f FORMAT、 -r FORMAT、 --from=FORMAT、 --read=FORMAT

入力形式を指定します。FORMAT は次のいずれかになります：

Markdown拡張は +EXTENSION または -EXTENSION をフォーマット名に追加することで、個別にそれぞれ「有効」または「無効」を切り替えられます。拡張とその名前のリストは下記の Extensions を参照してください。下記の --list-input-formats と --list-extensions オプションも参照。

-t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT

出力形式を指定してください。 FORMAT は以下の形式が選択できます。

注意: odt および docx, epub, pdf 出力については -o - と強制的に指定しない限り 標準出力 に出力されません。

Markdown拡張は +EXTENSION または -EXTENSION をフォーマット名に追加することで、個別にそれぞれ「有効」または「無効」を切り替えられます。拡張とその名前のリストは下記の Extensions を参照してください。下記の --list-input-formats と --list-extensions オプションも参照。

-o FILE, --output=FILE

出力を標準出力 stdout の代わりに FILE に書き出します。FILE が - の場合は、テキスト的でない形式 (docx, odt, epub2, epub3) が指定されていても、出力は標準出力 stdout になります。

--data-dir=DIRECTORY

Pandocがデータファイルを正しく見つけるために、ユーザーデータディレクトリを指定できます。このオプションが指定されていない場合、以下の既定のユーザーデータディレクトリが使われます。

-d FILE, --defaults=FILE

Specify a set of default option settings. FILE is a YAML file whose fields correspond to command-line option settings. All options for document conversion, including input and output files, can be set using a defaults file. The file will be searched for first in the working directory, and then in the defaults subdirectory of the user data directory (see --data-dir). The .yaml extension may be omitted. See the section Defaults files for more information on the file format. Settings from the defaults file may be overridden or extended by subsequent options on the command line.

--bash-completion

bash 補完スクリプトを生成します。Pandoc の bash 補完を有効にするために、これをあなたの .bashrc に加えます。

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

詳細なデバッグ出力が得られます。

--quiet

警告メッセージを抑制します。

--fail-if-warnings

警告があった場合、エラーステータスとともに終了します。

--log=FILE

機械可読(machine-readable) JSON 形式で FILE にログメッセージを書きます。DEBUG レベルより上のすべてのメッセージが冗長設定 (--verbose, --quiet) に関わらず書かれます。

--list-input-formats

サポートしている入力形式を１行に１つずつ表示します。

--list-output-formats

サポートしている出力形式を１行に１つずつ表示します。

--list-extensions[=FORMAT]

FORMAT 形式で利用できる拡張の一覧を出力します。1行ずつ先頭に、その拡張が有効かどうかを示す記号 + (有効) または - (無効) がつきます。もし FORMAT が指定されていなければ、既定でPandoc's Markdownの拡張一覧を出力します。

--list-highlight-languages

シンタックスハイライトをサポートしている言語を１行に１つずつ表示します。

--list-highlight-styles

シンタックスハイライトをサポートしているスタイルを１行に１つずつ表示する。 --highlight-style を参照してください。

-v, --version

バージョンを表示します。

-h, --help

使い方のメッセージを表示します。

Readerのオプション

--shift-heading-level-by=NUMBER

見出しレベルをシフトします。正または負の整数で指定します。たとえば --shift-heading-level-by=-1 により、レベル2見出しはレベル1見出しに、レベル3見出しはレベル2見出しになります。ただし見出しは1未満の見出しレベルを持てません。そのためレベル1見出しは通常の段落に変わります。例外: -N (マイナスN) でシフトした際に、文書の最初にあるレベルNヘッダはメタデータのtitleに置き換わります。便利な例を2つ挙げます。まず --shift-heading-level-by=-1 は、(訳注: 出力前の文書において)文書先頭のレベル1見出しを文書自体のタイトルとみなし、レベル2以上の見出しをセクションとみなすようなHTMLまたはMarkdown文書の変換に便利です。また --shift-heading-level-by=1 は、(訳注: 出力前の文書において)レベル1見出しをHTMLのセクションとみなしたい際に便利です。なぜならPandocはレベル1見出しを文書のタイトルとして生成するからです。

--base-header-level=NUMBER

非推奨。かわりに ``--shift-heading-level-by``=X を利用してください(X = NUMBER - 1)。 ベースの見出しレベルを指定します(既定値は1)。

--strip-empty-paragraphs

非推奨です。代わりに ``+empty_paragraphs`` 拡張を使用してください。 中身のない段落を無視します。このオプションは段落間の空白を作るために空白の段落を使用したワードプロセッシング文書を変換するのに便利です。

--indented-code-classes=CLASSES

インデントされたコードブロックに使うクラスを指定します。例としては perl,numberLines や haskell です。複数のクラスを空白（スペース）かカンマ（,）で区切って与えることが出来ます。

--default-image-extension=EXTENSION

画像のパスまたはURLが拡張子を持たないときに使うデフォルトの拡張子を指定します。同じソースをから異なる種類の画像を要求するフォーマットを使えるようになります。現在このオプションはMarkdown と LaTeX Readerにのみ影響を与えます。

--file-scope

複数のファイルからなるドキュメントを結合する前にそれぞれのファイルは個別に解釈されます。これによって、異なるファイルにある同じ識別子を持つの脚注が期待通りに機能します。このオプションを指定した場合、ファイルをまたいだ脚注とリンクは機能しなくなります。--file-scope はバイナリファイル(docx, odt, epub)を読むことを含みます。

-F PROGRAM, --filter=PROGRAM

入力が解析され出力が書かれる前にPandoc ASTを変換するフィルタとして使用する実行可能ファイルを指定します。実行可能ファイルは標準入力 stdin からJSONを読み、標準出力 stdout に出力するべきです。JSONはPandocのJSON入力と出力の形式にしなければなりません。出力形式の名前は第一引数としてフィルタに送られます。ここで、

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

は以下と等しい

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

後者の形式はフィルターのデバッグに便利です。

JSONフィルタは任意のプログラミング言語で書けます。HaskellでJSONフィルタを書く場合は、その手助けとして Text.Pandoc.JSON モジュールの toJSONFilter 関数を利用できます。PythonでJSONフィルタを書きたい場合は、PyPIからインストールできる ```pandocfilters```_ モジュールが利用可能です。他にもJSONフィルタ用のライブラリはいくつか存在し、 PHP, perl, JavaScript/node.js で利用できます。

Pandocはフィルターを以下の優先順で探します。

  1. 指定された絶対パスか相対パス（実行可能または実行不能）

  2. $DATADIR/filters (実行可能または実行不能) ここで $DATADIR はユーザデータディレクトリです。 (前記の --data-dir を参照してください)。

  3. $PATH (実行可能なものだけ)

フィルタ、Lua フィルタおよび citeproc の処理は、コマンド ラインで指定された順序で適用されます。

-L SCRIPT, --lua-filter=SCRIPT

JSONフィルタ(--filter を参照)と同様ですが、PandocにビルトインされたLuaによるフィルタシステムを用いてPandoc内部で文書(AST)を変換します。与えられたLuaスクリプトはLuaフィルタのリストを返すことを期待され、そのリストの順にフィルタが適用されます。それぞれのLuaフィルタは、AST要素の名前でインデックスされた要素変換関数(element-transforming functions)を含む必要があり、フィルタ関数はその同名のAST要素に対して変換を適用します。

pandoc Luaモジュールは要素を生成するためのヘルパー関数を提供します。これはスクリプトのLua環境に対して常にロードされます。

詳細は Lua filters documentation をご覧ください。

次の優先順位で、PandocはLuaフィルタを探します。

  1. 特定のフルパスまたは相対パス

  2. $DATADIR/filters ($DATADIR はユーザデータディレクトリ、前記の --data-dir を参照)。

フィルタ、Lua フィルタおよび citeproc の処理は、コマンド ラインで指定された順序で適用されます。

-M KEY[=VAL], --metadata=KEY[:VAL]

メタデータフィールド KEY を値 VAL に設定します。コマンドラインで指定された値は YAML metadata blocks を使用して文書で指定された値を上書きしてしまいます。値は YAMLの真偽値または文字列値としてパースされます。値が指定されていない場合、値は真偽値 true として扱われます。 --variable と同様に、 --metadata はテンプレート変数を設定します。しかし、 --variable とは異なり、 --metadata は基になる文書中のメタデータ（フィルタからアクセス可能で、一部の出力書式で印刷されるかもしれません）に影響し、メタデータの値はテンプレートに挿入されるとエスケープされます。

--metadata-file=FILE

Read metadata from the supplied YAML (or JSON) file. This option can be used with every input format, but string scalars in the YAML file will always be parsed as Markdown. (If the input format is Markdown or a Markdown variant, then the same variant will be used to parse the metadata file; if it is a non-Markdown format, pandoc’s default Markdown extensions will be used.) This option can be used repeatedly to include multiple metadata files; values in files specified later on the command line will be preferred over those specified in earlier files. Metadata values specified inside the document, or by using -M, overwrite values specified with this option. The file will be searched for first in the working directory, and then in the metadata subdirectory of the user data directory (see --data-dir).

-p, --preserve-tabs

タブ文字を、スペースに変換するのではなくそのまま保持します(既定ではPandocは入力を解析する前にタブ文字をスペースに変換します)。注意: インラインコード(literal code spans)とコードブロックのタブ文字のみ適用されます。通常のテキスト上にあるタブ文字は常にスペースとして扱われます。

--tab-stop=NUMBER

タブあたりのスペースの数を指定します（既定は4）

--track-changes=accept|reject|all

MS Word の「変更履歴の記録」機能によって生成された「挿入」、「削除」、および「コメント」の処理方法を指定します。

--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. Media are downloaded, read from the file system, or extracted from a binary container (e.g. docx), as needed. The original file paths are used if they are relative paths not containing ... Otherwise filenames are constructed from the SHA1 hash 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 found in this list will be followed by a nonbreaking space, and the period will not produce sentence-ending space in formats like LaTeX. The strings may not contain spaces.

--trace

Print diagnostic output tracing parser progress to stderr. This option is intended for use by developers in diagnosing performance issues.

一般的な Writer のオプション

-s, --standalone

適切なヘッダーとフッター (例えば、フラグメントではなく、スタンドアロンの HTML 、 LaTeX 、 TEI 、または RTF ファイル) を使用して出力を生成します。このオプションは pdf 、 epub 、 epub3 、 fb2 、 docx 、および odt 出力に対して自動的に設定されます。native 出力の場合、このオプションはメタデータを含めます。それ以外の場合、メタデータは抑制されます。

--template=FILE|URL

指定されたファイルを出力文書のためのカスタムテンプレートとして使用します。暗黙に --standalone も設定します。テンプレートの文法については、下記の Templates を参照してください。拡張子が指定されていない場合は、 Writer に対応する拡張子が追加されるます。つまり --template=special は HTML出力用に special.html を検索します。テンプレートが見つからない場合、Pandoc はユーザーデータディレクトリの templates サブディレクトリを検索します (--data-dir を参照)。このオプションが使われていない場合は、出力形式に応じて既定のテンプレートが使用されます (-D/--print-default-template を参照)。

-V KEY[=VAL], --variable=KEY[:VAL]

テンプレート変数 KEY に対して、値 VAL を指定します。スタンドアロンモード (-s) のみで有効です。もし VAL が指定されていなければ、その KEY に対する値は true となります。

--sandbox

Run pandoc in a sandbox, limiting IO operations in readers and writers to reading the files specified on the command line. Note that this option does not limit IO operations by filters or in the production of PDF documents. But it does offer security against, for example, disclosure of files through the use of include directives. Anyone using pandoc on untrusted user input should use this option.

-D FORMAT, --print-default-template=FORMAT

出力形式 FORMAT のために、システム既定のテンプレートを出力します。(利用可能な FORMAT の一覧については -t を参照) ユーザデータディレクトリ内のテンプレートは無視されます。このオプションの出力は -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

手動で改行コードを指定してください: crlf (Windows) 、 lf (macOS/Linux/UNIX) 、または native (pandoc が実行されているOSに適した改行コード)。既定は native です。

--dpi=NUMBER

ピクセルからインチ/センチメートルへの変換(またはその逆)を行うために、dpi (dots per inch; 1インチあたりのドット数) 値を指定します(正確にいえば、技術的に正しい用語はppi: 1インチあたりのピクセル数です)。デフォルトは96dpiです。画像内部にdpiに関する情報が含まれている場合、このオプションで指定された既定値ではなく、エンコードされた画像内部のdpi値が使用されます。

--wrap=auto|none|preserve

Determine how text is wrapped in the output (the source code, not the rendered version). With auto (the default), pandoc will attempt to wrap lines to the column width specified by --columns (default 72). With none, pandoc will not wrap lines at all. With preserve, pandoc will attempt to preserve the wrapping from the source document (that is, where there are nonsemantic newlines in the source, there will be nonsemantic newlines in the output as well). In ipynb output, this option affects wrapping of the contents of markdown cells.

--columns=NUMBER

行の長さは文字数で指定してください。これは生成されたソースコードでのテキストの折り返しに反映されます (--wrap を参照)。これはプレーンテキストでの表の列幅計算にも反映されます (下記の Tables を参照)。

--toc, --table-of-contents

出力文書に自動生成された目次を含めます（あるいは、 latex 、 context 、 docx 、 odt 、 opendocument 、 rst 、または ms の場合) 。このオプションは -s/--standalone を使わない限り影響がなく、 man 、 docbook4 、 docbook5 、 jats の出力にも影響がありません。

Note that if you are producing a PDF via ms, the table of contents will appear at the beginning of the document, before the title. If you would prefer it to be at the end of the document, use the option --pdf-engine-opt=--no-toc-relocation.

--toc-depth=NUMBER

目次に含めるセクションレベルを指定します。既定は3です(つまりレベル 1, 2, 3 の見出しが目次に表示されます) 。

--strip-comments

Markdown または Textile ソース内の HTML コメントは、生 (raw) の HTML として Markdown 、 Textile 、または HTML 出力に渡さずに取り除きます。 markdown_in_html_blocks 拡張が設定されていない場合、これは生 (raw) の HTML ブロック内の HTML コメントには適用されません。

--no-highlight

言語属性が指定されている場合でも、コードブロックとインラインのシンタックスハイライトを無効にします。

--highlight-style=STYLE|FILE

ソースコードのシンタックスハイライトに用いる色のスタイルを指定します。オプションは pygments (既定)、 kate , monochrome, breezeDark, espresso, zenburn, haddock, tango です。 pandocでのシンタックスハイライトの詳細については、下記の Syntax highlighting を参照してください。 (--list-highlight-styles も参照)

Instead of a STYLE name, a JSON file with extension .theme may be supplied. This will be parsed as a KDE syntax highlighting theme and (if valid) used as the highlighting style.

既存スタイルの JSON バージョンを生成するには、 --print-highlight-style を使用します。

--print-highlight-style=STYLE|FILE

ハイライトスタイルのJSON表記を出力します。これを編集して .theme 拡張子を付けて保存し、 --highlight-style オプションに指定できます。このオプションの出力は -o / --output によってファイルにリダイレクト出力できます。しかしコマンドラインでは -o / --output は --print-highlight-style の前に置く必要があります。

--syntax-definition=FILE

Instructs pandoc to load a KDE XML syntax definition file, which will be used for syntax highlighting of appropriately marked code blocks. This can be used to add support for new languages or to use altered syntax definitions for existing languages. This option may be repeated to add multiple syntax definitions.

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

FILE のコンテンツを、そのままヘッダの末尾に挿入します。たとえば、HTML文書に独自のCSSやJavaScriptを埋め込むことに利用できます。このオプションは複数のファイルを1つのヘッダに埋め込むために繰り返し使用できます。その順番はオプションで指定した通りになります。 --standalone を暗黙に指定します。

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

FILE のコンテンツを、そのまま本文 (body) の先頭 (すなわちHTMLでは <body> タグの後ろ、あるいはLaTeXでは \begin{document} コマンドの後ろ) に挿入します。HTML文書にナビゲーションバーやバナーを挿入するために使用できます。このオプションは複数のファイルを1つのヘッダに埋め込むために繰り返し使用できます。その順番はオプションで指定した通りになります。 --standalone を暗黙に指定します。

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

FILE のコンテンツを、そのまま本文 (body) の末尾 (すなわちHTMLでは </body> タグの前、あるいはLaTeXでは \end{document} コマンドの後ろ) に挿入します。このオプションは複数のファイルを1つのヘッダに埋め込むために繰り返し使用できます。その順番はオプションで指定した通りになります。 --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. This option can be used repeatedly. Search path components that come later on the command line will be searched before those that come earlier, so --resource-path foo:bar --resource-path baz:bim is equivalent to --resource-path baz:bim:foo:bar.

--request-header=NAME:VAL

HTTPリクエストを発行する際に、リクエストヘッダ NAME に値 VAL を設定します。たとえばコマンドラインでURLが指定されている場合や、文書中のあるリソースがダウンロードされる必要がある場合に利用できます。もしユーザがプロキシの後ろにいる場合には、環境変数 http_proxy  を http://... に設定する必要もあります。

--no-check-certificate

Disable the certificate verification to allow access to unsecure HTTP resources (for example when the certificate is no longer valid or self signed).

特定のWriterに関するオプション

--self-contained

Produce a standalone HTML file with no external dependencies, using data: URIs to incorporate the contents of linked scripts, stylesheets, images, and videos. Implies --standalone. The resulting file should be “self-contained,” in the sense that it needs no external files and no net access to be displayed properly by a browser. This option works only with HTML output formats, including html4, html5, html+lhs, html5+lhs, s5, slidy, slideous, dzslides, and revealjs. Scripts, images, and stylesheets at absolute URLs will be downloaded; those at relative URLs will be sought relative to the working directory (if the first source file is local) or relative to the base URL (if the first source file is remote). Elements with the attribute data-external="1" will be left alone; the documents they link to will not be incorporated in the document. Limitation: resources that are loaded dynamically through JavaScript cannot be incorporated; as a result, some advanced features (e.g. zoom or speaker notes) may not work in an offline “self-contained” reveal.js slide show.

--html-q-tags

Use <q> tags for quotes in HTML. (This option only has an effect if the smart extension is enabled for the input format used.)

--ascii

出力にASCII文字のみを使用します。現在はXMLおよびHTMLフォーマット(このオプションを選択するとUTF-8のかわりに実体参照を使用します)、CommonMark、gfm、およびマークダウン(実体参照を使用)、roff ms(16進数エスケープを使用)でサポートされており、LaTeX(可能であればアクセント付き文字のための標準コマンドを使用します)では一部サポートされています。roff manの出力はデフォルトでASCIIを使用します。

--reference-links

マークダウンまたは reStructuredTextを書き出す際にインラインリンクのかわりに参考文献スタイルのリンクを使用します。デフォルトでは、インラインリンクが使用されます。リンク先の位置は``--reference-location`` オプションに影響を受けます。

--reference-location=block|section|document

Specify whether footnotes (and references, if reference-links is set) are placed at the end of the current (top-level) block, the current section, or the document. The default is document. Currently this option only affects the markdown, muse, html, epub, slidy, s5, slideous, dzslides, and revealjs writers.

--markdown-headings=setext|atx

Specify whether to use ATX-style (#-prefixed) or Setext-style (underlined) headings for level 1 and 2 headings in Markdown output. (The default is atx.) ATX-style headings are always used for levels 3+. This option also affects Markdown cells in ipynb output.

--atx-headers

Deprecated synonym for ``--markdown-headings=atx``.

--top-level-division=default|section|chapter|part

Treat top-level headings as the given division type in LaTeX, ConTeXt, DocBook, and TEI output. The hierarchy order is part, chapter, then section; all headings are shifted such that the top-level heading becomes the specified type. The default behavior is to determine the best division type via heuristics: unless other conditions apply, section is chosen. When the documentclass variable is set to report, book, or memoir (unless the article option is specified), chapter is implied as the setting for this option. If beamer is the output format, specifying either chapter or part will cause top-level headings to become \part{..}, while second-level headings remain as their default type.

-N, --number-sections

Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB output. By default, sections are not numbered. Sections with class unnumbered will never be numbered, even if --number-sections is specified.

--number-offset=NUMBER[,NUMBER,…]

セクションヘッダのオフセット値。HTML出力に対してのみ適用されます (他の出力形式では無視されます)。1番目の値はトップレベル (レベル1) ヘッダのセクション番号に対して適用されます。2番目はレベル2ヘッダに対して、以下同様に適用されます。たとえば、文書のトップレベルヘッダに対して「6」というセクション番号を指定したい場合は、 --number-offset=5 を指定してください。一方で、文書をレベル2ヘッダから始める際に「1.5」というセクション番号を指定したい場合は、 --number-offset=1,4 を指定してください。オフセット値の既定は「0」です。このオプションは --number-sections を暗黙に指定します。

--listings

LaTeXのコードブロックに対して ```listings```_ パッケージを適用します。このパッケージは、ソースコードのマルチバイトエンコーディングをサポートしていません。UTF-8を扱うには、カスタムテンプレートを使う必要があります。この問題はここで完全に文書化されています: Encoding issue with the listings package

-i, --incremental

スライドショー中でリストアイテムをインクリメンタルに (1度に1つずつ) 表示するように変更します。既定ではリストは一気に表示されます。

--slide-level=NUMBER

Specifies that headings with the specified level create slides (for beamer, s5, slidy, slideous, dzslides). Headings above this level in the hierarchy are used to divide the slide show into sections; headings below this level create subheads within a slide. Valid values are 0-6. If a slide level of 0 is specified, slides will not be split automatically on headings, and horizontal rules must be used to indicate slide boundaries. If a slide level is not specified explicitly, the slide level will be set automatically based on the contents of the document; see Structuring the slide show.

--section-divs

セクションを <section> タグ (html4 向けには <div> タグ) で囲みます。そのセクションの識別子は見出しそのものではなく <section> (もしくは <div>) に含まれます。下記の Heading identifiers も参照。

--email-obfuscation=none|javascript|references

HTML文書において mailto: リンクを難読化 (obfuscating) する方法を指定します。 none は mailto: リンクをそのままにします。 javascript はJavaScriptを用いて難読化します。 references は文字列を十進数または十六進数の数値文字参照として出力することで難読化します。既定は none です。

--id-prefix=STRING

指定された接頭辞 (prefix) をすべての識別子、HTMLとDocBook出力の内部リンク、およびMarkdownとHaddock出力の脚注番号に付加します。たとえば文書の断片を他のページからインクルードして生成する際に、このオプションを使うと識別子の重複を防げて便利です。

-T STRING, --title-prefix=STRING

接頭辞 STRING を、HTMLヘッダにおけるtitle文字列の最初に挿入します (このtitleはHTML本文の最初に現れるものとは異なります)。暗黙に --standalone を指定します。

-c URL, --css=URL

CSSスタイルシートをリンクします。このオプションは複数のファイルをインクルードするために繰り返し指定できます。オプションを指定した通りの順番でインクルードされます。

EPUBを生成する場合、スタイルシートが必須です。もしこのオプション (もしくはメタデータのフィールドにおける css や stylesheet) が引数なしで指定された場合、Pandocは epub.css というファイルをユーザデータディレクトリ (--data-dir を参照) から探します。それでも見つからなければ、Pandocは自動で認識できる既定ファイル (sensible defaults) を利用しようとします。

--reference-doc=FILE

docxまたはodt出力のためのスタイル参照 (style reference) ファイルを指定します。

Docx

最良の出力を得るために、あらかじめスタイル参照用の docx ファイルを Pandoc で出力し、それを修正して用いるようにしてください。参照する docx の本文は無視されますが、そのスタイルシートと文書プロパティ（余白、ページサイズ、ヘッダー、フッターなど）は新しい docx で使用されます。コマンドラインでスタイル参照用 docx が指定されていない場合、Pandoc はユーザーデータディレクトリから reference.docx を探します (--data-dir を参照)。それでも見つからない場合は、Pandocは自動で認識できる既定ファイルを探します。

ユーザ用のカスタム reference.docx をつくるには、まずは既定の reference.docx のコピーを取得します: pandoc -o custom-reference.docx --print-default-data-file reference.docx を実行してください。次にWordで custom-reference.docx を開き、ユーザが望むようにスタイルを変更し保存します。最良の出力を得るためには、Pandocが利用する下記のスタイルを変更するようにし、それ以外は変更しないようにしてください:

段落スタイル:

  • Normal (標準)

  • Body Text (本文)

  • First Paragraph

  • Compact

  • Title (表題)

  • Subtitle (副題)

  • Author

  • Date

  • Abstract

  • Bibliography

  • Heading 1 (見出し1)

  • Heading 2 (見出し2)

  • Heading 3 (見出し3)

  • Heading 4 (見出し4)

  • Heading 5 (見出し5)

  • Heading 6 (見出し6)

  • Heading 7 (見出し7)

  • Heading 8 (見出し8)

  • Heading 9 (見出し9)

  • Block Text (ブロック)

  • Footnote Text

  • Definition Term

  • Definition

  • Caption

  • Table Caption

  • Image Caption

  • Figure

  • Captioned Figure

  • TOC Heading

文字スタイル:

  • Default Paragraph Font

  • Body Text Char

  • Verbatim Char

  • Footnote Reference

  • Hyperlink (ハイパーリンク)

  • Section Number

表スタイル:

  • Table

ODT

最良の出力を得るために、あらかじめスタイル参照用の ODT ファイルを Pandoc で出力し、それを修正して用いるようにしてください。参照する ODT の本文は無視されますが、そのスタイルシートは新しい ODT で使用されます。コマンドラインでスタイル参照用 ODT が指定されていない場合、Pandoc はユーザーデータディレクトリから reference.odt を探します (--data-dir を参照)。それでも見つからない場合は、Pandocは自動で認識できる既定ファイルを探します。

ユーザ用のカスタム reference.odt をつくるには、まずは既定の reference.odt のコピーを取得します: pandoc -o custom-reference.odt --print-default-data-file reference.odt を実行してください。次にLibreOfficeで custom-reference.odt を開き、ユーザが望むようにスタイルを変更し保存します。

PowerPoint

Microsoft PowerPoint 2013に含まれるテンプレート ( .pptx もしくは .potx のいずれかの拡張子) は、これから派生したほとんどのテンプレートと同様に機能するはずです。

The specific requirement is that the template should contain layouts with the following names (as seen within PowerPoint):

  • タイトル スライド

  • タイトルとコンテンツ

  • セクション見出し

  • 2 つのコンテンツ

  • Comparison

  • Content with Caption

  • Blank

For each name, the first layout found with that name will be used. If no layout is found with one of the names, pandoc will output a warning and use the layout with that name from the default reference doc instead. (How these layouts are used is described in PowerPoint layout choice.)

最近のバージョンの MS PowerPoint に含まれているすべてのテンプレートは、これらの基準に適合します。 (``ホーム``メニューの下にある``レイアウト``をクリックして確認できます。)

You can also modify the default reference.pptx: first run pandoc -o custom-reference.pptx --print-default-data-file reference.pptx, and then modify custom-reference.pptx in MS PowerPoint (pandoc will use the layouts with the names listed above).

--epub-cover-image=FILE

EPUBの表紙として、指定された画像を用います。縦横1000 px以内の画像サイズが推奨されます。ソースとなるMarkdown文書のYAMLメタデータブロックにおいて、 cover-image として表紙画像を指定することも可能です (下記の EPUB Metadata を参照してください)。

--epub-metadata=FILE

指定されたEPUBメタデータのXMLファイルを参照します。一連の Dublin Core elements を含める必要があります。次に例を示します：

<dc:rights>Creative Commons</dc:rights>
<dc:language>es-AR</dc:language>

デフォルトでは、Pandocは以下のメタデータ要素を含みます: <dc:title> (文書のタイトルから取得)、 <dc:creator> (文書の著者から取得)、 <dc:date> (文書の日付 (ISO 8601 format に準拠) から取得), <dc:language> (lang 変数から取得、lang 変数が設定されていない場合はロケールから取得), and <dc:identifier id="BookId"> (ランダムに生成された UUID)。なお、これらの要素はメタデータファイル中で明示的に設定できますが、その場合はメタデータファイルによる設定が優先されます。

注意: ソースファイル文書がMarkdown形式の場合、文書中のYAMLメタデータブロックが代わりに用いられます。詳しくは下記の EPUB Metadata を参照してください。

--epub-embed-font=FILE

EPUBファイルに指定したフォントを埋め込みます。複数のフォントを埋め込みたい場合は、このオプションを複数回用いてください。ワイルドカードも使用できます: たとえば、 DejaVuSans-*.ttf と指定することで、DejaVuSansフォントファミリーを埋め込むことができます。ただし、コマンドライン上でワイルドカードを使用する場合は、シェル上で解釈されないように、ワイルドカードをエスケープするか、フォントファイル名をシングルクォートで囲む必要があります。埋め込みフォントを使用するためには、CSSファイルに以下のような宣言を追加する必要があります (--css を参照してください):

@font-face {
font-family: DejaVuSans;
font-style: normal;
font-weight: normal;
src:url("DejaVuSans-Regular.ttf");
}
@font-face {
font-family: DejaVuSans;
font-style: normal;
font-weight: bold;
src:url("DejaVuSans-Bold.ttf");
}
@font-face {
font-family: DejaVuSans;
font-style: italic;
font-weight: normal;
src:url("DejaVuSans-Oblique.ttf");
}
@font-face {
font-family: DejaVuSans;
font-style: italic;
font-weight: bold;
src:url("DejaVuSans-BoldOblique.ttf");
}
body { font-family: "DejaVuSans"; }
--epub-chapter-level=NUMBER

EPUBを個別の “chapter(章)” ファイルに分割する見出しのレベルを設定します。デフォルトでは、レベル1の見出しごとに章ファイルが分割されます。このオプションは、EPUBの内部構成にのみ影響するものであり、ユーザサイドでの章や節の表示方法には影響しません。章ファイルのサイズが大きすぎると、一部のEPUBリーダの動作が遅くなることがあります。そのため、EPUBに変換するドキュメントのファイルサイズが大きく，かつレベル1の見出しが少ない場合、レベル2か3の見出しレベルを設定したほうがよいでしょう。

--epub-subdirectory=DIRNAME

EPUBに固有のコンテンツを含むOCFコンテナのサブディレクトリを指定します。デフォルトは EPUB です。 EPUBのコンテンツを最上位に配置したい場合は、空の文字列を使用してください。

--ipynb-output=all|none|best

入力されたipynbファイルにおける出力セルの処理方法を決定します。 all を指定すると、元ファイルに含まれるデータ形式がすべて保持されます。 none を指定すると、データセルの内容が省略されます。 best を指定すると、Pandocは、それぞれの出力セルに対して、出力形式と互換性のある最もリッチな表現を可能とするデータブロックを選択しようとします。デフォルトは best です。

--pdf-engine=PROGRAM

Use the specified engine when producing PDF output. Valid values are pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtmltopdf, weasyprint, pagedjs-cli, prince, context, and pdfroff. If the engine is not in your PATH, the full path of the engine may be specified here. If this option is not specified, pandoc uses the following defaults depending on the output format specified using -t/--to:

  • -t latex または未指定: pdflatex (他のオプション: xelatex, lualatex, tectonic, latexmk)

  • -t context: context

  • -t html: wkhtmltopdf (other options: prince, weasyprint, pagedjs-cli; see print-css.rocks for a good introduction to PDF generation from HTML/CSS.)

  • -t ms: pdfroff

--pdf-engine-opt=STRING

pdf-engine に対するコマンドライン引数を与えます。たとえば latexmk の補助ファイルを保存するためのディレクトリを指定するには --pdf-engine-opt=-outdir=foo と指定します。注意：オプション引数の重複チェックは行いません。

引用文献の生成

-C, --citeproc

Process the citations in the file, replacing them with rendered citations and adding a bibliography. Citation processing will not take place unless bibliographic data is supplied, either through an external file specified using the --bibliography option or the bibliography field in metadata, or via a references section in metadata containing a list of citations in CSL YAML format with Markdown formatting. The style is controlled by a CSL stylesheet specified using the --csl option or the csl field in metadata. (If no stylesheet is specified, the chicago-author-date style will be used by default.) The citation processing transformation may be applied before or after filters or Lua filters (see --filter, --lua-filter): these transformations are applied in the order they appear on the command line. For more information, see the section on Citations.

--bibliography=FILE

Set the bibliography field in the document’s metadata to FILE, overriding any value set in the metadata. If you supply this argument multiple times, each FILE will be added to bibliography. If FILE is a URL, it will be fetched via HTTP. If FILE is not found relative to the working directory, it will be sought in the resource path (see --resource-path).

--csl=FILE

Set the csl field in the document’s metadata to FILE, overriding any value set in the metadata. (This is equivalent to --metadata csl=FILE.) If FILE is a URL, it will be fetched via HTTP. If FILE is not found relative to the working directory, it will be sought in the resource path (see --resource-path) and finally in the csl subdirectory of the pandoc user data directory.

--citation-abbreviations=FILE

Set the citation-abbreviations field in the document’s metadata to FILE, overriding any value set in the metadata. (This is equivalent to --metadata citation-abbreviations=FILE.) If FILE is a URL, it will be fetched via HTTP. If FILE is not found relative to the working directory, it will be sought in the resource path (see --resource-path) and finally in the csl subdirectory of the pandoc user data directory.

--natbib

Use `natbib```_ for citations in LaTeX output. This option is not for use with the ``--citeproc option or with PDF output. It is intended for use in producing a LaTeX file that can be processed with ```bibtex```_.

--biblatex

Use `biblatex```_ for citations in LaTeX output. This option is not for use with the ``--citeproc option or with PDF output. It is intended for use in producing a LaTeX file that can be processed with ```bibtex```_ or ```biber```_.

HTMLにおける数式の生成

デフォルトでは、可能な限りUnicode文字を用いてTeX数式を生成します。数式は、 class = "math" としてクラス指定された span タグ内に置かれます。このため、必要に応じて、数式をそれ以外のテキストとは異なるスタイルにすることができます。ただし、この方法によって妥当な数式が生成されるのは、基本的な数式においてのみであり、通常は --mathjax もしくは次のオプションのいずれかを使用するのが好ましいです。

--mathjax[=URL]

HTML出力に埋め込まれたTeX数式を、 MathJax を用いて表示します。 TeX数式は、インライン数式モードの場合は \( と \) の間に、ディスプレイ数式モードの場合は \[ と \] の間に置かれ、さらにそれらが math クラスが指定された <span> タグ内に置かれます。これはその後、MathJax JavaScriptによって数式表示されます。 URL には、 MathJax.js のスクリプトを呼び出すサーバを指定する必要があります。 *URL*が指定されていない場合、Cloudflare CDNへのリンクが挿入されます。

--mathml

epub3 、docbook4 、 docbook5、jats 、 html4 および html5 において、TeX数式を MathML に変換します。これは、 odt 出力におけるデフォルトです。現在のところ、MathMLをネイティブでサポートしているのは、FirefoxとSafari (および一部の電子書籍リーダー) のみであることに注意してください。

--webtex[=URL]

Convert TeX formulas to <img> tags that link to an external script that converts formulas to images. The formula will be URL-encoded and concatenated with the URL provided. For SVG images you can for example use --webtex https://latex.codecogs.com/svg.latex?. If no URL is specified, the CodeCogs URL generating PNGs will be used (https://latex.codecogs.com/png.latex?). Note: the --webtex option will affect Markdown output as well as HTML, which is useful if you’re targeting a version of Markdown without native math support.

--katex[=URL]

KaTeX を使用して、埋め込みTeX数式をHTML出力に表示します。 URL は、KaTeXライブラリのURLを指定します。指定したKaTeXライブラリディレクトリには、 katex.min.js と katex.min.css ファイルが含まれている必要があります。 URL が与えられていない場合、KaTeX CDNへのリンクが挿入されます。

--gladtex

Enclose TeX math in <eq> tags in HTML output. The resulting HTML can then be processed by GladTeX to produce SVG images of the typeset formulas and an HTML file with these images embedded.

pandoc -s --gladtex input.md -o myfile.htex
gladtex -d image_dir myfile.htex
# produces myfile.html and images in image_dir

ラッパースクリプト向けのオプション

--dump-args

標準出力 にコマンドライン引数に関する情報を出力して終了します。このオプションは主にラッパースクリプト向けです。出力の1行目は -o  オプションで指定される出力ファイル名、もしくは出力ファイルが指定されていない場合の - (標準出力) です。残りの行はコマンドライン引数 (訳注: 入力ファイル) が1行ごとに引数が出現した順に並びます。通常のPandocオプションとそのパラメータは含まれません。コマンド行の末尾に -- セパレータを付けたときは、その後続のオプションは必ず含まれます。

--ignore-args

コマンドライン引数 (訳注: 入力ファイル) を無視します。ラッパースクリプト向け。通常のPandocオプションは無視されます。つまり次のようになります：

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

は以下と等しい

pandoc -o foo.html -s

終了コード

Pandoc が正常に完了すると、終了コード 0 が返されます。ゼロ以外の終了コードは、次の意味を持ちます。

コード

エラー

1

PandocIOError

3

PandocFailOnWarningError

4

PandocAppError

5

PandocTemplateError

6

PandocOptionError

21

PandocUnknownReaderError

22

PandocUnknownWriterError

23

PandocUnsupportedExtensionError

24

PandocCiteprocError

25

PandocBibliographyError

31

PandocEpubSubdirectoryError

43

PandocPDFError

44

PandocXMLError

47

PandocPDFProgramNotFoundError

61

PandocHttpError

62

PandocShouldNeverHappenError

63

PandocSomeError

64

PandocParseError

65

PandocParsecError

66

PandocMakePDFError

67

PandocSyntaxMapError

83

PandocFilterError

84

PandocLuaError

91

PandocMacroLoop

92

PandocUTF8DecodingError

93

PandocIpynbDecodingError

94

PandocUnsupportedCharsetError

97

PandocCouldNotFindDataFileError

98

PandocCouldNotFindMetadataFileError

99

PandocResourceNotFound

Defaults files

The --defaults option may be used to specify a package of options, in the form of a YAML file.

省略したフィールドには通常の既定値が割り当てられます。よってデフォルトファイルは次のような1行でシンプルに書けます：

verbosity: INFO

In fields that expect a file path (or list of file paths), the following syntax may be used to interpolate environment variables:

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

${USERDATA} may also be used; this will always resolve to the user data directory that is current when the defaults file is parsed, regardless of the setting of the environment variable USERDATA.

${.} will resolve to the directory containing the defaults file itself. This allows you to refer to resources contained in that directory:

epub-cover-image: ${.}/cover.jpg
epub-metadata: ${.}/meta.xml
resource-path:
- .             # the working directory from which pandoc is run
- ${.}/images   # the images subdirectory of the directory
                # containing this defaults file

This environment variable interpolation syntax only works in fields that expect file paths.

Defaults files can be placed in the defaults subdirectory of the user data directory and used from any directory. For example, one could create a file specifying defaults for writing letters, save it as letter.yaml in the defaults subdirectory of the user data directory, and then invoke these defaults from any directory using pandoc --defaults letter or pandoc -dletter.

複数の既定値がセットされた場合、それらの値は結合されます。

注意：コマンドライン引数が複数繰り返された場合は (--metadata-file, --css, --include-in-header, --include-before-body, --include-after-body, --variable, --metadata, --syntax-definition) 、コマンドライン上のそれらの値が (上書きされるのではなく) デフォルトファイルに指定された値と結合されます。

The following tables show the mapping between the command line and defaults file entries.

command line

defaults file

 
foo.md

input-file: foo.md

foo.md bar.md

input-files:
  - foo.md
  - bar.md

The value of input-files may be left empty to indicate input from stdin, and it can be an empty sequence [] for no input.

一般的なオプション

command line

defaults file

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

Options specified in a defaults file itself always have priority over those in another file included with a defaults: entry.

verbosity can have the values ERROR, WARNING, or INFO.

Readerのオプション

command line

defaults file

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

 --filter pandoc-citeproc \

--lua-filter count-words.lua \
  --filter special.lua

filters:
  - pandoc-citeproc
  - count-words.lua
  - type: json
    path: special.lua

--metadata key=value \
 --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

Metadata values specified in a defaults file are parsed as literal string text, not Markdown.

Filters will be assumed to be Lua filters if they have the .lua extension, and JSON filters otherwise. But the filter type can also be specified explicitly, as shown. Filters are run in the order specified. To include the built-in citeproc filter, use either citeproc or {type: citeproc}.

一般的な Writer のオプション

command line

defaults file

 
--standalone

standalone: true

--template letter

template: letter

--variable key=val \
  --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

特定のWriterに関するオプション

command line

defaults file

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

--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  \
  --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-metadata meta.xml

epub-metadata: meta.xml

--epub-embed-font special.otf \

 --epub-embed-font headline.otf

epub-fonts:
  - special.otf
  - headline.otf

--epub-chapter-level 2

epub-chapter-level: 2

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

引用文献の生成

command line

defaults file

 
--citeproc

citeproc: true

--bibliography logic.bib

metadata:
  bibliography: logic.bib

--csl ieee.csl

metadata:
  csl: ieee.csl

--citation-abbreviations ab.json

 metadata:

citation-abbreviations: ab.json

--natbib

cite-method: natbib

--biblatex

cite-method: biblatex

cite-method can be citeproc, natbib, or biblatex. This only affects LaTeX output. If you want to use citeproc to format citations, you should also set ‘citeproc: true’.

If you need control over when the citeproc processing is done relative to other filters, you should instead use citeproc in the list of filters (see above).

HTMLにおける数式の生成

command line

defaults file

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

In addition to the values listed above, method can have the value plain.

If the command line option accepts a URL argument, an url: field can be added to html-math-method:.

ラッパースクリプト向けのオプション

command line

defaults file

 
--dump-args

dump-args: true

--ignore-args

ignore-args: true

テンプレート

-s/--standalone オプションが使用された場合、独立した文書 (self-standing document) に必要なヘッダとフッタを追加するために、Pandocはテンプレートを用います。既定のテンプレートを参照するには、次を実行します:

pandoc -D *FORMAT*

ここで *FORMAT* は出力形式の名前です (以下同様)。カスタムテンプレートは --template で指定できます。システム上の既定のテンプレートを上書きしたい場合は、ユーザデータディレクトリ (上記の --data-dir を参照) に、 templates/default.*FORMAT* という形のファイル名で保存してください。 ただし以下は例外です:

  • odt 出力については、 default.opendocument テンプレートをカスタマイズします。

  • pdf 出力については、 default.latex テンプレートをカスタマイズします。(-t context を使う場合は default.context テンプレート、 -t ms の場合は default.ms テンプレート、-t html の場合は default.html テンプレートをカスタマイズします)

  • docx および pptx には、テンプレートがありません (出力をカスタマイズするために --reference-doc を使うことはできます)。

テンプレートは 変数 を含みます。変数によって、ファイルのどの位置でも任意の情報を含めることが可能です。変数はコマンドラインで -V/--variable オプションを用いてセットできます。変数がセットされていない場合、Pandocは文書のメタデータからキーを検索します。このメタデータは YAML metadata blocks または -M/--metadata オプションによって指定可能です。さらに、いくつかの値はPandocによって既定値が与えられます。既定のテンプレートで用いられる変数のリストは、下記の Variables をご覧ください。

もしユーザがテンプレートをカスタマイズしているときは、Pandocの更新に伴いカスタムテンプレートも更新する必要する必要があります。できれば既定のテンプレートの変更をトラッキングした上で、その変更に応じてカスタムテンプレートを変更することをお勧めします。このトラッキングを簡単に行うには pandoc-templates リポジトリをForkし、Pandocのリリースごとに変更をマージするとよいでしょう。

テンプレートの文法

コメント

$-- から行末までの部分はコメントとして扱われ、出力されません。

Delimiters

To mark variables and control structures in the template, either $…$ or ${…} may be used as delimiters. The styles may also be mixed in the same template, but the opening and closing delimiter must match in each case. The opening delimiter may be followed by one or more spaces or tabs, which will be ignored. The closing delimiter may be followed by one or more spaces or tabs, which will be ignored.

To include a literal $ in the document, use $$.

Interpolated variables

A slot for an interpolated variable is a variable name surrounded by matched delimiters. Variable names must begin with a letter and can contain letters, numbers, _, -, and .. The keywords it, if, else, endif, for, sep, and endfor may not be used as variable names. Examples:

$foo$
$foo.bar.baz$
$foo_bar.baz-bim$
$ foo $
${foo}
${foo.bar.baz}
${foo_bar.baz-bim}
${ foo }

Variable names with periods are used to get at structured variable values. So, for example, employee.salary will return the value of the salary field of the object that is the value of the employee field.

  • If the value of the variable is simple value, it will be rendered verbatim. (Note that no escaping is done; the assumption is that the calling program will escape the strings appropriately for the output format.)

  • If the value is a list, the values will be concatenated.

  • If the value is a map, the string true will be rendered.

  • Every other value will be rendered as the empty string.

Conditionals

A conditional begins with if(variable) (enclosed in matched delimiters) and ends with endif (enclosed in matched delimiters). It may optionally contain an else (enclosed in matched delimiters). The if section is used if variable has a non-empty value, otherwise the else section is used (if present). Examples:

$if(foo)$bar$endif$

$if(foo)$
  $foo$
$endif$

$if(foo)$
part one
$else$
part two
$endif$

${if(foo)}bar${endif}

${if(foo)}
  ${foo}
${endif}

${if(foo)}
${ foo.bar }
${else}
no foo!
${endif}

The keyword elseif may be used to simplify complex nested conditionals:

$if(foo)$
XXX
$elseif(bar)$
YYY
$else$
ZZZ
$endif$

For loops

A for loop begins with for(variable) (enclosed in matched delimiters) and ends with endfor (enclosed in matched delimiters.

  • If variable is an array, the material inside the loop will be evaluated repeatedly, with variable being set to each value of the array in turn, and concatenated.

  • If variable is a map, the material inside will be set to the map.

  • If the value of the associated variable is not an array or a map, a single iteration will be performed on its value.

例:

$for(foo)$$foo$$sep$, $endfor$

$for(foo)$
  - $foo.last$, $foo.first$
$endfor$

${ for(foo.bar) }
  - ${ foo.bar.last }, ${ foo.bar.first }
${ endfor }

$for(mymap)$
$it.name$: $it.office$
$endfor$

You may optionally specify a separator between consecutive values using sep (enclosed in matched delimiters). The material between sep and the endfor is the separator.

${ for(foo) }${ foo }${ sep }, ${ endfor }

Instead of using variable inside the loop, the special anaphoric keyword it may be used.

${ for(foo.bar) }
  - ${ it.last }, ${ it.first }
${ endfor }

Partials

Partials (subtemplates stored in different files) may be included by using the name of the partial, followed by (), for example:

${ styles() }

Partials will be sought in the directory containing the main template. The file name will be assumed to have the same extension as the main template if it lacks an extension. When calling the partial, the full name including file extension can also be used:

${ styles.html() }

(If a partial is not found in the directory of the template and the template path is given as a relative path, it will also be sought in the templates subdirectory of the user data directory.)

Partials may optionally be applied to variables using a colon:

${ date:fancy() }

${ articles:bibentry() }

If articles is an array, this will iterate over its values, applying the partial bibentry() to each one. So the second example above is equivalent to

${ for(articles) }
${ it:bibentry() }
${ endfor }

Note that the anaphoric keyword it must be used when iterating over partials. In the above examples, the bibentry partial should contain it.title (and so on) instead of articles.title.

Final newlines are omitted from included partials.

Partials may include other partials.

A separator between values of an array may be specified in square brackets, immediately after the variable name or partial:

${months[, ]}$

${articles:bibentry()[; ]$

The separator in this case is literal and (unlike with sep in an explicit for loop) cannot contain interpolated variables or other template directives.

Nesting

To ensure that content is “nested,” that is, subsequent lines indented, use the ^ directive:

$item.number$  $^$$item.description$ ($item.price$)

In this example, if item.description has multiple lines, they will all be indented to line up with the first line:

00123  A fine bottle of 18-year old
       Oban whiskey. ($148)

To nest multiple lines to the same level, align them with the ^ directive in the template. For example:

$item.number$  $^$$item.description$ ($item.price$)
               (Available til $item.sellby$.)

will produce

00123  A fine bottle of 18-year old
       Oban whiskey. ($148)
       (Available til March 30, 2020.)

If a variable occurs by itself on a line, preceded by whitespace and not followed by further text or directives on the same line, and the variable’s value contains multiple lines, it will be nested automatically.

Breakable spaces

Normally, spaces in the template itself (as opposed to values of the interpolated variables) are not breakable, but they can be made breakable in part of the template by using the ~ keyword (ended with another ~).

$~$This long line may break if the document is rendered
with a short line length.$~$

Pipes

A pipe transforms the value of a variable or partial. Pipes are specified using a slash (/) between the variable name (or partial) and the pipe name. Example:

$for(name)$
$name/uppercase$
$endfor$

$for(metadata/pairs)$
- $it.key$: $it.value$
$endfor$

$employee:name()/uppercase$

Pipes may be chained:

$for(employees/pairs)$
$it.key/alpha/uppercase$. $it.name$
$endfor$

Some pipes take parameters:

|----------------------|------------|
$for(employee)$
$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
$endfor$
|----------------------|------------|

Currently the following pipes are predefined:

  • pairs: Converts a map or array to an array of maps, each with key and value fields. If the original value was an array, the key will be the array index, starting with 1.

  • uppercase: Converts text to uppercase.

  • lowercase: Converts text to lowercase.

  • length: Returns the length of the value: number of characters for a textual value, number of elements for a map or array.

  • reverse: Reverses a textual value or array, and has no effect on other values.

  • first: Returns the first value of an array, if applied to a non-empty array; otherwise returns the original value.

  • last: Returns the last value of an array, if applied to a non-empty array; otherwise returns the original value.

  • rest: Returns all but the first value of an array, if applied to a non-empty array; otherwise returns the original value.

  • allbutlast: Returns all but the last value of an array, if applied to a non-empty array; otherwise returns the original value.

  • chomp: Removes trailing newlines (and breakable space).

  • nowrap: Disables line wrapping on breakable spaces.

  • alpha: Converts textual values that can be read as an integer into lowercase alphabetic characters a..z (mod 26). This can be used to get lettered enumeration from array indices. To get uppercase letters, chain with uppercase.

  • roman: Converts textual values that can be read as an integer into lowercase roman numerials. This can be used to get lettered enumeration from array indices. To get uppercase roman, chain with uppercase.

  • left n "leftborder" "rightborder": Renders a textual value in a block of width n, aligned to the left, with an optional left and right border. Has no effect on other values. This can be used to align material in tables. Widths are positive integers indicating the number of characters. Borders are strings inside double quotes; literal " and \ characters must be backslash-escaped.

  • right n "leftborder" "rightborder": Renders a textual value in a block of width n, aligned to the right, and has no effect on other values.

  • center n "leftborder" "rightborder": Renders a textual value in a block of width n, aligned to the center, and has no effect on other values.

Variables

メタデータに関する変数

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

Note that if you just want to set PDF or HTML metadata, without including a title block in the document itself, you can set the title-meta, author-meta, and date-meta variables. (By default these are set automatically, based on title, author, and date.) The page title in HTML is set by pagetitle, which is equal to title by default.

subtitle

文書のサブタイトル (HTML, EPUB, LaTeX, ConTeXt, docxのみ)

abstract

文書の要約・概要 (LaTeX, ConTeXt, AsciiDoc, docx のみ)

abstract-title

title of abstract, currently used only in HTML and EPUB. This will be set automatically to a localized value, depending on lang, but can be manually overridden.

keywords

キーワードの一覧 (HTML, PDF, ODT, pptx, docx, AsciiDoc のメタデータ); 上記の author のように複数個を記述可能

subject

document subject, included in ODT, PDF, docx, EPUB, and pptx metadata

description

文書の説明 (ODT, docx, pptx のメタデータ); 一部のアプリケーションではこれは Comments (コメント) メタデータとして表示します。

category

文書のカテゴリー (docx, pptx のメタデータ)

Additionally, any root-level string metadata, not included in ODT, docx or pptx metadata is added as a custom property. The following YAML metadata block for instance:

---
title:  'This is the title'
subtitle: "This is the subtitle"
author:
- Author One
- Author Two
description: |
    This is a long
    description.

    It consists of two paragraphs
...

このとき title, author および description は、標準的な文書のプロパティとして扱われます。一方 subtitle は、docx, ODT もしくは pptx に変換する際にはカスタムプロパティとして扱われます。

言語に関する変数

lang

文書で使われる主な言語を指定します。 en または en-GB のようなIETF言語タグを使用してください (BCP 47 標準にしたがいます)。 Language subtag lookup を使うとタグを検索および検証できます。この指定は大半の形式に影響します。特に LaTeX (具体的には ```babel```_ および ```polyglossia```_) または ConTeXt を用いるPDF出力では、PDFのハイフネーションが制御されます。

言語を切り替えるには、ネイティブPandoc Divs and Spans を用いて lang 属性をその都度指定してください。

---
lang: en-GB
...

Text in the main document language (British English).

::: {lang=fr-CA}
> Cette citation est écrite en français canadien.
:::

More text in English. ['Zitat auf Deutsch.']{lang=de}
dir

文字表記の方向（左右）を指定します。 rtl (right-to-left) または ltr (left-to-right) のいずれかです。

双方向テキストによる文書においてベースの方向を上書きする場合には、ネイティブPandoc span および div によって、 dir 属性 (値は rtl` または ltr) を指定してください (一部の出力形式のみに対応)。もし最終的なレンダリングエンジン (すなわちHTMLを生成するブラウザなど) が Unicode Bidirectional Algorithm をサポートする場合には、この指定が必要ないかもしれません。

LaTeXで双方向テキストによる文書を扱う際には、 xelatex エンジン (--pdf-engine=xelatex) のみが完全にサポートします。

Variables for HTML

document-css

Enables inclusion of most of the CSS in the styles.html partial (have a look with pandoc --print-default-data-file=templates/styles.html). Unless you use `--css```_, this variable is set to ``true by default. You can disable it with e.g. pandoc -M document-css=false.

mainfont

sets the CSS font-family property on the html element.

fontsize

sets the base CSS font-size, which you’d usually set to e.g. 20px, but it also accepts pt (12pt = 16px in most browsers).

fontcolor

sets the CSS color property on the html element.

linkcolor

sets the CSS color property on all links.

monofont

sets the CSS font-family property on code elements.

monobackgroundcolor

sets the CSS background-color property on code elements and adds extra padding.

linestretch

sets the CSS line-height property on the html element, which is preferred to be unitless.

backgroundcolor

sets the CSS background-color property on the html element.

margin-left, margin-right, margin-top, margin-bottom

sets the corresponding CSS padding properties on the body element.

To override or extend some CSS for just one document, include for example:

---
header-includes: |
  <style>
  blockquote {
    font-style: italic;
  }
  tr.even {
    background-color: #f0f0f0;
  }
  td, th {
    padding: 0.5em 2em 0.5em 0.5em;
  }
  tbody {
    border-bottom: none;
  }
  </style>
---

Variables for HTML math

classoption

when using KaTeX, you can render display math equations flush left using YAML metadata or with -M classoption=fleqn.

HTMLスライド用の変数

These affect HTML output when [producing slide shows with pandoc].

institute

著者の所属 (著者が複数いる場合はリストになりうる)

revealjs-url

base URL for reveal.js documents (defaults to https://unpkg.com/reveal.js@^4/)

s5-url

S5文書のベースURL (既定: s5/default)

slidy-url

Slidy文書のベースURL (既定: https://www.w3.org/Talks/Tools/Slidy2)

slideous-url

Slideous文書のベースURL (既定: slideous)

title-slide-attributes

additional attributes for the title slide of reveal.js slide shows. See [background in reveal.js and beamer] for an example.

All reveal.js configuration options are available as variables. To turn off boolean flags that default to true in reveal.js, use 0.

Beamerスライド用の変数

次に示す変数は、LaTeX ```beamer```_ を用いたPDFスライドの見た目を変更します。

aspectratio

スライドのアスペクト比 (43 → 4:3 [既定], 169 → 16:9, 1610 → 16:10, 149 → 14:9, 141 → 1.41:1, 54 → 5:4, 32 → 3:2)

`beameroption

\setbeameroption{} に指定する追加のBeamerオプション

institute

著者の所属 (著者が複数いる場合はリストになりうる)

logo

各スライドに付けるロゴ画像

navigation

コントールナビゲーションの記号 (既定では記号を表示しない empty ; 他には frame, vertical, および horizontal が指定可能)

section-titles [boolean]

新しいセクション (section) ごとに “title pages” を行う (既定: true)

theme, colortheme, fonttheme, innertheme, outertheme

beamer themes

themeoptions

Beamerのテーマに対するオプション (リスト)

titlegraphic

タイトルスライドの画像

Variables for PowerPoint

These variables control the visual aspects of a slide show that are not easily controlled via templates.

monofont

font to use for code.

LaTeX用の変数

Pandocは creating a PDF でLaTeXエンジンを用いる場合、下記の変数を用います。

レイアウト
block-headings [boolean]

\paragraph および \subparagraph を生成します。それぞれヘッダレベルは 4 および 5 (book系クラスの場合は 5 および 6) です。本文に追い込む (run-in) のではなく独立した (free-standing) パラグラフをつくります。 \subsubsection (ヘッダレベル 3 または 4) と区別するために、さらなる書式づけを必要とします。このオプションの代わりに、 KOMA-Script ではさらに広範囲にわたってヘッダを調整できます:

---
documentclass: scrartcl
header-includes: |
  \RedeclareSectionCommand[
    beforeskip=-10pt plus -2pt minus -1pt,
    afterskip=1sp plus -1sp minus 1sp,
    font=\normalfont\itshape]{paragraph}
  \RedeclareSectionCommand[
    beforeskip=-10pt plus -2pt minus -1pt,
    afterskip=1sp plus -1sp minus 1sp,
    font=\normalfont\scshape,
    indent=0pt]{subparagraph}
...
classoption

option for document class, e.g. oneside; repeat for multiple options:

---
classoption:
- twocolumn
- landscape
...
documentclass

文書クラス。通常は `article```_, ```book```_, ```report```_ のうちいずれか文書クラスを指定します。 `KOMA-Script`_ では ``scrartcl, scrbook, scrreprt に対応し、既定では最も小さいマージンを用います。 ```memoir```_ も利用できます。

geometry

option for `geometry```_ package, e.g. ``margin=1in; repeat for multiple options:

---
geometry:
- top=30mm
- left=20mm
- heightrounded
...
hyperrefoptions

option for `hyperref```_ package, e.g. ``linktoc=all; repeat for multiple options:

---
hyperrefoptions:
- linktoc=all
- pdfwindowui
- pdfpagemode=FullScreen
...
indent [boolean]

if true, pandoc will use document class settings for indentation (the default LaTeX template otherwise removes indentation and adds space between paragraphs)

linestretch

adjusts line spacing using the `setspace```_ package, e.g. ``1.25, 1.5

margin-left, margin-right, margin-top, margin-bottom

geometry を使用しない場合のマージン (設定がない場合、 geometry がこれらを上書きします)

pagestyle

\pagestyle{} を制御します (訳注: 文書全体のページ形式の指定: ノンブル (ページ番号) や柱を設定できる)。既定のarticleクラスでは plain (既定の値), empty (柱やノンブルなどを付けない) および headings (柱にセクション名) が利用できます。

papersize

用紙サイズ (例: letter, a4)

secnumdepth

セクションなどに対する番号づけの深さ (depth) (--number-sections または numbersections 変数の有効時のみ)

beamerarticle

Beamerスライドから article を生成する (訳注: Beamerのarticleモード / beamerarticle パッケージ)

フォント
fontenc

フォントのエンコーディングを fontenc パッケージによって指定 (pdflatex のみ); 既定では T1 エンコーディングを用います。(詳しくは LaTeX font encodings guide を参照)

fontfamily

pdflatex においてフォントパッケージを利用します。 TeX Live にはさまざまなオプションがあり、 LaTeX Font Catalogue に記載されています。既定は Latin Modern です。

fontfamilyoptions

fontfamily パッケージのオプション; 複数のオプションを指定可能。たとえば `libertinus```_ パッケージを用いて、Libertineフォントに対して ``p (proportional) と osf (lowercase / old-style figures) オプションを指定したい場合には、次のように書きます:

---
fontfamily: libertinus
fontfamilyoptions:
- osf
- p
...
fontsize

本文テキストのフォントサイズ。(訳注: 欧文の) 標準的な文書クラスでは 10pt, 11pt, および 12pt を指定できます。(訳注: 欧文において) 他のサイズを指定するには KOMA-Script の文書クラスのうちひとつ (scrartcl や scrbook など) を documentclass に指定してください。(訳注: `BXjscls`_ や `LuaTeX-ja`_ の文書クラスを用いている場合は、それぞれのマニュアルに書かれているフォントサイズが利用できます)

mainfont, sansfont, monofont, mathfont, CJKmainfont

xelatex または lualatex におけるフォントファミリー。 `fontspec```_ パッケージを用いて、任意のシステムフォント (訳注: OpenType あるいは TrueType の Unicode フォント) の名前を指定します。 ``CJKmainfont は `xecjk```_ パッケージを利用します。(訳注: ``lualatex 利用時に CJKmainfont を指定すると、 `LuaTeX-ja`_ の luatexja-fontspec パッケージが読み込まれます。このとき CJKmainfont の値は \setmainjfont として指定されます。)

mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions, CJKoptions

xelatex および lualatex における mainfont, sansfont, monofont, mathfont, CJKmainfont のオプション。 ```fontspec```_ で利用できるすべてのオプションの組み合わせが利用でき、複数指定可能です。たとえば TeX Gyre バージョンの Palatino フォントに lowercase figures を適用する場合は次のようになります:

---
mainfont: TeX Gyre Pagella
mainfontoptions:
- Numbers=Lowercase
- Numbers=Proportional
...
microtypeoptions

microtype パッケージに渡されるオプション

前付 (front matter)
lof, lot [boolean]

図目次および表目次を挿入します。

thanks

文書タイトルの後の謝辞・注意書きなどを表す脚注 (訳注: LaTeXの \thanks)

toc [boolean]

目次を挿入します。(--toc/--table-of-contents でも設定可能)

toc-depth

挿入される目次に対するセクションレベル

BibLaTeXによる参考文献リスト

以下の変数はBibLaTeXで citation rendering を行うために用います。

biblatexoptions

BibLaTeX用のオプションリスト

biblio-style

--natbib および --biblatex による引用スタイル

biblio-title

--natbib および --biblatex による参考文献リストのタイトル

bibliography

引用する元となる参考文献一覧 (訳注: bibファイルなどの文献データベース)

natbiboptions

natbib向けのオプションリスト

ConTeXt用の変数

Pandocでは creating a PDF でConTeXtを使う際に、下記の変数を利用します。

fontsize

本文テキストのフォントサイズ (例: 10pt, 12pt)

headertext, footertext

(それぞれページの天と地の) 柱に配置されるテキスト (ConTeXt Headers and Footers を参照)。異なる場所に対して4つまで繰り返し指定可能 text to be placed in running header or footer (see ConTeXt Headers and Footers); repeat up to four times for different placement

indenting

controls indentation of paragraphs, e.g. yes,small,next (see ConTeXt Indentation); repeat for multiple options

interlinespace

adjusts line spacing, e.g. 4ex (using ```setupinterlinespace```_); repeat for multiple options

layout

ページのマージンとテキスト配置のためのオプション (ConTeXt Layout を参照) 複数回指定可能

linkcolor, contrastcolor

color for links outside and inside a page, e.g. red, blue (see ConTeXt Color)

linkstyle

typeface style for links, e.g. normal, bold, slanted, boldslanted, type, cap, small

lof, lot [boolean]

図目次および表目次を挿入します。

mainfont, sansfont, monofont, mathfont

フォントファミリー: 任意のシステムフォントのフォント名 (ConTeXt Font Switching を参照)

margin-left, margin-right, margin-top, margin-bottom

layout が設定されていない場合にマージンを設定 (layout はこれらを上書きします)

pagenumbering

ページ番号のスタイルと場所 (```setuppagenumbering```_ を利用) 複数回指定可能

papersize

paper size, e.g. letter, A4, landscape (see ConTeXt Paper Setup); repeat for multiple options

pdfa

adds to the preamble the setup necessary to generate PDF/A of the type specified, e.g. 1a:2005, 2a. If no type is specified (i.e. the value is set to True, by e.g. --metadata=pdfa or pdfa: true in a YAML metadata block), 1b:2005 will be used as default, for reasons of backwards compatibility. Using --variable=pdfa without specified value is not supported. To successfully generate PDF/A the required ICC color profiles have to be available and the content and all included files (such as images) have to be standard conforming. The ICC profiles and output intent may be specified using the variables pdfaiccprofile and pdfaintent. See also ConTeXt PDFA for more details.

pdfaiccprofile

when used in conjunction with pdfa, specifies the ICC profile to use in the PDF, e.g. default.cmyk. If left unspecified, sRGB.icc is used as default. May be repeated to include multiple profiles. Note that the profiles have to be available on the system. They can be obtained from ConTeXt ICC Profiles.

pdfaintent

when used in conjunction with pdfa, specifies the output intent for the colors, e.g. ISO coated v2 300\letterpercent\space (ECI) If left unspecified, sRGB IEC61966-2.1 is used as default.

toc [boolean]

目次を挿入します。(--toc/--table-of-contents でも設定可能)

whitespace

spacing between paragraphs, e.g. none, small (using ```setupwhitespace```_)

includesource

include all source documents as file attachments in the PDF file

wkhtmltopdf 用の変数

Pandocは `wkhtmltopdf```_ を用いた `creating a PDF`_ の際に、下記の変数を利用します。 ``--css オプションも同様に出力へ影響します。

footer-html と header-html

ヘッダとフッタに情報を付け加える

margin-left, margin-right, margin-top, margin-bottom

用紙の余白を設定する

papersize

用紙のサイズを設定する

manページ用の変数

adjusting

テキストを左揃え(l)、右揃え(r)、中央揃え(c)、もしくは両端揃え(b)にする

footer

manページにおけるフッタ

header

manページにおけるヘッダ

hyphenate

true の場合(デフォルト)、ハイフネーションによる分綴を行う

section

manページにおけるセクション数

roff ms用の変数

fontfamily

フォントファミリー (例: T や P など)

indent [boolean]

パラグラフのインデント (例: 2m)

lineheight

行の高さ (例: 12p)

pointsize

文字サイズ (例: 10p)

Variables set automatically

Pandocは、options もしくは文書の内容に応じて、以下の変数を自動的に設定します。ユーザはそれらの変数を変更することもできます。自動的に設定される変数には以下の変数が含まれ、出力形式によって使われる変数は異なります:

body

文書の本文(body)

date-meta

date 変数は、HTMLベースのフォーマット (dzslides, epub, html, html4, html5, revealjs, s5, slideous, slidy) において、ISO 8601形式である YYYY-MM-DD に変換されます。 date 変数として、次の形式が認識されます: mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601形式), dd MM yyyy (例: 02 Apr 2018 もしくは 02 April 2018 ), MM dd, yyyy (例: Apr. 02, 2018 もしくは April 02, 2018), \ yyyy[mm[dd]]\ `` (例: ``\ 20180402, 201804 もしくは 2018 )

header-includes

contents specified by -H/--include-in-header (may have multiple values)

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)

meta-json

文書中の全てのメタデータのJSON表現。フィールドの値は、選択した出力形式に変換されます。

numbersections

-N/--number-sections が指定されていた場合、非ヌルの値

sourcefile, outputfile

コマンドラインから与えられる入力および出力ファイル名。 sourcefile は複数ファイルの場合に配列となり、標準入力の場合に空になります。ユーザがテンプレート内でこれらを区別するために、次のスニペットを利用できます：

$if(sourcefile)$
$for(sourcefile)$
$sourcefile$
$endfor$
$else$
(stdin)
$endif$

同様に outputfile は標準出力の場合に - となります。

If you need absolute paths, use e.g. $curdir$/$sourcefile$.

curdir

working directory from which pandoc is run.

toc [boolean]

--toc/--table-of-contents が指定されていた場合、非ヌルの値

toc-title

title of table of contents (works only with EPUB, HTML, revealjs, opendocument, odt, docx, pptx, beamer, LaTeX)

拡張

ReaderとWriterの動作の一部は、さまざまな拡張を有効もしくは無効にすることで調整できます。

拡張機能を有効にするには、ファイル形式に +EXTENSION を追加し、無効にするときは 、 -EXTENSION を追加します。たとえば、 --from markdown_strict+footnotes は、オリジナルのMarkdown (markdown_strict) 形式にfootnotes拡張を有効にしたものを意味し、 --from markdown-footnotes-pipe_tables は、Pandoc Markdown形式から、footnotes拡張とpipe_tables拡張を無効にしたものを意味しています。

Markdown ReaderおよびWriterは、拡張を最も使用しています。そのような拡張は、下記の Pandoc’s Markdown セクションで網羅されます (commonmark と gfm については Markdown variants も参照) 。次に説明する拡張は、他の形式でも利用できるものを含みます。

注意： ipynb 形式に対するMarkdown拡張は、Jupyter notebooksのMarkdownセルに対して影響を与えます (--atx-headers のようなコマンドラインオプションも同様)。

タイポグラフィ

直線形の引用符( '...' や "..." )を曲線形の引用符 (‘...’ や “...”)に、 --- を emダッシュ (—)に、-- を enダッシュ (–)に、そして ... を三点リーダー (…)に変換します。また、“Mr.” などの省略語の直後にノーブレークスペースを挿入します。

この拡張は、下記の形式について有効/無効を切り替えることができます。

入力フォーマット

markdown, commonmark, latex, mediawiki, org, rst, twiki, html

出力フォーマット

markdown, latex, context, rst

デフォルトで有効になっているフォーマット

markdown, latex, context (入出力の両方で有効)

注意: Markdownを入力フォーマットにする場合、 smart 拡張は、これとは逆の効果をもたらします。たとえば曲線形の引用符が直線形に変換されます。

LaTeXにおいて smart はTeXにおける標準的な合字の使用を意味します。つまりクォーテーションマーク (ダブルクォートの `` と '' 、シングルクォートの ` と ') およびダッシュ (enダッシュ -- と emダッシュ ---) を利用します。 smart が無効の場合は、PandocはLaTeX入力において文字通りに解釈します。LaTeX出力において smart を有効にした場合は、Pandocは可能な限りTeXの合字を利用します。 smart が無効の場合はUnicodeのクォーテーション文字およびダッシュ文字を利用します。

見出しと章

識別子が明示的に指定されていない見出しには、自動的に見出しのテキストに基づいたユニークな識別子が割り当てられます。

この拡張は、下記の形式について有効/無効を切り替えることができます。

入力フォーマット

markdown, latex, rst, mediawiki, textile

出力フォーマット

markdown, muse

デフォルトで有効になっているフォーマット

markdown, muse

見出しのテキストから識別子を作成する際に用いられるデフォルトのアルゴリズムは次のとおりです:

  • すべての修飾やリンクなどを削除する

  • すべての脚注を削除する

  • アンダーバー、ハイフン、ピリオドを除く「英数字ではない文字」を削除する

  • すべての空白と改行をハイフンで置換する

  • すべてのアルファベットを小文字に変換する

  • テキストのはじまりが英字になるまで文頭の数字や句読点を除く(識別子は数字や句読点で始まることができないため)

  • 何も残らなかった場合は、 section を識別子として用いる

このアルゴリズムに従うと、例えば以下のような見出しと識別子の対応が得られます:

見出し

識別子

Heading identifiers in HTML

heading-identifiers-in-html

Maître d'hôtel

maître-dhôtel

*Dogs*?--in *my* house?

dogs--in-my-house

[HTML], [S5], or [RTF]?

html-s5-or-rtf

3. Applications

applications

33

section

ほとんどの場合、上述したアルゴリズムによって見出しのテキストから識別子を決定できます。例外は、同一のテキストが複数の見出しに使われている場合です。この場合、一番はじめの見出しが、上記のアルゴリズムによって決められた識別子を取得します。2つめの見出しは、 -1 が末尾に追加された同じ識別子を取得します。このようにして、3つめ以降の見出しも -2, -3 ...が追加された識別子が与えられます。

（ただし、 gfm_auto_identifiers を有効にした場合、異なるアルゴリズムが使われます。下記を参照してください）

これらの識別子は、 --toc|--table-of-contents オプションを有効にしたときに作成される目次のリンクに用いられます。異なる文書中のセクションへのリンクを作成するときにも便利です。たとえば、このセクションへのリンクは次のようになります:

See the section on
[heading identifiers](#heading-identifiers-in-html-latex-and-context).

ただし、セクションへのリンクを張るこの方法は、HTML、LaTeX、およびConTeXt形式でのみ機能することに注意してください。

--section-divs オプションが指定された場合、それぞれのセクションは section (html4 形式の場合は div) で囲まれます。その見出しの識別子は、見出しそのものではなく外側の <section> (または <div>) タグに付与されます。これによりすべてのセクションをJavaScriptで操作したり、CSSで個別に取り扱えたりできます。

auto_identifiers によって生成される識別子を、純粋なASCII文字にします。すなわち、アクセント付きラテン文字からアクセントを取り除き、また、非ラテン文字も取り除かれます。

Changes the algorithm used by auto_identifiers to conform to GitHub’s method. Spaces are converted to dashes (-), uppercase characters to lowercase characters, and punctuation characters other than - and _ are removed. Emojis are replaced by their names.

数式の入力

```tex_math_dollars```_ 、 ```tex_math_single_backslash```_ 、 そして ```tex_math_double_backslash```_ 拡張はPandoc’s Markdownのセクションに書かれています。

しかし、これらはHTML入力とともに使用することができます。これは例えばMathJaxを使って整えられたウェブページを読むのに便利です。

生の HTML/TeX

The following extensions are described in more detail in their respective sections of Pandoc’s Markdown:

  • ```raw_html```_ allows HTML elements which are not representable in pandoc’s AST to be parsed as raw HTML. By default, this is disabled for HTML input.

  • `raw_tex```_ allows raw LaTeX, TeX, and ConTeXt to be included in a document. This extension can be enabled/disabled for the following formats (in addition to ``markdown):

    入力フォーマット

    latex, textile, html (environments, \ref, and \eqref only), ipynb

    出力フォーマット

    textile, commonmark

    注意： ipynb, raw_html および raw_tex 形式の適用は、Markdownセル内の生のTeXだけでなく、出力セルの text/html mime type データにも影響を与えます。 ipynb Readerはいくつかのオプションが与えられたときに、できるだけリッチな出力を保持しようとします。そのため docx のように生の html や tex を利用できない形式へ変換しようとする際には、よい出力結果を得るために raw_html と raw_tex を無効にするとよいでしょう。

  • `native_divs```_ causes HTML ``div elements to be parsed as native pandoc Div blocks. If you want them to be parsed as raw HTML, use -f html-native_divs+raw_html.

  • `native_spans```_ causes HTML ``span elements to be parsed as native pandoc Span inlines. If you want them to be parsed as raw HTML, use -f html-native_spans+raw_html. If you want to drop all divs and spans when converting HTML to Markdown, you can use pandoc -f html-native_divs-native_spans -t markdown.

Literate Haskellのサポート

文書をLiterate Haskellソースコードとして扱います。

この拡張は、下記の形式について有効/無効を切り替えることができます。

入力フォーマット

markdown, rst, latex

出力フォーマット

markdown, rst, latex, html

上記の形式に対して +lhs (または +literate_haskell) を追加した場合、Pandocは文書をLiterate Haskellソースコードと認識します。つまり次のようになります：

  • Markdown入力において > 記号から始まる部分は、ブロック引用ではなくHaskellコードとして解釈します。 \begin{code} と \end{code} で挟まれた部分も同様です。ATX形式の見出しに関しては、かわりに ‘=’ が利用されます。

  • Markdown出力において haskell および literate クラスが付いているコードブロックは > 記号から始まる形で出力されます。ブロック引用は1つの空白でインデントされるためHaskellソースコードとして認識されない形となります。さらに見出しはATX形式 (# が付く) ではなくsetext形式 (下線が付く) として出力されます。(GHCは # 文字を行番号の1文字目として利用するため)

  • reStructuredText入力では > 記号から始まる部分はHaskellコードとして解釈されます。

  • reStructuredText出力では haskell クラス付きコードブロックは > 記号を使って出力されます。

  • LaTeX入力では code 環境内のテキストがHaskellコードとして解釈されます。

  • LaTeX出力では haskell クラス付きのコードブロックが code 環境の中に出力されます。

  • HTML出力では haskell クラス付きのコードブロックが > 記号とともに literatehaskell クラスとして出力されます。

例:

pandoc -f markdown+lhs -t html

はMarkdown規約に基づいたLiterate Haskellソースコードを入力し、通常のHTML (> 記号がない形) に出力します。

pandoc -f markdown+lhs -t html+lhs

は > 記号付きのHaskellコードを含むHTMLを出力するため、Literate Haskellソースコードとしてコピー＆ペースト可能です。

注意：GHCは > 記号が1文字目にあることを期待します。したがってインデントされたLiterateコードブロック (例：箇条書きの環境内)はHaskellコンパイラに認識されません。

その他の拡張

空の段落を許します。デフォルトでは、空の段落は省略されます。

この拡張は、下記の形式について有効/無効を切り替えることができます。

入力フォーマット

docx, html

出力フォーマット

docx, odt, opendocument, html

Enables native numbering of figures and tables. Enumeration starts at 1.

この拡張は、下記の形式について有効/無効を切り替えることができます。

出力フォーマット

odt, opendocument, docx

Links to headings, figures and tables inside the document are substituted with cross-references that will use the name or caption of the referenced item. The original link text is replaced once the generated document is refreshed. This extension can be combined with xrefs_number in which case numbers will appear before the name.

Text in cross-references is only made consistent with the referenced item once the document has been refreshed.

この拡張は、下記の形式について有効/無効を切り替えることができます。

出力フォーマット

odt, opendocument

Links to headings, figures and tables inside the document are substituted with cross-references that will use the number of the referenced item. The original link text is discarded. This extension can be combined with xrefs_name in which case the name or caption numbers will appear after the number.

For the xrefs_number to be useful heading numbers must be enabled in the generated document, also table and figure captions must be enabled using for example the native_numbering extension.

Numbers in cross-references are only visible in the final document once it has been refreshed.

この拡張は、下記の形式について有効/無効を切り替えることができます。

出力フォーマット

odt, opendocument

docx形式から変換する場合、Pandocは、docxファイル中のスタイルの意味に関係なく、すべてのdocxのスタイルをdivスタイル (docxファイル中で段落スタイルだった場合) もしくはspanスタイル (docxファイル中で文字列スタイルだった場合) として読み取ります。これは、 docx custom styles と同時に使用できます。デフォルトでは無効になっています。

入力フォーマット

docx

muse 入力形式においてEmacs MuseマークアップのText::Amuse拡張を有効にします。

In the ipynb input format, this causes Markdown cells to be included as raw Markdown blocks (allowing lossless round-tripping) rather than being parsed. Use this only when you are targeting ipynb or a markdown-based output format.

When the citations extension is enabled in org, org-cite and org-ref style citations will be parsed as native pandoc citations.

When citations is enabled in docx, citations inserted by Zotero or Mendeley or EndNote plugins will be parsed as native pandoc citations. (Otherwise, the formatted citations generated by the bibliographic software will be parsed as regular text.)

Some aspects of Pandoc’s Markdown fancy lists are also accepted in org input, mimicking the option org-list-allow-alphabetical in Emacs. As in Org Mode, enabling this extension allows lowercase and uppercase alphabetical markers for ordered lists to be parsed in addition to arabic ones. Note that for Org, this does not include roman numerals or the # placeholder that are enabled by the extension in Pandoc’s Markdown.

In the jats output formats, this causes reference items to be replaced with <element-citation> elements. These elements are not influenced by CSL styles, but all information on the item is included in tags.

context 出力形式において、既定の Extreme Tables (xtables) ではなく`Natural Tables (TABLE)`_ を利用します。Natural Tables はよりきめ細かいグローバルカスタマイズを実現しますが、Extreme Tablesに比べるとパフォーマンスに難があります。

Pandoc’s Markdown

Pandoc understands an extended and slightly revised version of John Gruber’s Markdown syntax. This document explains the syntax, noting differences from original Markdown. Except where noted, these differences can be suppressed by using the markdown_strict format instead of markdown. Extensions can be enabled or disabled to specify the behavior more granularly. They are described in the following. See also Extensions above, for extensions that work also on other formats.

哲学

Markdownは、書きやすく設計されているだけでなく、より重要なこととして、Markdownで書かれた文書をそのまま容易に読めるようにも設計されています:

Markdown形式の文書は、タグなどでマークアップされているように見えることなく、プレーンテキストとしてそのまま見せても通用するように書かれるべきである。 – John Gruber

この原則は、Pandocにおいて、表や脚注、その他の拡張機能についての文法を設計する上での指針となっています。

しかしながら、ある1点において、Pandocの目指すものとオリジナルのMarkdownが目指すものは異なります。Markdownは、もともとHTMLを生成するために設計されたのに対し、Pandocは、様々なフォーマットへと出力することを目的として設計されています。この目的から、Pandocでは、文書中に埋め込まれた生のHTMLを解釈することはできますが、それを推奨せず、その代わりにHTMLらしくない方法で、定義リスト、表、数式、脚注などの文章に重要な構成要素を表現します。

段落

段落は、1行以上のテキストと、それに続く1行以上の空行からなります。単なる改行は、スペースとして扱われます。これにより、ユーザの好きなように改行を行って段落を構成することが可能です。もしも強制改行(ソフトリターン)が必要な場合は、行末に2つ以上のスペースを置いてください。

改行の後にバックスラッシュを置いた場合も、強制改行として処理されます。注意: マルチラインテーブルおよびグリッドテーブルのセルでは、行末のスペースが無視されるため、これが唯一の強制改行を行う方法です。

見出し

Pandocでは、Setext形式とATX形式の2つの見出し記法を用いることができます。

Setext形式の見出し

Setex形式では、"下線が引かれた"行が見出しとなります。 = 記号で下線を引くとレベル1の見出しに、 - 記号で下線を引くとレベル2の見出しになります:

A level-one heading
===================

A level-two heading
-------------------

見出しとなるテキストは、強調や斜体などのインライン修飾が可能です (詳細は下記の Inline formatting を参照)。

ATX形式の見出し

ATX形式の見出しは、1から6個の連続した # 記号と、それに続く1行のテキストから成ります。ATX形式の見出しでは、行末に任意の数の # 記号があっても構いません。行頭に置かれた # 記号の数が、見出しのレベルを決めます:

## A level-two heading

### A level-three heading ###

Setext形式の見出しと同様に、ATX形式の見出しもインライン修飾が可能です:

# A level-one heading with a [link](/url) and *emphasis*
拡張: blank_before_header

Original Markdown syntax does not require a blank line before a heading. Pandoc does require this (except, of course, at the beginning of the document). The reason for the requirement is that it is all too easy for a # to end up at the beginning of a line by accident (perhaps through line wrapping). Consider, for example:

I like several of their flavors of ice cream:
#22, for example, and #5.
拡張: space_in_atx_header

多くのMarkdown方言では、ATX形式の見出しにおいて、 # 記号と見出しとなるテキストの間にスペースがなくても、見出しとして処理されます。しかしこれでは、 #5 bolt や #hashtag といった行も見出しとして処理されてしまいます。この拡張によって、Pandocは、 # 記号と見出しとなるテキストの間にスペースがある行を見出しとして処理します。

見出しの識別子

上述した `auto_identifiers extension`_ も参照してください。

拡張: header_attributes

見出しのテキストを含む行の行末にこの文法を用いることで、見出しに属性をつけることができます。

{#identifier .class .class key=value key=value}

例えば、以下の見出しは foo 識別子が与えられます:

# My heading {#foo}

## My heading ##    {#foo}

My other heading   {#foo}
---------------

(この文法は PHP Markdown Extra と互換性があります。)

Note that although this syntax allows assignment of classes and key/value attributes, writers generally don’t use all of this information. Identifiers, classes, and key/value attributes are used in HTML and HTML-based formats such as EPUB and slidy. Identifiers are used for labels and link anchors in the LaTeX, ConTeXt, Textile, Jira markup, and AsciiDoc writers.

unnumbered クラスが付いた見出しには、たとえ --number-sections オプションが指定されていても、見出し番号が付きません。単一のハイフン ( - )が属性として用いられている場合は、 .unnumbered と等価です (非英語圏の文書には、単一のハイフンによる識別子が適しています。)。よって、

# My heading {-}

は、以下と等価です

# My heading {.unnumbered}

If the unlisted class is present in addition to unnumbered, the heading will not be included in a table of contents. (Currently this feature is only implemented for certain formats: those based on LaTeX and HTML, PowerPoint, and RTF.)

拡張: implicit_header_references

Pandocは、それぞれの見出しに対して参照リンクが定義されているかのように振る舞います。そのため、以下のような識別子による明示的な見出しへのリンク

# Heading identifiers in HTML

を、

[Heading identifiers in HTML]

や

[Heading identifiers in HTML][]

や

[the section on heading identifiers][heading identifiers in
HTML]

のように、簡略化して書くことができます:

[Heading identifiers in HTML](#heading-identifiers-in-html)

複数の見出しが同一のテキストからなる場合、最初の見出しに対してリンクされます。それ以外の見出しに対してリンクしたい場合は、上述したような明示的なリンクを用いる必要があります。

標準的な参照リンクのように、この参照は大文字・小文字を区別します。

明示的な参照リンクの定義は、常に暗黙的な見出しの参照リンクよりも優先されます。そのため、以下の例では、リンクは #foo ではなく ``bar``を指します:

# Foo

[foo]: bar

See [foo]

引用

Markdownは、Eメールで慣習的に用いられてきた引用の記法を採用しています。引用は、ひとつ以上の段落もしくはブロック要素(リストや見出しなど)からなり、それらの各行は、 > で始まる必要があります。 >``記号の直後には、1つの空白文字を入れてもかまいません。( ``> 記号は、行頭から始まる必要はありませんが、4つ以上の空白文字によってインデントされてはなりません。)

> This is a block quote. This
> paragraph has two lines.
>
> 1. This is a list inside a block quote.
> 2. Second item.

簡略化したやり方(a ""lazy"" form)として、 ``>``を各ブロックの最初の行に置くだけでも引用として処理されます:

> This is a block quote. This
paragraph has two lines.

> 1. This is a list inside a block quote.
2. Second item.

引用の中に、引用を置くことも可能です。つまり、引用はネストすることができます:

> This is a block quote.
>
> > A block quote within a block quote.

> という文字列に続く1つの空白文字は、引用ブロックの開始を示す記号の一部として認識され、引用文のインデントの一部としては換算されません。よって、引用ブロック内にインデントされたコードブロックを置きたい場合は、 > に続けて5つの空白文字を置く必要があります:

>     code

Original Markdown syntax does not require a blank line before a block quote. Pandoc does require this (except, of course, at the beginning of the document). The reason for the requirement is that it is all too easy for a > to end up at the beginning of a line by accident (perhaps through line wrapping). So, unless the markdown_strict format is used, the following does not produce a nested block quote in pandoc:

> This is a block quote.
>> Nested.

文字通りのブロック (コードブロック)

インデントされたコードブロック

4つの空白文字(もしくは1つのタブ文字)によってインデントされた文字列は、そのまま文字通りに処理されます。すなわち、 * や _ などの特別な文字が、斜体や太字などの文字列の修飾には用いられずに、そのまま文字通りに出力されます。また、全ての空白文字や改行も、そのまま保持されます。たとえば、

if (a > 3) {
  moveShip(5 * gravity, DOWN);
}

行頭のインデント(4つの空白文字もしくはタブ文字)は、コードブロックとして扱われず、出力の際に削除されます。

注意: コードブロックにおいて空行を表現するとき、その行は4つのスペースもしくはタブ文字でインデントされている必要はありません。

囲いコードブロック (Fenced code blocks)

拡張: fenced_code_blocks

通常のインデントによるコードブロックに加えて、Pandocでは 囲い (fenced) コードブロックもサポートします。これは始まりの行に3つ以上のチルダ (~) を並べ、同様に終わりの行に、始まりと同じ数のチルダを並べるものです。この2行の間にあるすべてのテキストが、コード行として扱われます。インデントは不要です:

~~~~~~~
if (a > 3) {
  moveShip(5 * gravity, DOWN);
}
~~~~~~~

通常のコードブロックと同様に、囲いコードブロックと周辺のテキストの間には空行が入らなければなりません。

コード自体にチルダやバッククォートを並べたものが入っている場合は、単純に最初と最後のチルダまたはバッククォートをもっと長くしてください。

~~~~~~~~~~~~~~~~
~~~~~~~~~~
code including tildes
~~~~~~~~~~
~~~~~~~~~~~~~~~~
拡張: backtick_code_blocks

fenced_code_blocks と同様ですが、バッククォート (`) をチルダ (~) の代わりに使います。

拡張: fenced_code_attributes

必要に応じて、以下の構文を用いることで囲いコードブロックやバッククォートによるコードブロックに属性を与えることができます:

~~~~ {#mycode .haskell .numberLines startFrom="100"}
qsort []     = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
               qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ここでは、 mycode が識別子で、 haskell および numberLines がクラス、そして startFrom 属性は値 100 の属性です。いくつかの出力形式では、これらの情報を用いてシンタックスハイライトが適用されます。現在のところ、この情報を利用する出力形式は、HTML, LaTeX, Docx, Ms, およびPowerPointだけです。シンタックスハイライトが出力形式および用いた言語でサポートされている場合、上記のコードブロックは行番号付きでシンタックスハイライトが適用されます (どの言語でシンタックスハイライトがサポートされているかを知るためには、 pandoc --list-highlight-languages を実行してください)。シンタックスハイライトがサポートされていない出力形式や言語を用いた場合、以下のように表示されます:

<pre id="mycode" class="haskell numberLines" startFrom="100">
  <code>
  ...
  </code>
</pre>

numberLines (もしくは number-lines )クラスのコードブロックでは、 1 もしくは startFrom 属性の数値から始まる行番号が表示されます。 lineAnchors (もしくは line-anchors ) クラスのコードブロックをHTML出力すると、行がクリック可能なアンカーになります。

コードブロック内の言語を指定するときには、以下のような短縮形も利用できます:

```haskell
qsort [] = []
```

これは、以下と等価です:

``` {.haskell}
qsort [] = []
```

If the fenced_code_attributes extension is disabled, but input contains class attribute(s) for the code block, the first class attribute will be printed after the opening fence as a bare word.

コードブロックのハイライトをさせたくない場合は、 --no-highlight フラグを使用してください。ハイライトのスタイル (カラースキーム)を設定したいときは、 --highlight-style フラグを使用します。詳しくは、下記の Syntax highlighting を参照してください。

ラインブロック

ラインブロックは、縦線 (|) と1つのスペースで始まる一連の行からなります。行の分割や行頭のスペースは保持され、そのまま出力されます。これらの点以外は、Markdown記法に従って修飾されます。ラインブロックは、詩や住所などを書く際に便利な記法です:

| The limerick packs laughs anatomical
| In space that is quite economical.
|    But the good ones I've seen
|    So seldom are clean
| And the clean ones so seldom are comical

| 200 Main St.
| Berkeley, CA 94718

ラインブロック中の行をハードブロックで折り返したい場合は、折り返した行の行頭に1つのスペースを置いてください。

| The Right Honorable Most Venerable and Righteous Samuel L.
  Constable, Jr.
| 200 Main St.
| Berkeley, CA 94718

Inline formatting (such as emphasis) is allowed in the content, but not block-level formatting (such as block quotes or lists).

この文法は、 reStructuredText から借用されています。

リスト

箇条書きリスト

箇条書きリストは、各項目の行頭に点記号が付されたリストのことを指します。箇条書きリストの各項目は、箇条記号( * 、 + 、もしくは - のどれか)が行頭に置かれる必要があります。例を以下に示します:

* one
* two
* three

これは、「コンパクト」なリストを生成します。「ゆるい (loose)」リスト、すなわち各項目が段落として処理されたようなリストが必要ならば、空行を項目の間に入れてください:

* one

* two

* three

箇条記号は、かならずしも左端で揃っている必要はなく、1つから3つのスペースでインデントされていても構いません。ただし、箇条記号の直後には必ずスペースが挿入されていなければいけません。

リストは、(箇条記号を除いた)テキスト部分が先頭のリスト項目と揃っているのが最適な記法です:

* here is my first
  list item.
* and my second.

しかし、下記のような「怠惰な(lazy)」記法も可能です:

* here is my first
list item.
* and my second.

リスト項目として可能なブロック要素

リスト項目には、複数の段落や異なるブロック要素(引用やコードブロックなど)を含めることが可能です。ただし、後続の段落は、空行で区切り、先頭のリスト項目のテキスト開始点に合わせてインデントする必要があります。

* First paragraph.

  Continued.

* Second paragraph. With a code block, which must be indented
  eight spaces:

      { code }

例外: もしもインデントされたコードブロックをリスト項目にする場合、箇条記号に続けて5つの空白(すなわち、箇条記号とそれに続く1つのスペース、そしてインデントを表す4つのスペース)を置いてください。この項目に続けて段落を挿入するときは、コードブロックのテキスト開始点に合わせてインデントするのではなく、コードブロックのインデント開始点に合わせてインデントしてください:

*     code

  continuation paragraph

リストは入れ子にすることが可能です。入れ子となるリストは、空行で区切られている必要はありません。リストを入れ子にするためには、上位のリスト項目のテキスト開始点に合わせてインデントする必要があります。

* fruits
  + apples
    - macintosh
    - red delicious
  + pears
  + peaches
* vegetables
  + broccoli
  + chard

上述したように、Markdownでは「怠惰 (lazily)」なリスト記法が可能であり、必ずしも後続する行がインデントされている必要はありません。しかし、リスト項目に複数の段落を含めたい場合はその限りではなく、リスト項目となる段落はインデントされていなければなりません。

+ A lazy, lazy, list
item.

+ Another one; this looks
bad but is legal.

    Second paragraph of second
list item.

順序付きリスト

順序付きリストは、箇条書きリストと似ていますが、項目の先頭は記号でなく数値が割り振られます。

In original Markdown, enumerators are decimal numbers followed by a period and a space. The numbers themselves are ignored, so there is no difference between this list:

1.  one
2.  two
3.  three

以下の順序付きリストと等価です:

5.  one
7.  two
1.  three
拡張: fancy_lists

Unlike original Markdown, pandoc allows ordered list items to be marked with uppercase and lowercase letters and roman numerals, in addition to Arabic numerals. List markers may be enclosed in parentheses or followed by a single right-parentheses or period. They must be separated from the text that follows by at least one space, and, if the list marker is a capital letter with a period, by at least two spaces. 1

fancy_lists 拡張では、数値の代わりに ‘ # ’ 記号を順序記号として用いることも可能です:

#. one
#. two
拡張: startnum

Pandocは、リスト記号の型および順序の出だしを認識し、可能な限りそれらを保持して出力します。すなわち、下記の例では、閉じ括弧つきの9から始まる順序付きリスト、および小文字のローマ数字を用いた順序付きサブリストが得られます:

 9)  Ninth
10)  Tenth
11)  Eleventh
       i. subone
      ii. subtwo
     iii. subthree

Pandocは、異なる型のリスト記号が用いられるたびに新しいリストを開始します。よって、次の例では3つのリストが作成されます:

(2) Two
(5) Three
1.  Four
*   Five

デフォルトのリスト記号を使用したい場合は、 #. を使ってください:

#.  one
#.  two
#.  three
拡張: task_lists

Pandocは、GitHub-Flavored Markdown文法を用いて、タスクリストをサポートしています。

- [ ] an unchecked task list item
- [x] checked item

定義リスト

拡張: definition_lists

Pandocは、 PHP Markdown Extra 文法といくつかの拡張機能を用いて、定義リストをサポートしています。 2

Term 1

:   Definition 1

Term 2 with *inline markup*

:   Definition 2

        { some code, part of Definition 2 }

    Third paragraph of definition 2.

各用語は、1行に収まっている必要があり、用語の後ろには1つ以上の定義を置く必要があります。用語と定義の間には、1つの空行を置いても構いません。定義は、1つのコロンもしくはチルダ記号ではじめます。行頭に1つもしくは2つのスペースを置いてインデントしても構いません。

A term may have multiple definitions, and each definition may consist of one or more block elements (paragraph, code block, list, etc.), each indented four spaces or one tab stop. The body of the definition (not including the first line) should be indented four spaces. However, as with other Markdown lists, you can “lazily” omit indentation except at the beginning of a paragraph or other block element:

Term 1

:   Definition
with lazy continuation.

    Second paragraph of the definition.

(上述したとおり、)定義の前にスペースを置いた場合、その定義テキストは段落として扱われます。このように定義を段落として扱った場合、いくつかの出力形式では、用語と定義の間に置かれる間隔が通常よりも広く設定されます。よりコンパクトな定義リストを用いたい場合は、定義の直前にスペースを置いてはいけません:

Term 1
  ~ Definition 1

Term 2
  ~ Definition 2a
  ~ Definition 2b

Note that space between items in a definition list is required. (A variant that loosens this requirement, but disallows “lazy” hard wrapping, can be activated with compact_definition_lists: see Non-default extensions, below.)

順序付き用例リスト

拡張: example_lists

特別なリスト記号である @ は、連番の順序付き用例リストに用いられます。文書中にはじめて出てくる @ 記号には ‘1’ が割り振られ、その次の記号には ‘2’ が割り振られ...というように、文書中を通して連番が付されたリストが生成されます。連番が付された用例は、単一のリストにまとめる必要はありません。すなわち、新しい順序付き用例リストのはじめに出てくる``@`` 記号には、一つ前の順序付き用例リストで最後に割り振られた連番の次の番号が割り振られます。例えば:

(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of examples.

(@)  My third example will be numbered (3).

順序付き用例リストは、ラベル付けが可能であり、そのラベルは文書中の任意の場所で参照できます:

(@good)  This is a good example.

As (@good) illustrates, ...

アルファベット、アンダーバー、もしくはハイフンからなる任意の文字列をラベルに使用することができます。

Note: continuation paragraphs in example lists must always be indented four spaces, regardless of the length of the list marker. That is, example lists always behave as if the four_space_rule extension is set. This is because example labels tend to be long, and indenting content to the first non-space character after the label would be awkward.

リストの終わらせ方

リストの後にインデントされたコードブロックを置いた場合、何が起こるでしょうか。

-   item one
-   item two

    { my code block }

おっと! この例では、Pandocは(他のMarkdown実装と同様) { my code block } をコードブロックではなく2番目のリスト項目の第2段落として扱います。

2番目の項目でリストを終えるためには、HTMLコメントなどの出力に反映されない文字列を、インデントせずにリストの後に置いてください:

-   item one
-   item two

<!-- end of list -->

    { my code block }

この方法は、2つのリストを、ひとつながりのリストではなく異なるリストとして扱いたい時にも使えます:

1.  one
2.  two
3.  three

<!-- -->

1.  uno
2.  dos
3.  tres

水平線

3つ以上の *, - もしくは _ 記号を含む行(これらの記号は空白で分けられていても構いません)は、水平線を生成します。

*  *  *  *

---------------

表

4種類の表が使用可能です。最初の3種類の表は、Courierなどの等幅フォントの使用を前提としています。 4番目の表は、列を並べる必要がないため、プロポーショナルフォントでも使用できます。

4種類の表すべてに、オプションとして(以下の例で示すように)キャプションを与えることができます。 Table: (もしくは単に : )で始まる段落がキャプションとして扱われ、行頭の Table: や : は、キャプションを生成する際に削除されます。キャプションは、表の直前もしくは直後に表示されます。

シンプルテーブルは、このように書きます:

  Right     Left     Center     Default
-------     ------ ----------   -------
     12     12        12            12
    123     123       123          123
      1     1          1             1

Table:  Demonstration of simple table syntax.

見出し行も含めたすべてのセルの内容が、それぞれ1行に収まっている必要があります。文字の左右寄せ・中央揃えは、見出し行のテキストが、その直下の - からなる表見出しの下線に対してどこに位置するかで決定されます: 3

  • 表見出しの下線と表見出しのテキストが右側で揃っており、表見出しの下線が左側にはみ出している場合は、列は右寄せとなります。

  • 表見出しの下線と表見出しのテキストが左側で揃っており、表見出しの下線が右側にはみ出している場合は、列は左寄せとなります。

  • 表見出しの下線が、表見出しのテキストの左右両端にはみ出している場合は、列は中央揃えとなります。

  • 表見出しの下線と表見出しのテキストが左右両端で揃っている場合は、デフォルトの方法で列が揃えられます(ほとんどの場合、左寄せになります)。

表は、空行で終わる必要があります。もしくは、表見出しの下線のように、連続した - からなる区切り線の行を直前に置いた空行で終わることもできます。

表見出しのテキストは省略可能ですが、- からなる区切り線を表の最後に付け加える必要があります。たとえば:

-------     ------ ----------   -------
     12     12        12             12
    123     123       123           123
      1     1          1              1
-------     ------ ----------   -------

表見出しのテキストが省略されている場合、左右寄せ・中央揃えの方法は、表の1行目の揃え方によって決まります。そのため、上記の表の列はそれぞれ、右寄せ、左寄せ、中央揃え、右寄せになります。

マルチラインテーブルでは、見出し行も含めたすべてのセルに複数行のテキストを置くことが可能です(ただし、セルの結合はサポートしていません)。例を示します:

-------------------------------------------------------------
 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

Table: Here's the caption. It, too, may span
multiple lines.

マルチラインテーブルは、シンプルテーブルと同じように働きますが、以下の点でシンプルテーブルと異なります:

  • 見出し行の直前に、連続した - からなる区切り線を置く必要がある(ただし、見出し行を省略する場合は除く)。

  • 表の終わりに、連続した - からなる区切り線と、それに続く空行を置く必要がある。

  • それぞれの行を、空行で区切る必要がある。

マルチラインテーブルにおいて、Pandocのパーサは列幅をチェックしており、表を出力する際、Writerは表の各列の相対的な幅をなるべく再現しようとします。出力された表の列幅が狭すぎる場合は、Markdownのソースファイル中で列幅を広げてみてください。

マルチラインテーブルでも、シンプルテーブルと同様、見出し行を省略することが可能です:

----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
----------- ------- --------------- -------------------------

: Here's a multiline table without a header.

マルチラインテーブルでは、必ずしもすべてのセルに複数行のテキストを置く必要はなく、1行だけのテキストを置くことも可能です。ただし、シンプルテーブルとして変換されてしまわないように、セルが1行だけだったとしても空行でそれぞれの行を区切るべき(および、表の最後は区切り線を置くべき)です。

グリッドテーブルは、このように書きます:

: Sample grid table.

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

The row of =s separates the header from the table body, and can be omitted for a headerless table. The cells of grid tables may contain arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). Cells that span multiple columns or rows are not supported. Grid tables can be created easily using Emacs’ table-mode (M-x table-insert).

区切り線の境界にコロンを置くことにで、パイプテーブルと同様に、テキストの左右寄せ・中央揃えを指定できます:

+---------------+---------------+--------------------+
| Right         | Left          | Centered           |
+==============:+:==============+:==================:+
| Bananas       | $1.34         | built-in wrapper   |
+---------------+---------------+--------------------+

見出しのない表の場合は、一番上の行にコロンを置きます:

+--------------:+:--------------+:------------------:+
| Right         | Left          | Centered           |
+---------------+---------------+--------------------+

Pandocは、行や列の結合をサポートしていません。これは、Pandocでは、行数を列ごとに変えたり、列数を行ごとに変えたりすることができないということです。グリッドテーブルでは、各行の列数および各列の行数がそれぞれ同じである必要があります。たとえば、Docutilsの sample grid tables は、Pandocでは思ったとおりにレンダリングされません。

パイプテーブルは、このように書きます:

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of pipe table syntax.

パイプテーブルは、 PHP Markdown Extra tables と同じ文法です。表の左端と右端に置くパイプ文字の列はオプションである一方で、列の間には必ずパイプ文字を置く必要があります。コロンは、上で示したように、文字列の左右寄せ・中央揃えを指定します。パイプテーブルでは、見出し行は省略できません。見出し行のないテーブルをシミュレートするには、見出しとして空白のセルを置いてください。

パイプ文字は列の境界を示すため、上の例のようにパイプテーブルの列を縦に揃える必要はありません。よって、以下は文法的に完全に正しい(しかし見栄えが悪い(ugly))パイプテーブルの記述です:

fruit| price
-----|-----:
apple|2.05
pear|1.37
orange|3.09

The cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. If any line of the markdown source is longer than the column width (see --columns), then the table will take up the full text width and the cell contents will wrap, with the relative cell widths determined by the number of dashes in the line separating the table header from the table body. (For example ---|- would make the first column 3/4 and the second column 1/4 of the full text width.) On the other hand, if no lines are wider than column width, then cell contents will not be wrapped, and the cells will be sized to their contents.

注意: Pandocは、以下に示したようなEmacs orgtbl-modeによって作成される形式の表もパイプテーブルとして認識します:

| One | Two   |
|-----+-------|
| my  | table |
| is  | nice  |

違いは、 | の代わりに + が使用される点です。この他のorgtbl機能はサポートされていません。特別な点として、デフォルトでない文字列の左右寄せ・中央揃えを設定するためには、上記のようにコロンを区切り線に追加する必要があります。

メタデータブロック

ファイルがタイトルブロックから開始している場合、

% title
% author(s) (separated by semicolons)
% date

タイトルブロックは、通常のテキストではなく書誌情報として解析されます (たとえば、スタンドアロンのLaTeXもしくはHTML出力のタイトルとして使用されます)。タイトルブロックには、タイトルのみ、タイトルと著者、もしくは3つの要素すべて(タイトルと著者と日付)を含めることが可能です。著者を含めるがタイトルを含めない場合や、タイトルと日付を含めるが著者を含めない場合には、該当の行を空白にします:

%
% Author

% My title
%
% June 15, 2006

複数行からなるタイトルを設定することもできますが、その場合、2行目以降の行頭はスペースで始める必要があります:

% My title
  on multiple lines

著者名を複数設定したいる場合、行頭にスペースを加えた上で著者名を複数行に分けるか、セミコロンで区切るか、もしくはその両方にすることが可能です。よって、以下はすべて同等に処理されます:

% Author One
  Author Two

% Author One; Author Two

% Author One;
  Author Two

日付は、1行で記載する必要があります。

3つのメタデータフィールドは、どれもインライン修飾が可能です(イタリック、リンク、脚注など)。

タイトルブロックは常に処理されますが、 -standalone (-s) オプションが選択された場合に限り、出力に影響を与えます。HTML出力では、タイトルは2箇所に表示されます。ひとつは、 <head> タグ内部で、これはブラウザのウィンドウ上部に表示されます。もうひとつは、 <body> タグの直後で、これは出力したHTMLをブラウザで表示した時、ページの先頭に表示されます。 <head> タグ内部のタイトルには、オプションで接頭辞を付けることが可能です (`` --title-prefix`` もしくは -T オプション)。 <body> タグ内部のタイトルは、 class="title" のH1要素として表示されるため、CSSを用いて削除したり書式を変更したりすることが可能です。タイトルの接頭辞が -T オプションで指定されているがタイトルブロックが文書中に存在しない場合、タイトル接頭辞そのものがHTMLのタイトルとして使用されます。

manのWriterは、タイトル行からmanページタイトル、セクション番号、ヘッダおよびフッタ情報を取得します。タイトル行の最初の単語が、manページタイトルとして解釈されます。オプションとして、manページにセクション番号を与える場合は、括弧で囲んだ(1桁の)数字を語末に置いてください(セクション番号とタイトルとなる単語の間にスペースを置いてはいけません)。これらの後に置かれる全てのテキストは、フッタもしくはヘッダとして解釈されます。パイプ記号 (|) は、フッタテキストとヘッダテキストを区切る記号として働きます。そのため、

% PANDOC(1)

は、 PANDOC をタイトルとするセクション番号1のmanページをもたらします。

% PANDOC(1) Pandoc User Manuals

は、上記に加えて、"Pandoc User Manuals"がフッタになります。

% PANDOC(1) Pandoc User Manuals | Version 4.0

は、さらに上記に加えて、"Version 4.0"がヘッダになります。

A YAML metadata block is a valid YAML object, delimited by a line of three hyphens (---) at the top and a line of three hyphens (---) or three dots (...) at the bottom. A YAML metadata block may occur anywhere in the document, but if it is not at the beginning, it must be preceded by a blank line. (Note that, because of the way pandoc concatenates input files when several are provided, you may also keep the metadata in a separate YAML file and pass it to pandoc as an argument, along with your Markdown files:

pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html

この時、YAMLファイルが --- ではじまり、 --- もしくは ... で終わることを確認してください。) あるいは、 metadata-file オプションを使用してYAMLファイルを指定することも可能です。ただし、この方法を用いた場合、入力するMarkdown文書中のコンテンツ (脚注など) を参照することができなくなります。

メタデータは、YAMLオブジェクトのフィールドから取得され、文書中の既存のメタデータに追加されます。メタデータには、リストやオブジェクトを含めることができます (適宜、入れ子にもできます)。また、全ての文字列スカラ値は、Markdownとして解釈されます。フィールド名がアンダースコアで終わっている場合は、Pandocはその名前付きフィールドを無視します (これらは、外部の処理系によって与えられることがあります)。フィールド名は、YAMLの数値や真偽値として解釈されないように命名する必要があります (そのため、たとえば yes, True や 15 は、フィールド名として使用できません) 。

A document may contain multiple metadata blocks. If two metadata blocks attempt to set the same field, the value from the second block will be taken.

Each metadata block is handled internally as an independent YAML document. This means, for example, that any YAML anchors defined in a block cannot be referenced in another block.

Pandocを -t markdown オプションとともに用いてMarkdown文書を作成するとき、 -s/--standalone オプションも指定されている場合にのみ、YAMLメタデータブロックが生成されます。すべてのメタデータはまとめられ、単一のメタデータブロックとして文書の先頭に置かれます。

Note that YAML escaping rules must be followed. Thus, for example, if a title contains a colon, it must be quoted, and if it contains a backslash escape, then it must be ensured that it is not treated as a YAML escape sequence. The pipe character (|) can be used to begin an indented block that will be interpreted literally, without need for escaping. This form is necessary when the field contains blank lines or block-level formatting:

---
title:  'This is the title: it contains a colon'
author:
- Author One
- Author Two
keywords: [nothing, nothingness]
abstract: |
  This is the abstract.

  It consists of two paragraphs.
...

The literal block after the | must be indented relative to the line containing the |. If it is not, the YAML will be invalid and pandoc will not interpret it as metadata. For an overview of the complex rules governing YAML, see the Wikipedia entry on YAML syntax.

テンプレート変数は、メタデータから自動的に設定されます。そのため、たとえばHTMLを出力する場合、HTMLの abstract 変数に、Markdown中の abstract フィールドの内容が設定されます。

<p>This is the abstract.</p>
<p>It consists of two paragraphs.</p>

変数には任意のYAML構造を含めることができますが、テンプレート変数の構造は、与えたYAML構造と一致している必要があります。 author テンプレート変数には、デフォルトでは単純な配列もしくは文字列が入ることが想定されていますが、より複雑な構造にすることも可能です。たとえば、"affiliation" メタデータが与えられた場合は、"author" メタデータに "affiliation"メタデータを加えます:

---
title: The document title
author:
- name: Author One
  affiliation: University of Somewhere
- name: Author Two
  affiliation: University of Nowhere
...

上記の例のように、構造化された著者メタデータを利用する場合、カスタムテンプレートが必要になります:

$for(author)$
$if(author.name)$
$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
$else$
$author$
$endif$
$endfor$

文書のヘッダに生 (raw) のコンテンツを含める場合は、 header-includes を使用してください。ただし、 `raw_attribute 拡張`_を使用した上で、特定の出力形式でのコードブロックとしてマークアップすることが重要です。これを行わない場合、生のコンテンツがMarkdownとして解釈されます:

header-includes:
- |
  ```{=latex}
  \let\oldsection\section
  \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
  ```

Note: the yaml_metadata_block extension works with commonmark as well as markdown (and it is enabled by default in gfm and commonmark_x). However, in these formats the following restrictions apply:

  • The YAML metadata block must occur at the beginning of the document (and there can be only one). If multiple files are given as arguments to pandoc, only the first can be a YAML metadata block.

  • The leaf nodes of the YAML structure are parsed in isolation from each other and from the rest of the document. So, for example, you can’t use a reference link in these contexts if the link definition is somewhere else in the document.

バックスラッシュを用いたエスケープ

コードブロックとインラインコードの内部を除き、バックスラッシュの次に続くあらゆる文字および空白文字は、そのまま文字通り扱われます。これは、通常は修飾に使われる記号に対しても同様です。例えば、

*\*hello\**

は以下のHTMLに変換され、以下のHTML

<em>*hello*</em>

には変換されません。

<strong>hello</strong>

This rule is easier to remember than original Markdown’s rule, which allows only the following characters to be backslash-escaped:

\`*_{}[]()>#+-.!

(However, if the markdown_strict format is used, the original Markdown rule will be used.)

A backslash-escaped space is parsed as a nonbreaking space. In TeX output, it will appear as ~. In HTML and XML output, it will appear as a literal unicode nonbreaking space character (note that it will thus actually look “invisible” in the generated HTML source; you can still use the --ascii command-line option to make it appear as an explicit entity).

バックスラッシュによってエスケープされた改行文字 (すなわち、行末のバックスラッシュ) は、ソフトリターン (hard line break) として変換されます。これは、Texでは \\ 、HTMLでは <br /> として出力されます。この方法は、Markdownにおいてソフトリターンするために、2つの空白文字を行末に入力する方法と比べて、より明示的です。

バックスラッシュによるエスケープは、コードブロックやインラインコードなど、そのまま文字通りに解釈されるようなコンテキストでは用いることができません。

インライン修飾

強調

テキストを 斜体 にするためには、そのテキストを * もしくは _ で囲みます:

This text is _emphasized with underscores_, and this
is *emphasized with asterisks*.

2つの * もしくは _ で囲むと、 太字 で強調されます:

This is **strong emphasis** and __with underscores__.

空白文字で囲まれた * や _ 、および、バックスラッシュによってエスケープされた * や _ は、テキストを修飾しません。

This is * not emphasized *, and \*neither is this\*.
拡張: intraword_underscores

_ 記号は、単語や識別子に含まれることがあるため、Pandocは、 _ によって囲まれた英数字を修飾しません。テキストを修飾したい場合は、 * を使用してください:

feas*ible*, not feas*able*.

取り消し線

拡張: strikeout

テキストを ~~ で囲むことで、そのテキストに取り消し線をかけることができます。たとえば、

This ~~is deleted text.~~

上付き文字と下付き文字

拡張: superscript , subscript

^ で囲まれた文字列は、上付き文字に変換されます。また、 ~ で囲まれた文字列は、下付き文字に変換されます。たとえば、

H~2~O is a liquid.  2^10^ is 1024.

The text between ^...^ or ~...~ may not contain spaces or newlines. If the superscripted or subscripted text contains spaces, these spaces must be escaped with backslashes. (This is to prevent accidental superscripting and subscripting through the ordinary use of ~ and ^, and also bad interactions with footnotes.) Thus, if you want the letter P with ‘a cat’ in subscripts, use P~a\ cat~, not P~a cat~.

そのまま文字通りの出力 (Verbatim)

短いテキストを、そのまま文字通り出力したい場合は、バッククォートで囲みます:

What is the difference between `>>=` and `>>`?

もしも、バッククォートも含めた文字列をそのまま文字通り出力したい場合は、2重のバッククォートで囲みます:

Here is a literal backtick `` ` ``.

(開きのバッククォート(左側のバッククォート)の直後の空白文字、および閉じのバッククォート(右側のバッククォート)の直前の空白文字は無視されます。)

一般則として、連続したバッククォートの組で囲まれた文字列は、そのまま文字通り出力されます(開きと閉じのバッククォートの直前・直後にあるスペースは無視されます)。このとき、開きのバッククォートと閉じのバッククォートの数は同じである必要があります。

バックスラッシュによるエスケープ (および、その他のMarkdown修飾記法) は、そのまま文字通りの出力を行っているときには有効になりません:

This is a backslash followed by an asterisk: `\*`.
拡張: inline_code_attributes

そのまま文字通りの出力するテキストに対して、 fenced code blocks と同様に、属性を与えることができます:

`<$>`{.haskell}

Underline

To underline text, use the underline class:

[Underline]{.underline}

Or, without the bracketed_spans extension (but with native_spans):

<span class="underline">Underline</span>

This will work in all output formats that support underline.

スモールキャピタル

スモールキャピタルを適用したい場合は、 smallcaps クラスを使用してください:

[Small caps]{.smallcaps}

もしくは、 bracketed_spans 拡張機能をオフにして以下のように記述することも可能です:

<span class="smallcaps">Small caps</span>

その他のMarkdown方言との互換性のため、CSSの使用も可能です:

<span style="font-variant:small-caps;">Small caps</span>

この方法は、スモールキャピタルを利用可能なすべての出力形式で使用可能です。

数式

2つの $ 記号で囲まれた文字列は、TeX数式として扱われます。TeX数式として扱いたいとき、開きの $ (つまり左側の $ ) 記号の直後には、非空白文字が続く必要があります。逆に言えば、 $ 記号のすぐ後に空白文字が来た場合は、TeX数式として扱われません。同様に、閉じの $ (つまり右側の $ ) 記号は、直前に非空白文字が続いている必要があります。また、 $ 記号の直後に数字が続く場合は、閉じの $ として扱われません。これにより、 $20,000 や $30,000 は数式として扱われません。もし何らかの理由で文章の末尾に $ 記号を入れなければならないときは、バックスラッシュによってエスケープしてください。これにより、その $ 記号は、TeX数式の区切り文字として扱われなくなります。

For display math, use $$ delimiters. (In this case, the delimiters may be separated from the formula by whitespace. However, there can be no blank lines between the opening and closing $$ delimiters.)

TeX 数式はすべての出力形式で出力されます。どのようにレンダリングされるかは出力形式に依存します：

LaTeX

\( ... \) 中のテキスト(インライン数式の場合)、もしくは \[ ... \] 中のテキスト(ディスプレイ数式の場合)は、そのまま文字通り出力されます。

Markdown, Emacs Org mode, ConTeXt, ZimWiki

$ 記号で囲まれたもの(インライン数式の場合)、もしくは $$ 記号で囲まれたもの(ディスプレイ数式の場合)が、そのまま文字通り出力されます。

XWiki

{{formula}} .. {{/formula}} 中のテキストは、そのまま文字通り出力されます。

reStructuredText

It will be rendered using an interpreted text role `:math:```_.

AsciiDoc

AsciiDoc出力形式の場合 (-t asciidoc)、 latexmath:[$ ... $] 中のテキスト(インライン数式の場合)、もしくは [latexmath]++++\[ ... \]+++ 中のテキスト(ディスプレイ数式の場合)が、そのまま文字通り出力されます。AsciiDoctor出力形式の場合 (-t asciidoctor)、LaTeXの区切り文字 ($ .. $ および \[ .. \])は省略されます。

Texinfo

@math コマンドに埋め込む形で生成されます。

roff man, Jira markup

It will be rendered verbatim without $’s.

MediaWiki, DokuWiki

<math> タグで囲まれて生成されます。

Textile

<span class="math"> で囲まれて生成されます。

RTF, OpenDocument

可能であれば、Unicode文字で生成されます。そうでなければ、そのまま文字通りに出力されます。

ODT

可能であれば、MathMLで出力されます。

DocBook

--mathml オプションが指定された場合は、MathMLを用いて inlineequation もしくは informalequation タグに囲まれて生成されます。そうでなければ、可能な限りUnicode文字で生成されます。

Docx

OMML 数式マークアップ形式で出力されます。

FictionBook2

--webtex オプションが指定された場合は、数式はCodeCogsやその他の互換性のあるWebサービスを用いて、画像として生成されます。生成された画像は、ダウンロードされてe-bookに埋め込まれます。そうでなければ、そのまま文字通りに出力されます。

HTML, Slidy, DZSlides, S5, EPUB

HTMLにおける数式の生成方法は、選ばれたコマンドラインオプションに依存します。上述の Math rendering in HTML を参照してください。

生のHTML

Markdownでは、文書中のどこにでも生のHTML (もしくはDocBook) 記法を挿入できます (ただし、コードブロックやインラインコードなど、 <, > および & がそのまま(文字通り)変換されるようなコンテキストは除きます) 。(これは、実際は拡張機能ではなく、標準のMarkdownにおいても可能な機能です。しかし、ユーザが望んだ時にオフにできるように、この機能は拡張機能として実装されています。)

生のHTMLは、HTML, S5, Slidy, Slideous, DZslides, EPUB, Markdown, CommonMark, Emacs Org mode, およびTextile フォーマットで出力する場合は、そのまま何もされずに出力されます。これ以外のフォーマットでは、出力されません。

生のHTML記法をMarkdown文書に挿入するにあたって、より明示的な方法を知りたい場合は、 `raw_attribute extension`_ を参照してください。

CommonMark形式では、 raw_html 拡張が追加されている場合、上付き文字、下付き文字、取り消し線、およびスモールキャピタルがHTMLに変換されます。それ以外の場合、プレーンテキストに変換されます。 raw_html 拡張が無効になっていたとしても、表はHTML構文にレンダリングされることに注意してください。

Original Markdown allows you to include HTML “blocks”: blocks of HTML between balanced tags that are separated from the surrounding text with blank lines, and start and end at the left margin. Within these blocks, everything is interpreted as HTML, not Markdown; so (for example), * does not signify emphasis.

markdown_strict 形式を用いた場合、Pandocはこのように動作します。しかし、デフォルトでは、PandocはHTMLブロックタグ内の内容を、Markdownとして解釈します。すなわち、Pandocは、以下に示したような内容

<table>
<tr>
<td>*one*</td>
<td>[a link](https://google.com)</td>
</tr>
</table>

を

<table>
<tr>
<td><em>one</em></td>
<td><a href="https://google.com">a link</a></td>
</tr>
</table>

へと変換します。一方で、 Markdown.pl は、上の例のようにMarkdownとして解釈した変換を行わないでしょう。

There is one exception to this rule: text between <script>, <style>, and <textarea> tags is not interpreted as Markdown.

This departure from original Markdown should make it easier to mix Markdown with HTML block elements. For example, one can surround a block of Markdown text with <div> tags without preventing it from being interpreted as Markdown.

Use native pandoc Div blocks for content inside <div> tags. For the most part this should give the same output as markdown_in_html_blocks, but it makes it easier to write pandoc filters to manipulate groups of blocks.

Use native pandoc Span blocks for content inside <span> tags. For the most part this should give the same output as raw_html, but it makes it easier to write pandoc filters to manipulate groups of inlines.

In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be included in a document. Inline TeX commands will be preserved and passed unchanged to the LaTeX and ConTeXt writers. Thus, for example, you can use LaTeX to include BibTeX citations:

This result was proved in \cite{jones.1967}.

Note that in LaTeX environments, like

\begin{tabular}{|l|l|}\hline
Age & Frequency \\ \hline
18--25  & 15 \\
26--35  & 33 \\
36--45  & 22 \\ \hline
\end{tabular}

the material between the begin and end tags will be interpreted as raw LaTeX, not as Markdown.

For a more explicit and flexible way of including raw TeX in a Markdown document, see the `raw_attribute extension`_.

Inline LaTeX is ignored in output formats other than Markdown, LaTeX, Emacs Org mode, and ConTeXt.

Generic raw attribute

拡張: raw_attribute

Inline spans and fenced code blocks with a special kind of attribute will be parsed as raw content with the designated format. For example, the following produces a raw roff ms block:

```{=ms}
.MYMACRO
blah blah
```

And the following produces a raw html inline element:

This is `<a>html</a>`{=html}

これは生のxmlを docx ドキュメントに挿入するのに便利です。例えば、改ページの場合は

```{=openxml}
<w:p>
  <w:r>
    <w:br w:type="page"/>
  </w:r>
</w:p>
```

The format name should match the target format name (see -t/--to, above, for a list, or use pandoc --list-output-formats). Use openxml for docx output, opendocument for odt output, html5 for epub3 output, html4 for epub2 output, and latex, beamer, ms, or html5 for pdf output (depending on what you use for --pdf-engine).

This extension presupposes that the relevant kind of inline code or fenced code block is enabled. Thus, for example, to use a raw attribute with a backtick code block, backtick_code_blocks must be enabled.

The raw attribute cannot be combined with regular attributes.

LaTeX マクロ

この拡張機能が有効なとき、Pandocは、LaTeXマクロ定義を解析し、すべてのLaTeX数式および生のLaTeXに対してマクロを実行します。そのため、以下の例では、LaTeX だけで無くすべての出力形式でマクロが機能します:

\newcommand{\tuple}[1]{\langle #1 \rangle}

$\tuple{a, b, c}$

Note that LaTeX macros will not be applied if they occur inside a raw span or block marked with the `raw_attribute extension`_.

When latex_macros is disabled, the raw LaTeX and math will not have macros applied. This is usually a better approach when you are targeting LaTeX or PDF.

Macro definitions in LaTeX will be passed through as raw LaTeX only if latex_macros is not enabled. Macro definitions in Markdown source (or other formats allowing raw_tex) will be passed through regardless of whether latex_macros is enabled.

画像

! が直前についたリンクは画像として扱われます。リンクテキストは画像の代替テキストとして使われます。

![la lune](lalune.jpg "Voyage to the moon")

![movie reel]

[movie reel]: movie.gif

空白でない代替テキストのある画像は、パラグラフ内でそれ自身で発生した、キャプションのついた画像として処理されます。画像の代替テキストはキャプションとして使用されます。

![This is the caption](/url/of/image.png)

これがどのようにレンダリングされるかは出力形式に依存します。いくつかの出力形式（例えば RTF）は図をサポートしていません。これらの形式ではユーザはパラグラフ内にキャプションのない画像が得られます。

もし段落にインライン画像だけを配置したい場合、1つの段落に1つの画像だけを配置することはできません。1つの回避策として、画像の後に改行を伴わないスペースを挿入する方法があります：

![This image won't be a figure](/url/of/image.png)\

Note that in reveal.js slide shows, an image in a paragraph by itself that has the r-stretch class will fill the screen, and the caption and figure tags will be omitted.

属性はリンクと画像に設定できます

An inline ![image](foo.jpg){#id .class width=30 height=20px}
and a reference ![image][ref] with attributes.

[ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}

(This syntax is compatible with PHP Markdown Extra when only #id and .class are used.)

For HTML and EPUB, all known HTML5 attributes except width and height (but including srcset and sizes) are passed through as is. Unknown attributes are passed through as custom attributes, with data- prepended. The other writers ignore attributes that are not specifically supported by their output format.

The width and height attributes on images are treated specially. When used without a unit, the unit is assumed to be pixels. However, any of the following unit identifiers can be used: px, cm, mm, in, inch and %. There must not be any spaces between the number and the unit. For example:

![](file.jpg){ width=50% }

  • Dimensions may be converted to a form that is compatible with the output format (for example, dimensions given in pixels will be converted to inches when converting HTML to LaTeX). Conversion between pixels and physical measurements is affected by the --dpi option (by default, 96 dpi is assumed, unless the image itself contains dpi information).

  • The % unit is generally relative to some available space. For example the above example will render to the following.

    • HTML: <img href="file.jpg" style="width: 50%;" />

    • LaTeX: \includegraphics[width=0.5\textwidth,height=\textheight]{file.jpg} (カスタムテンプレートを利用している場合、デフォルトのテンプレートと同じように graphicx を設定する必要があります)

    • ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]

  • Some output formats have a notion of a class (ConTeXt) or a unique identifier (LaTeX \caption), or both (HTML).

  • When no width or height attributes are specified, the fallback is to look at the image resolution and the dpi metadata embedded in the image file.

Div と Span

Using the native_divs and native_spans extensions (see above), HTML syntax can be used as part of markdown to create native Div and Span elements in the pandoc AST (as opposed to raw HTML). However, there is also nicer syntax available:

Allow special fenced syntax for native Div blocks. A Div starts with a fence containing at least three consecutive colons plus some attributes. The attributes may optionally be followed by another string of consecutive colons. The attribute syntax is exactly as in fenced code blocks (see Extension: ``fenced_code_attributes``). As with fenced code blocks, one can use either attributes in curly braces or a single unbraced word, which will be treated as a class name. The Div ends with another line containing a string of at least three consecutive colons. The fenced Div should be separated by blank lines from preceding and following blocks.

例：

::::: {#special .sidebar}
Here is a paragraph.

And another.
:::::

Fenced divs can be nested. Opening fences are distinguished because they must have attributes:

::: Warning ::::::
This is a warning.

::: Danger
This is a warning within a warning.
:::
::::::::::::::::::

Fences without attributes are always closing fences. Unlike with fenced code blocks, the number of colons in the closing fence need not match the number in the opening fence. However, it can be helpful for visual clarity to use fences of different lengths to distinguish nested divs from their parents.

A bracketed sequence of inlines, as one would use to begin a link, will be treated as a Span with attributes if it is followed immediately by attributes:

[This is *some text*]{.class key="val"}

脚注

Pandoc’s Markdown では、次の構文によって脚注を使うことができます:

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

        { some.code }

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.

脚注の識別子には、スペース、タブ文字、および改行文字を使用することができません。識別子は、脚注がつけられた位置と脚注の内容とを関連づけるためにだけ用いられます。出力では、脚注に順番に番号が振られます。

脚注の内容は、必ずしも文書の末尾に置かれている必要はありません。脚注は、ブロック(リスト、引用ブロック、テーブルなど)の中以外ならば、どこに置いても構いません。それぞれの脚注は、直前と直後に空白行を置くことによって、(他の脚注も含めた)周囲のコンテンツから区切られている必要があります。

インライン脚注も使用可能です (ただし、これは通常の脚注とは異なり、脚注の内容を複数行に渡らせることはできません)。構文を以下に示します:

Here is an inline note.^[Inlines notes are easier to write, since
you don't have to pick an identifier and move down to type the
note.]

インライン脚注と通常の脚注は混在しても構いません。

Citation syntax

To cite a bibliographic item with an identifier foo, use the syntax @foo. Normal citations should be included in square brackets, with semicolons separating distinct items:

Blah blah [@doe99; @smith2000; @smith2004].

How this is rendered depends on the citation style. In an author-date style, it might render as

Blah blah (Doe 1999, Smith 2000, 2004).

In a footnote style, it might render as

Blah blah.[^1]

[^1]:  John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
Susan Smith, "Flies," *Journal of Insects* (2000);
Susan Smith, "Bees," *Journal of Insects* (2004).

See the CSL user documentation for more information about CSL styles and how they affect rendering.

Unless a citation key start with a letter, digit, or _, and contains only alphanumerics and single internal punctuation characters (:.#$%&-+?<>~/), it must be surrounded by curly braces, which are not considered part of the key. In @Foo_bar.baz., the key is Foo_bar.baz because the final period is not internal punctuation, so it is not included in the key. In @{Foo_bar.baz.}, the key is Foo_bar.baz., including the final period. In @Foo_bar--baz, the key is Foo_bar because the repeated internal punctuation characters terminate the key. The curly braces are recommended if you use URLs as keys: [@{https://example.com/bib?name=foobar&date=2000}, p.  33].

Citation items may optionally include a prefix, a locator, and a suffix. In

Blah blah [see @doe99, pp. 33-35 and *passim*; @smith04, chap. 1].

The first item (doe99) has prefix see, locator pp.  33-35, and suffix and *passim*. The second item (smith04) has locator chap. 1 and no prefix or suffix.

Pandoc uses some heuristics to separate the locator from the rest of the subject. It is sensitive to the locator terms defined in the CSL locale files. Either abbreviated or unabbreviated forms are accepted. In the en-US locale, locator terms can be written in either singular or plural forms, as book, bk./bks.; chapter, chap./chaps.; column, col./cols.; figure, fig./figs.; folio, fol./fols.; number, no./nos.; line, l./ll.; note, n./nn.; opus, op./opp.; page, p./pp.; paragraph, para./paras.; part, pt./pts.; section, sec./secs.; sub verbo, s.v./s.vv.; verse, v./vv.; volume, vol./vols.; /¶¶; §/§§. If no locator term is used, “page” is assumed.

In complex cases, you can force something to be treated as a locator by enclosing it in curly braces or prevent parsing the suffix as locator by prepending curly braces:

[@smith{ii, A, D-Z}, with a suffix]
[@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
[@smith{}, 99 years later]

マイナス記号 (-) を @ 記号の前に置くことで、著者名が表示されなくなります。この記法は、文中ですでに著者名について言及しているときに便利です:

Smith says blah [-@smith04].

You can also write an author-in-text citation, by omitting the square brackets:

@smith04 says blah.

@smith04 [p. 33] says blah.

This will cause the author’s name to be rendered, followed by the bibliographical details. Use this form when you want to make the citation the subject of a sentence.

When you are using a note style, it is usually better to let citeproc create the footnotes from citations rather than writing an explicit note. If you do write an explicit note that contains a citation, note that normal citations will be put in parentheses, while author-in-text citations will not. For this reason, it is sometimes preferable to use the author-in-text style inside notes when using a note style.

Non-default extensions

以下に示したMarkdown構文の拡張機能は、デフォルトのPandocでは有効になっていませんが、フォーマット名に +EXTENSION を追加することで、それぞれの拡張機能を有効にできます。ここで、 EXTENSION は拡張機能の名前を指します。たとえば、 markdown+hard_line_breaks は、 hard_line_breaks 拡張を含むMarkdownです。

Rewrite relative paths for Markdown links and images, depending on the path of the file containing the link or image link. For each link or image, pandoc will compute the directory of the containing file, relative to the working directory, and prepend the resulting path to the link or image path.

The use of this extension is best understood by example. Suppose you have a a subdirectory for each chapter of a book, chap1, chap2, chap3. Each contains a file text.md and a number of images used in the chapter. You would like to have ![image](spider.jpg) in chap1/text.md refer to chap1/spider.jpg and ![image](spider.jpg) in chap2/text.md refer to chap2/spider.jpg. To do this, use

pandoc chap*/*.md -f markdown+rebase_relative_paths

Without this extension, you would have to use ![image](chap1/spider.jpg) in chap1/text.md and ![image](chap2/spider.jpg) in chap2/text.md. Links with relative paths will be rewritten in the same way as images.

Absolute paths and URLs are not changed. Neither are empty paths or paths consisting entirely of a fragment, e.g., #foo.

Note that relative paths in reference links and images will be rewritten relative to the file containing the link reference definition, not the file containing the reference link or image itself, if these differ.

Allows attributes to be attached to any inline or block-level element when parsing commonmark. The syntax for the attributes is the same as that used in ```header_attributes```_.

  • Attributes that occur immediately after an inline element affect that element. If they follow a space, then they belong to the space. (Hence, this option subsumes inline_code_attributes and link_attributes.)

  • Attributes that occur immediately before a block element, on a line by themselves, affect that element.

  • Consecutive attribute specifiers may be used, either for blocks or for inlines. Their attributes will be combined.

  • Attributes that occur at the end of the text of a Setext or ATX heading (separated by whitespace from the text) affect the heading element. (Hence, this option subsumes header_attributes.)

  • Attributes that occur after the opening fence in a fenced code block affect the code block element. (Hence, this option subsumes fenced_code_attributes.)

  • Attributes that occur at the end of a reference link definition affect links that refer to that definition.

Note that pandoc’s AST does not currently allow attributes to be attached to arbitrary elements. Hence a Span or Div container will be added if needed.

Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: - before a numeral is an en-dash, and -- is an em-dash. This option only has an effect if smart is enabled. It is selected automatically for textile input.

Allow < and > to be backslash-escaped, as they can be in GitHub flavored Markdown but not original Markdown. This is implied by pandoc’s default all_symbols_escapable.

リストを、段落の直後に空白行なしで置くことを許可します。

リスト生成に関するPandoc バージョン2.0以下の挙動を選択します。この場合、リスト項目が複数行に渡る場合、2行目以降のリスト項目の文頭に4つの空白文字を置く必要があります。

2つの参照リンクの間に、空白文字を置くことを許可します。たとえば、

[foo] [bar].

段落内の全ての改行文字を、空白ではなく強制改行として処理します。

段落内の改行を、スペースもしくは強制改行として扱わず、完全に無視します。このオプションは、読みやすくするためにテキストを行に分割して記述するが、単語間にはスペースを置かないような東アジア言語で使用します。

改行文字が、全角文字が末尾に置かれた行と全角文字で始まる行の間にある場合、その改行をスペースもしくは強制改行として扱わず、完全に無視します。この拡張機能は、全角文字とそれ以外の文字が混在するテキストにおいて、 ignore_line_breaks よりも適切な選択です。

:smile: のような絵文字のテキスト表記を、Unicode絵文字アイコンに変換します。

\( と \) の間のテキストを、TeX インライン数式として扱います。また、 \[ と \] の間のテキストを、TeX ディスプレイ数式として扱います。注意: この拡張機能を使うと、 ( と [ のエスケープができなくなるという欠点があります。

\\( と \\) の間のテキストを、TeX インライン数式として扱います。また、 \\[ と \\] の間のテキストを、TeX ディスプレイ数式として扱います。

By default, pandoc interprets material inside block-level tags as Markdown. This extension changes the behavior so that Markdown is only parsed inside block-level tags if the tags have the attribute markdown=1.

文書のはじめに、 MultiMarkdown 形式のタイトルブロックを置くことが可能になります。たとえば:

Title:   My title
Author:  John Doe
Date:    September 1, 2008
Comment: This is a sample mmd title block, with
         a field spanning multiple lines.

詳しくは、 MultiMarkdown のドキュメンテーションを参照してください。 pandoc_title_block もしくは yaml_metadata_block 拡張が有効になっている場合、これらの拡張が mmd_title_block よりも優先されます。

以下に示したような、PHP Markdown Extra の省略表記の記法を処理します

*[HTML]: Hypertext Markup Language

Note that the pandoc document model does not support abbreviations, so if this extension is enabled, abbreviation keys are simply skipped (as opposed to being parsed as paragraphs).

山括弧 < ... > で囲まれていない場合でも、完全なURIをリンクとして処理します。

MultiMarkdown形式のリンクおよび画像の参照記法を処理します。この拡張を ```link_attributes```_ 拡張と混同しないように注意してください。

This is a reference ![image][ref] with multimarkdown attributes.

[ref]: https://path.to/image "Image title" width=20px height=30px
       id=myId class="myClass1 myClass2"

Parses multimarkdown style heading identifiers (in square brackets, after the heading but before any trailing #s in an ATX heading).

Activates the definition list syntax of pandoc 1.12.x and earlier. This syntax differs from the one described above under Definition lists in several respects:

  • No blank line is required between consecutive items of the definition list.

  • To get a “tight” or “compact” list, omit space between consecutive items; the space between a term and its definition does not affect anything.

  • Lazy wrapping of paragraphs is not allowed: the entire definition must be indented four spaces. 4

Use Project Gutenberg conventions for plain output: all-caps for strong emphasis, surround by underscores for regular emphasis, add extra blank space around headings.

Include source position attributes when parsing commonmark. For elements that accept attributes, a data-pos attribute is added; other elements are placed in a surrounding Div or Span element with a data-pos attribute.

Parse multimarkdown style subscripts and superscripts, which start with a ‘~’ or ‘^’ character, respectively, and include the alphanumeric sequence that follows. For example:

x^2 = 4

や

Oxygen is O~2.

Markdown方言

Pandocの拡張マークダウンに加えて、以下のMarkdown方言をサポートしています:

  • markdown_phpextra (PHP Markdown Extra)

  • markdown_github (廃止されたGitHub-Flavored Markdown)

  • markdown_mmd (MultiMarkdown)

  • markdown_strict (Markdown.pl)

  • commonmark (CommonMark)

  • gfm (Github-Flavored Markdown)

  • commonmark_x (CommonMark with many pandoc extensions)

To see which extensions are supported for a given format, and which are enabled by default, you can use the command

pandoc --list-extensions=FORMAT

where FORMAT is replaced with the name of the format.

Note that the list of extensions for commonmark, gfm, and commonmark_x are defined relative to default commonmark. So, for example, backtick_code_blocks does not appear as an extension, since it is enabled by default and cannot be disabled.

引用

When the --citeproc option is used, pandoc can automatically generate citations and a bibliography in a number of styles. Basic usage is

pandoc --citeproc myinput.txt

To use this feature, you will need to have

  • a document containing citations (see Extension: ``citations``);

  • a source of bibliographic data: either an external bibliography file or a list of references in the document’s YAML metadata

  • optionally, a CSL citation style.

Specifying bibliographic data

You can specify an external bibliography using the bibliography metadata field in a YAML metadata section or the --bibliography command line argument. If you want to use multiple bibliography files, you can supply multiple --bibliography arguments or set bibliography metadata field to YAML array. A bibliography may have any of these formats:

フォーマット

拡張子

BibLaTeX

.bib

BibTeX

.bibtex

CSL JSON

.json

CSL YAML

.yaml

RIS

.ris

Note that .bib can be used with both BibTeX and BibLaTeX files; use the extension .bibtex to force interpretation as BibTeX.

In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside fields such as title; in CSL YAML databases, pandoc Markdown; and in CSL JSON databases, an HTML-like markup:

<i>...</i>

斜体

<b>...</b>

太字

<span style="font-variant:small-caps;">...</span> もしくは <sc>...</sc>

スモールキャピタル

<sub>...</sub>

下付き文字

<sup>...</sup>

上付き文字

<span class="nocase">...</span>

タイトルケース表記において、タグで囲まれたテキストの語頭を大文字にすることを防ぐ

--bibliography もしくはYAMLメタデータフィールド bibliography を用いて参考文献ファイルを指定するかわりに、文書内のYAMLメタデータフィールド references 中に直接引用文献データを書くことが可能です。このメタデータフィールドには、YAML形式で書かれた参考文献のリストが配列として記述されている必要があります。たとえば:

---
references:
- type: article-journal
  id: WatsonCrick1953
  author:
  - family: Watson
    given: J. D.
  - family: Crick
    given: F. H. C.
  issued:
    date-parts:
    - - 1953
      - 4
      - 25
  title: 'Molecular structure of nucleic acids: a structure for
    deoxyribose nucleic acid'
  title-short: Molecular structure of nucleic acids
  container-title: Nature
  volume: 171
  issue: 4356
  page: 737-738
  DOI: 10.1038/171737a0
  URL: https://www.nature.com/articles/171737a0
  language: en-GB
...

If both an external bibliography and inline (YAML metadata) references are provided, both will be used. In case of conflicting ids, the inline references will take precedence.

Note that pandoc can be used to produce such a YAML metadata section from a BibTeX, BibLaTeX, or CSL JSON bibliography:

pandoc chem.bib -s -f biblatex -t markdown
pandoc chem.json -s -f csljson -t markdown

Indeed, pandoc can convert between any of these citation formats:

pandoc chem.bib -s -f biblatex -t csljson
pandoc chem.yaml -s -f markdown -t biblatex

Running pandoc on a bibliography file with the --citeproc option will create a formatted bibliography in the format of your choice:

pandoc chem.bib -s --citeproc -o chem.html
pandoc chem.bib -s --citeproc -o chem.pdf

Capitalization in titles

If you are using a bibtex or biblatex bibliography, then observe the following rules:

  • English titles should be in title case. Non-English titles should be in sentence case, and the langid field in biblatex should be set to the relevant language. (The following values are treated as English: american, british, canadian, english, australian, newzealand, USenglish, or UKenglish.)

  • As is standard with bibtex/biblatex, proper names should be protected with curly braces so that they won’t be lowercased in styles that call for sentence case. For example:

    title = {My Dinner with {Andre}}

  • In addition, words that should remain lowercase (or camelCase) should be protected:

    title = {Spin Wave Dispersion on the {nm} Scale}

    Though this is not necessary in bibtex/biblatex, it is necessary with citeproc, which stores titles internally in sentence case, and converts to title case in styles that require it. Here we protect “nm” so that it doesn’t get converted to “Nm” at this stage.

If you are using a CSL bibliography (either JSON or YAML), then observe the following rules:

  • All titles should be in sentence case.

  • Use the language field for non-English titles to prevent their conversion to title case in styles that call for this. (Conversion happens only if language begins with en or is left empty.)

  • Protect words that should not be converted to title case using this syntax:

    Spin wave dispersion on the <span class="nocase">nm</span> scale

Conference Papers, Published vs. Unpublished

For a formally published conference paper, use the biblatex entry type inproceedings (which will be mapped to CSL paper-conference).

For an unpublished manuscript, use the biblatex entry type unpublished without an eventtitle field (this entry type will be mapped to CSL manuscript).

For a talk, an unpublished conference paper, or a poster presentation, use the biblatex entry type unpublished with an eventtitle field (this entry type will be mapped to CSL speech). Use the biblatex type field to indicate the type, e.g. “Paper”, or “Poster”. venue and eventdate may be useful too, though eventdate will not be rendered by most CSL styles. Note that venue is for the event’s venue, unlike location which describes the publisher’s location; do not use the latter for an unpublished conference paper.

Specifying a citation style

Citations and references can be formatted using any style supported by the Citation Style Language, listed in the Zotero Style Repository. These files are specified using the --csl option or the csl (or citation-style) metadata field. By default, pandoc will use the Chicago Manual of Style author-date format. (You can override this default by copying a CSL style of your choice to default.csl in your user data directory.) The CSL project provides further information on finding and editing styles.

The --citation-abbreviations option (or the citation-abbreviations metadata field) may be used to specify a JSON file containing abbreviations of journals that should be used in formatted bibliographies when form="short" is specified. The format of the file can be illustrated with an example:

{ "default": {
    "container-title": {
            "Lloyd's Law Reports": "Lloyd's Rep",
            "Estates Gazette": "EG",
            "Scots Law Times": "SLT"
    }
  }
}

Citations in note styles

Pandoc’s citation processing is designed to allow you to move between author-date, numerical, and note styles without modifying the markdown source. When you’re using a note style, avoid inserting footnotes manually. Instead, insert citations just as you would in an author-date style—for example,

Blah blah [@foo, p. 33].

The footnote will be created automatically. Pandoc will take care of removing the space and moving the note before or after the period, depending on the setting of notes-after-punctuation, as described below in Other relevant metadata fields.

In some cases you may need to put a citation inside a regular footnote. Normal citations in footnotes (such as [@foo, p. 33]) will be rendered in parentheses. In-text citations (such as @foo [p. 33]) will be rendered without parentheses. (A comma will be added if appropriate.) Thus:

[^1]:  Some studies [@foo; @bar, p. 33] show that
frubulicious zoosnaps are quantical.  For a survey
of the literature, see @baz [chap. 1].

Raw content in a style

To include raw content in a prefix, suffix, delimiter, or term, surround it with these tags indicating the format:

{{jats}}&lt;ref&gt;{{/jats}}

Without the tags, the string will be interpreted as a string and escaped in the output, rather than being passed through raw.

This feature allows stylesheets to be customized to give different output for different output formats. However, stylesheets customized in this way will not be usable by other CSL implementations.

Placement of the bibliography

CSLによって文献目録の生成が設定されている場合、 refs idをもつ div があれば、その中に文献目録が生成されます:

::: {#refs}
:::

それ以外の場合は、文献目録は文書の末尾に置かれます。YAMLメタデータで suppress-bibliography: true と設定することで、文献目録の生成を無効にできます。

文献目録をセクションとして分けて見出しを付けたい場合、メタデータ中の reference-section-title を設定するか、refs idをもつdivの直前に見出しを置く、もしくは文書の末尾に見出しを置いてください。

last paragraph...

# References

The bibliography will be inserted after this heading. Note that the unnumbered class will be added to this heading, so that the section will not be numbered.

If you want to put the bibliography into a variable in your template, one way to do that is to put the div with id refs into a metadata field, e.g.

---
refs: |
   ::: {#refs}
   :::
...

You can then put the variable $refs$ into your template where you want the bibliography to be placed.

Including uncited items in the bibliography

書誌情報を本文中で引用せずに文献目録に加えたい場合、 nocite メタデータフィールドにダミーの引用を置いてください:

---
nocite: |
  @item1, @item2
...

@item3

この例では、本文には item3 の引用しか生成されませんが、文書末尾に生成される文献目録には、 item1, item2 および item3 の3つの書誌情報が含まれます。

本文中で引用するかどうかに関わらず、bibliography ファイルに含まれる全ての文献を文献目録として生成したい場合は、ワイルドカードを用います:

---
nocite: |
  @*
...

For LaTeX output, you can also use `natbib```_ or ```biblatex```_ to render the bibliography. In order to do so, specify bibliography files as outlined above, and add ``--natbib or --biblatex argument to pandoc invocation. Bear in mind that bibliography files have to be in either BibTeX (for --natbib) or BibLaTeX (for --biblatex) format.

Other relevant metadata fields

A few other metadata fields affect bibliography formatting:

link-citations

If true, citations will be hyperlinked to the corresponding bibliography entries (for author-date and numerical styles only). Defaults to false.

link-bibliography

If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be rendered as hyperlinks. (If an entry contains a DOI, PMCID, PMID, or URL, but none of these fields are rendered by the style, then the title, or in the absence of a title the whole entry, will be hyperlinked.) Defaults to true.

lang

The lang field will affect how the style is localized, for example in the translation of labels, the use of quotation marks, and the way items are sorted. (For backwards compatibility, locale may be used instead of lang, but this use is deprecated.)

A BCP 47 language tag is expected: for example, en, de, en-US, fr-CA, ug-Cyrl. The unicode extension syntax (after -u-) may be used to specify options for collation (sorting) more precisely. Here are some examples:

  • zh-u-co-pinyin – Chinese with the Pinyin collation.

  • es-u-co-trad – Spanish with the traditional collation (with Ch sorting after C).

  • fr-u-kb – French with “backwards” accent sorting (with coté sorting after côte).

  • en-US-u-kf-upper – English with uppercase letters sorting before lower (default is lower before upper).

notes-after-punctuation

If true (the default for note styles), pandoc will put footnote references or superscripted numerical citations after following punctuation. For example, if the source contains blah blah [@jones99]., the result will look like blah blah.[^1], with the note moved after the period and the space collapsed. If false, the space will still be collapsed, but the footnote will not be moved after the punctuation. The option may also be used in numerical styles that use superscripts for citation numbers (but for these styles the default is not to move the citation).

Slide shows

Pandocを使うと、Webブラウザで閲覧可能なHTML + JavaScript のスライドプレゼンテーションを生成できます。スライドには、 S5, DZSlides, Slidy, Slideous, reveal.js `_ の5つの形式があります。あるいは、LaTeX ```beamer`` によるPDFスライドや、Microsoft PowerPoint 形式のスライドを生成することもできます。

シンプルなスライドショーを作成するMarkdownソース habits.txt の例を示します:

% Habits
% John Doe
% March 22, 2005

# In the morning

## Getting up

- Turn off alarm
- Get out of bed

## Breakfast

- Eat eggs
- Drink coffee

# In the evening

## Dinner

- Eat spaghetti
- Drink wine

------------------

![picture of spaghetti](images/spaghetti.jpg)

## Going to sleep

- Get in bed
- Count sheep

HTML/JavaScript スライドショーを得るには、単に次のように実行します。

pandoc -t FORMAT -s habits.txt -o habits.html

ここで FORMAT は s5 、 slidy 、 slideous 、 dzslides または revealjs のいずれかです。

Slidy, Slideous, reveal.js, およびS5の場合、 -s/--standalone オプション付きで出力されたファイルには、JavaScriptおよびCSSファイルへのリンクが埋め込まれます。既定では、それらのファイルはそれぞれ次の相対パスにおいて有効とみなされます: s5/default (S5の場合) 、 slideous (Slideousの場合) 、 reveal.js (reveal.jsの場合) 、 w3.org 上のSlidyのWebサイト (for Slidy) (これらのパスは、それぞれ変数 slidy-url, slideous-url, revealjs-url, s5-url を用いて変更できます。詳しくは、上述の Variables for HTML slides を参照してください)。DZSlidesについては、既定では（比較的短い）JavaScriptとCSSが出力ファイルに含まれます。

すべてのHTMLスライド形式において、 --self-contained オプションを用いることで、画面にスライドショーを表示するためのすべてのデータ (スクリプト、スタイルシート、画像および動画) を含めて、単一ファイルとして出力できます。

beamerでPDFスライドショーを出力するには、次のように実行します。

pandoc -t beamer habits.txt -o habits.pdf

補足: reveal.js スライドショーは、ブラウザを用いてPDFとして印刷することも可能です。

PowerPoint スライドショーを出力するには、次を実行します。

pandoc habits.txt -o habits.pptx

スライドショーの構造をつくる

既定では、 スライドレベル (slide level) には、見出し以外の何らかのスライドコンテンツが直後に現れる見出しの中で、最も高い見出しレベルが設定されます。上記の例 (訳注: habits.txt ) では常に、レベル 1 の見出しの直後にレベル 2の見出しが置かれています。このレベル 2 のヘッダの直後には、スライドコンテンツが置かれています。つまりこの例では、スライドレベルは2です。この既定動作は --slide-level  オプションで変更できます。

1つの文書は、次のルールによっていくつかのスライドに分割されます:

  • 水平線は、常に新しいスライドを開始する。

  • スライドレベルと同じレベルを持つ見出しは、常に新しいスライドを開始する。

  • Headings below the slide level in the hierarchy create headings within a slide. (In beamer, a “block” will be created. If the heading has the class example, an exampleblock environment will be used; if it has the class alert, an alertblock will be used; otherwise a regular block will be used.)

  • スライドレベルよりも 上位の (訳注: レベルを表す数字が小さい) 見出しは、セクションタイトルのみを表示する「タイトルスライド」を作る。これにより、一つのスライドショーを複数のセクションに分けて発表することが容易になる。この場合、見出しの直下に置かれた非スライド要素は、(HTML スライドショーの場合)タイトルスライドに含まれるか、(beamerの場合)タイトルスライドと同じタイトルを持つスライドが作られ、そのスライドに含まれるかされます。

  • タイトルページは、(もし存在すれば) 文書のタイトルブロックから自動的に生成される (beamer の場合、デフォルトテンプレートのいくつかの行をコメントアウトすることで無効にできる)。

These rules are designed to support many different styles of slide show. If you don’t care about structuring your slides into sections and subsections, you can either just use level-1 headings for all slides (in that case, level 1 will be the slide level) or you can set --slide-level=0.

Note: in reveal.js slide shows, if slide level is 2, a two-dimensional layout will be produced, with level-1 headings building horizontally and level-2 headings building vertically. It is not recommended that you use deeper nesting of section levels with reveal.js unless you set --slide-level=0 (which lets reveal.js produce a one-dimensional layout and only interprets horizontal rules as slide boundaries).

PowerPoint layout choice

When creating slides, the pptx writer chooses from a number of pre-defined layouts, based on the content of the slide:

タイトル スライド

This layout is used for the initial slide, which is generated and filled from the metadata fields date, author, and title, if they are present.

セクション見出し

This layout is used for what pandoc calls “title slides”, i.e. slides which start with a header which is above the slide level in the hierarchy.

2 つのコンテンツ

This layout is used for two-column slides, i.e. slides containing a div with class columns which contains at least two divs with class column.

Comparison

This layout is used instead of “Two Content” for any two-column slides in which at least one column contains text followed by non-text (e.g. an image or a table).

Content with Caption

This layout is used for any non-two-column slides which contain text followed by non-text (e.g. an image or a table).

Blank

This layout is used for any slides which only contain blank content, e.g. a slide containing only speaker notes, or a slide containing only a non-breaking space.

タイトルとコンテンツ

This layout is used for all slides which do not match the criteria for another layout.

These layouts are chosen from the default pptx reference doc included with pandoc, unless an alternative reference doc is specified using --reference-doc.

インクリメンタルリスト

既定では、スライドショーはリストを「すべて一気に (all at once)」見せるように出力されます。もしリストを徐々に増やすように (incrementally)、 一度に1アイテム (one item at a time) として見せたい場合には、 -i オプションを使用します (訳注: このような動作を「インクリメンタル」と呼びます)。既定動作から離れて特定のリストだけを見せたい場合には、 div ブロックを作り、classとして incremental または nonincremental を指定してください。たとえば fenced div 拡張記法を使えば、文書の既定動作にかかわらず、下記はインクリメンタルに動作します:

::: incremental

- Eat spaghetti
- Drink wine

:::

や

::: nonincremental

- Eat spaghetti
- Drink wine

:::

incremental と nonincremental は、一時的に (on a per-case basis) インクリメンタルリストを設定する方法として推奨されています。一方で、次のような古い方法もサポートしています: 引用中のリストは、文書の既定動作に反します (これは -i オプションがなくてもインクリメンタルに表示されますし、 -i を付けても一気に表示されます)

> - Eat spaghetti
> - Drink wine

いずれの方法でも、1つの文書の中にインクリメンタルリストとそうでないリストを混在できます。

If you want to include a block-quoted list, you can work around this behavior by putting the list inside a fenced div, so that it is not the direct child of the block quote:

> ::: wrapper
> - a
> - list in a quote
> :::

ポーズの挿入

半角スペースで区切られた3つのピリオドを段落に含めることで、スライドに「ポーズ」を追加できます:

# Slide with a pause

content before the pause

. . .

content after the pause

Note: this feature is not yet implemented for PowerPoint output.

スライドのスタイルを変える

特定の場所にカスタム済のCSSファイルを配置することで、HTMLスライドの変更できます。その場所は $DATADIR/s5/default (S5の場合)、 $DATADIR/slidy (Slidyの場合)、および $DATADIR/slideous (Slideousの場合) です。ただし $DATADIR はユーザデータディレクトリです。 (上記の --data-dir を参照)。元のCSSファイルはPandocのシステムデータディレクトリ (通常は $CABALDIR/pandoc-VERSION/s5/default) にあります。Pandocはまずユーザデータディレクトリでファイルを検索し、何も見つからない場合にシステムデータディレクトリを検索します。

dzslidesについては、HTMLファイル自身の中に必要なCSSが含まれます。CSSが変更される場合も同様です。

すべての reveal.js configuration options は、変数を介して設定されます。たとえば、テーマの設定は theme 変数を用います:

-V theme=moon

あるいは --css オプションを用いて、カスタム済のスタイルシートを指定できます。

Beamerスライドのスタイルを変えるには -V オプションを用いて、 theme 、 colortheme 、 fonttheme 、 innertheme 、 および outertheme を指定します。

pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf

Note that heading attributes will turn into slide attributes (on a <div> or <section>) in HTML slide formats, allowing you to style individual slides. In beamer, a number of heading classes and attributes are recognized as frame options and will be passed through as options to the frame: see Frame attributes in beamer, below.

発表者ノート

Speaker notes are supported in reveal.js, PowerPoint (pptx), and beamer output. You can add notes to your Markdown document thus:

::: notes

This is my note.

- It can contain Markdown
- like this list

:::

reveal.js でノートウィンドウを開くには、プレゼンテーションを閲覧中に s キーを押します。発表者ノートはPowerPointにおいて、いつものように配付資料と発表者ビューで利用できます。

他のスライド形式において、ノートはまだサポートされていませんが、それでもノートがスライド中に現れることはありません。

段組み

資料を横に並べて段組みとしたい場合に、 ネイティブ Div コンテナ (columns クラス付き) を利用できます。その内側には、2つ以上の Div コンテナ (column および width 属性付き) を入れます:

:::::::::::::: {.columns}
::: {.column width="40%"}
contents...
:::
::: {.column width="60%"}
contents...
:::
::::::::::::::

Additional columns attributes in beamer

The div containers with classes columns and column can optionally have an align attribute. The class columns can optionally have a totalwidth attribute or an onlytextwidth class.

:::::::::::::: {.columns align=center totalwidth=8em}
::: {.column width="40%"}
contents...
:::
::: {.column width="60%" align=bottom}
contents...
:::
::::::::::::::

The align attributes on columns and column can be used with the values top, top-baseline, center and bottom to vertically align the columns. It defaults to top in columns.

The totalwidth attribute limits the width of the columns to the given value.

:::::::::::::: {.columns align=top .onlytextwidth}
::: {.column width="40%" align=center}
contents...
:::
::: {.column width="60%"}
contents...
:::
::::::::::::::

The class onlytextwidth sets the totalwidth to \textwidth.

See Section 12.7 of the Beamer User’s Guide for more details.

フレームの属性 (Beamer)

Sometimes it is necessary to add the LaTeX [fragile] option to a frame in beamer (for example, when using the minted environment). This can be forced by adding the fragile class to the heading introducing the slide:

# Fragile slide {.fragile}

All of the other frame attributes described in Section 8.1 of the Beamer User’s Guide may also be used: allowdisplaybreaks, allowframebreaks, b, c, s, t, environment, label, plain, shrink, standout, noframenumbering, squeeze. allowframebreaks is recommended especially for bibliographies, as it allows multiple slides to be created if the content overfills the frame:

# References {.allowframebreaks}

In addition, the frameoptions attribute may be used to pass arbitrary frame options to a beamer slide:

# Heading {frameoptions="squeeze,shrink,customoption=foobar"}

Background in reveal.js, beamer, and pptx

Background images can be added to self-contained reveal.js slide shows, beamer slide shows, and pptx slide shows.

On all slides (beamer, reveal.js, pptx)

With beamer and reveal.js, the configuration option background-image can be used either in the YAML metadata block or as a command-line variable to get the same image on every slide.

For pptx, you can use a reference doc in which background images have been set on the relevant layouts.

parallaxBackgroundImage (reveal.js)

For reveal.js, there is also the reveal.js-native option parallaxBackgroundImage, which can be used instead of background-image to produce a parallax scrolling background. You must also set parallaxBackgroundSize, and can optionally set parallaxBackgroundHorizontal and parallaxBackgroundVertical to configure the scrolling behaviour. See the reveal.js documentation for more details about the meaning of these options.

reveal.jsのoverviewモード (訳注: 複数スライドを一覧できるモード) においては、parallaxBackgroundImageは最初のスライドのものを表示します。

On individual slides (reveal.js, pptx)

To set an image for a particular reveal.js or pptx slide, add {background-image="/path/to/image"} to the first slide-level heading on the slide (which may even be empty).

As the HTML writers pass unknown attributes through, other reveal.js background settings also work on individual slides, including background-size, background-repeat, background-color, transition, and transition-speed. (The data- prefix will automatically be added.)

Note: data-background-image is also supported in pptx for consistency with reveal.js – if background-image isn’t found, data-background-image will be checked.

On the title slide (reveal.js, pptx)

To add a background image to the automatically generated title slide for reveal.js, use the title-slide-attributes variable in the YAML metadata block. It must contain a map of attribute names and values. (Note that the data- prefix is required here, as it isn’t added automatically.)

For pptx, pass a reference doc with the background image set on the “Title Slide” layout.

Example (reveal.js)

---
title: My Slide Show
parallaxBackgroundImage: /path/to/my/background_image.png
title-slide-attributes:
    data-background-image: /path/to/title_image.png
    data-background-size: contain
---

## Slide One

Slide 1 has background_image.png as its background.

## {background-image="/path/to/special_image.jpg"}

Slide 2 has a special image for its background, even though the heading has no content.

EPUBs

EPUB メタデータ

EPUB メタデータは、 --epub-metadata オプションを使うことで指定できます。ただし、もとの文書がMarkdown形式である場合は、 YAML metadata block を使うのがよいでしょう。例を示します:

---
title:
- type: main
  text: My Book
- type: subtitle
  text: An investigation of metadata
creator:
- role: author
  text: John Smith
- role: editor
  text: Sarah Jones
identifier:
- scheme: DOI
  text: doi:10.234234.234/33
publisher:  My Press
rights: © 2007 John Smith, CC BY-NC
ibooks:
  version: 1.3.4
...

以下の項目が認識されます：

identifier (訳注: 識別子)

文字列値またはフィールド text および scheme のオブジェクト。 scheme の有効な値は ISBN-10 、 GTIN-13 、 UPC 、 ISMN-10 、 DOI 、 LCCN 、 GTIN-14 、 ISBN-13 、 Legal deposit number 、 URN 、 OCLC 、 ISMN-13 、 ISBN-A 、 JP 、 OLCC 。

title

文字列値、またはフィールド file-as および type のオブジェクト、またはこのようなオブジェクトのリスト。type の有効な値は main 、 subtitle 、 short 、 collection 、 edition 、 extended 。

creator

Either a string value, or an object with fields role, file-as, and text, or a list of such objects. Valid values for role are MARC relators, but pandoc will attempt to translate the human-readable versions (like “author” and “editor”) to the appropriate marc relators.

contributor

creator と同じ形式。

date

YYYY-MM-DD 形式の文字列 (年 YYYY は必要な場合のみ)。 Pandoc は他の一般的な日時フォーマットを変換しようとします。

lang (古い形式: language)

BCP 47 形式の文字列。これが指定されていない場合、Pandocはローカルの言語をデフォルトとします。

subject

Either a string value, or an object with fields text, authority, and term, or a list of such objects. Valid values for authority are either a reserved authority value (currently AAT, BIC, BISAC, CLC, DDC, CLIL, EuroVoc, MEDTOP, LCSH, NDC, Thema, UDC, and WGS) or an absolute IRI identifying a custom scheme. Valid values for term are defined by the scheme.

description

文字列値。

type

文字列値。

format

文字列値。

relation

文字列値。

coverage

文字列値。

rights

文字列値。

belongs-to-collection

A string value. identifies the name of a collection to which the EPUB Publication belongs.

group-position

The group-position field indicates the numeric position in which the EPUB Publication belongs relative to other works belonging to the same belongs-to-collection field.

cover-image

文字列値（カバー画像へのパス）。

css (古い形式: stylesheet)

文字列値（CSSスタイルシートへのパス）

page-progression-direction

Either ltr or rtl. Specifies the page-progression-direction attribute for the `spine element`_.

ibooks

iBooks 特有のメタデータ。下記のフィールドが有効：

  • version: (文字列)

  • specified-fonts: true|false (既定は false)

  • ipad-orientation-lock: portrait-only|landscape-only

  • iphone-orientation-lock: portrait-only|landscape-only

  • binding: true|false (既定は true)

  • scroll-axis: vertical|horizontal|default

epub:type 属性

For epub3 output, you can mark up the heading that corresponds to an EPUB chapter using the `epub:type attribute`_. For example, to set the attribute to the value prologue, use this markdown:

# My chapter {epub:type=prologue}

次のような結果が得られます：

<body epub:type="frontmatter">
  <section epub:type="prologue">
    <h1>My chapter</h1>

Pandoc は <body epub:type="bodymatter"> を出力します。ただし下記の値のうち frontmatter (訳注: 目次や献辞など、コンテンツ本体の予備的な資料など)もしくは backmatter (訳注: 索引や付録など、文書の後にある補助的な資料)が出力されるケースでは、その値が使用されます。

section 最初の epub:type

body の epub:type

prologue (訳注: 序章)

frontmatter

abstract

frontmatter

acknowledgments (訳注: 謝辞)

frontmatter

copyright-page (訳注: 著作権のページ)

frontmatter

dedication (訳注: 献辞)

frontmatter

credits

frontmatter

keywords

frontmatter

imprint

frontmatter

contributors

frontmatter

other-credits

frontmatter

errata

frontmatter

revision-history

frontmatter

titlepage (訳注: 作品の標題紙・タイトルページ)

frontmatter

halftitlepage

frontmatter

seriespage

frontmatter

foreword (訳注: 前書き)

frontmatter

preface (訳注: 序)

frontmatter

frontispiece

frontmatter

appendix (訳注: 補足情報・付録)

backmatter

colophon (訳注: 奥付)

backmatter

bibliography

backmatter

index

backmatter

リンクされたメディア

通常、Pandoc は生成された EPUB に現れる <img> 、 <audio> 、 <video> または <source> のいずれかから参照されたメディアをダウンロードし、EPUB コンテナに格納しようとします。これにより完全に独立した (self-contained) EPUBを得られます。もしユーザが替わりに外部のメディアリソースへのリンクを望む場合には、生の (raw) HTMLとして source を記述し、src 属性のあるタグに data-external="1" をつけ加えてください。たとえば：

<audio controls="1">
  <source src="https://example.com/music/toccata.mp3"
          data-external="1" type="audio/mpeg">
  </source>
</audio>

If the input format already is HTML then data-external="1" will work as expected for <img> elements. Similarly, for Markdown, external images can be declared with ![img](url){external=1}. Note that this only works for images; the other media elements have no native representation in pandoc’s AST and requires the use of raw HTML.

EPUB styling

By default, pandoc will include some basic styling contained in its epub.css data file. (To see this, use pandoc --print-default-data-file epub.css.) To use a different CSS file, just use the --css command line option. A few inline styles are defined in addition; these are essential for correct formatting of pandoc’s HTML output.

The document-css variable may be set if the more opinionated styling of pandoc’s default HTML templates is desired (and in that case the variables defined in Variables for HTML may be used to fine-tune the style).

Jupyter notebooks

Jupyter notebook を作成するとき、Pandocはノートブック構造を推測します。 code クラスを持つコードブロックはコードセルと見なされ、介在するコンテンツはMarkdownセルと見なされます。Markdownセル中の添付ファイルは、自動的に画像になります。メタデータは、 jupyter メタデータフィールドから取得されます。例えば:

---
title: My notebook
jupyter:
  nbformat: 4
  nbformat_minor: 5
  kernelspec:
     display_name: Python 2
     language: python
     name: python2
  language_info:
     codemirror_mode:
       name: ipython
       version: 2
     file_extension: ".py"
     mimetype: "text/x-python"
     name: "python"
     nbconvert_exporter: "python"
     pygments_lexer: "ipython2"
     version: "2.7.15"
---

# Lorem ipsum

**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
bibendum felis dictum sodales.

``` code
print("hello")
```

## Pyout

``` code
from IPython.display import HTML
HTML("""
<script>
console.log("hello");
</script>
<b>HTML</b>
""")
```

## Image

This image ![image](myimage.png) will be
included as a cell attachment.

If you want to add cell attributes, group cells differently, or add output to code cells, then you need to include divs to indicate the structure. You can use either fenced divs or native divs for this. Here is an example:

:::::: {.cell .markdown}
# Lorem

**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
bibendum felis dictum sodales.
::::::

:::::: {.cell .code execution_count=1}
``` {.python}
print("hello")
```

::: {.output .stream .stdout}
```
hello
```
:::
::::::

:::::: {.cell .code execution_count=2}
``` {.python}
from IPython.display import HTML
HTML("""
<script>
console.log("hello");
</script>
<b>HTML</b>
""")
```

::: {.output .execute_result execution_count=2}
```{=html}
<script>
console.log("hello");
</script>
<b>HTML</b>
hello
```
:::
::::::

If you include raw HTML or TeX in an output cell, use the [raw attribute][Extension: fenced_attribute], as shown in the last cell of the example above. Although pandoc can process “bare” raw HTML and TeX, the result is often interspersed raw elements and normal textual elements, and in an output cell pandoc expects a single, connected raw block. To avoid using raw HTML or TeX except when marked explicitly using raw attributes, we recommend specifying the extensions -raw_html-raw_tex+raw_attribute when translating between Markdown and ipynb notebooks.

Note that options and extensions that affect reading and writing of Markdown will also affect Markdown cells in ipynb notebooks. For example, --wrap=preserve will preserve soft line breaks in Markdown cells; --atx-headers will cause ATX-style headings to be used; and --preserve-tabs will prevent tabs from being turned to spaces.

シンタックスハイライト

Pandocは、言語名を指定された fenced code blocks に対して、言語に応じたシンタックスハイライトを自動的に適用します。シンタックスハイライトには、Haskell ライブラリ skylighting が使用されます。現在のところ、シンタックスハイライトは、 HTML, EPUB , docx, ms, および LaTeX/PDF 出力に適用されます。Pandocが認識する言語名の一覧を見たい場合は、 pandoc --list-highlight-languages を実行してください。

カラースキームは --highlight-style オプションによって選択できます。既定のカラースキームは pygments で、これはPythonライブラリの pygments を真似たものです (ただしPandocの中では、実際の pygments はシンタックスハイライトに利用されません)。ハイライトスタイルの一覧を見るには、 pandoc --list-highlight-styles を実行してください。

既定のハイライトスタイルに満足できない場合には、 --print-highlight-style によってJSON形式の .theme ファイルを出力することで、ハイライトスタイルを変更して --highlight-style の引数として与えることで、カスタマイズが可能です。たとえば、 pygments スタイルのJSONファイルを得るには、次を実行します:

pandoc --print-highlight-style pygments > my.theme

そして my.theme を編集し、次のように利用します:

pandoc --highlight-style my.theme

それでも内蔵のハイライトに満足できない場合や、サポートされていない言語に対するハイライトが必要な場合には、 --syntax-definition オプションを使って KDE-style XML syntax definition file を読み込むことが可能です。自分で独自のファイルを書く前に、KDEの repository of syntax definitions をご覧ください。

シンタックスハイライトを無効にするには、 --no-highlight オプションを使います。

カスタムスタイル

カスタムスタイルは、docx形式およびICML形式で使用することができます。

出力

通常、Pandocの docx 出力およびICML出力において、段落や引用などのテキストブロックに対しては事前に定義されたスタイルの集まりを、インラインテキストに対しては(ほとんどの場合、)既定のインライン修飾(斜体や太字)をそれぞれ使用します。この動作は、特に reference.docx ファイルを用いる場合には、大半の用途でうまくいきます。しかし、テキストブロックに対して独自のスタイルを適用したい場合や、テキストブロックを既存のスタイルセットと一致させたい場合には、Pandocにおいてカスタムスタイルを定義することも可能です。テキストブロックに対しては div を、インラインテキストに対しては span をそれぞれ定義できます。

If you define a div or span with the attribute custom-style, pandoc will apply your specified style to the contained elements (with the exception of elements whose function depends on a style, like headings, code blocks, block quotes, or links). So, for example, using the bracketed_spans syntax,

[Get out]{custom-style="Emphatically"}, he said.

は、「Get out」に文字スタイル Emphatically を適用した docx ファイルを出力します。同様に、 fenced_divs 拡張記法を用いると、

Dickinson starts the poem simply:

::: {custom-style="Poetry"}
| A Bird came down the Walk---
| He did not know I saw---
:::

は、段落スタイル Poetry をその中の2行に適用します。

docx出力を行う場合、reference.docxで設定されていないスタイルは、通常のテキストを継承するスタイルとして定義されて出力されます。reference.docxで定義済みの場合、Pandocはそのスタイルの定義を変更しません。

この機能と pandoc filters を併用することで、すばらしいカスタマイズを実現できます。引用の後に続くすべての段落をインデントしたい場合には、必要なスタイルを適用するフィルタを書けばよいのです。また、すべての斜体を Emphasis 文字スタイルに変換したい場合には (もしかしたら文字色が変わるかもしれません)、斜体となっているすべてのインラインテキストを Emphasis カスタムスタイルの span に変換するフィルタを書けばよいでしょう。

カスタムスタイルを使ってdocxを出力したい時に、特に何らかの拡張機能を有効にする必要はありません。

入力

通常、docx Readerはスタイルの読み込みにおいて、Pandocの要素に直接変換できるもの、または入力文書のスタイルの派生として解釈できるもののみを読み込みます。

docx Reader (-f docx+styles) において `styles extension`_ を有効にすることで、入力文書のスタイルを custom-style class として保持した出力を得られます。段落スタイルは div として解釈され、文字スタイルは span として解釈されます。

例えば、テストディレクトリ中の custom-style-reference.docx を使うことで、次のような異なる出力を得ることが出来ます。

+styles 拡張がない場合:

$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
This is some text.

This is text with an *emphasized* text style. And this is text with a
**strengthened** text style.

> Here is a styled paragraph that inherits from Block Text.

+styles 拡張がある場合:

$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown

::: {custom-style="First Paragraph"}
This is some text.
:::

::: {custom-style="Body Text"}
This is text with an [emphasized]{custom-style="Emphatic"} text style.
And this is text with a [strengthened]{custom-style="Strengthened"}
text style.
:::

::: {custom-style="My Block Style"}
> Here is a styled paragraph that inherits from Block Text.
:::

このようなカスタムスタイルを用いることで、出力文書として docx を作成する場合においても (下記参照)、入力文書 (docx) をリファレンス文書としても同時に利用でき、入力および出力ファイルの両方で同じスタイルが保持されるようになります。

Custom readers and writers

Pandoc can be extended with custom readers and writers written in Lua. (Pandoc includes a Lua interpreter, so Lua need not be installed separately.)

To use a custom reader or writer, simply specify the path to the Lua script in place of the input or output format. For example:

pandoc -t data/sample.lua
pandoc -f my_custom_markup_language.lua -t latex -s

A custom reader is a Lua script that defines one function, Reader, which takes a string as input and returns a Pandoc AST. See the Lua filters documentation for documentation of the functions that are available for creating pandoc AST elements. For parsing, the lpeg parsing library is available by default. To see a sample custom reader:

pandoc --print-default-data-file creole.lua

If you want your custom reader to have access to reader options (e.g. the tab stop setting), you give your Reader function a second options parameter.

A custom writer is a Lua script that defines a function that specifies how to render each element in a Pandoc AST. To see a documented example which you can modify according to your needs:

pandoc --print-default-data-file sample.lua

Note that custom writers have no default template. If you want to use --standalone with a custom writer, you will need to specify a template manually using --template or add a new default template with the name default.NAME_OF_CUSTOM_WRITER.lua to the templates subdirectory of your user data directory (see Templates).

Reproducible builds

Some of the document formats pandoc targets (such as EPUB, docx, and ODT) include build timestamps in the generated document. That means that the files generated on successive builds will differ, even if the source does not. To avoid this, set the SOURCE_DATE_EPOCH environment variable, and the timestamp will be taken from it instead of the current time. SOURCE_DATE_EPOCH should contain an integer unix timestamp (specifying the number of second since midnight UTC January 1, 1970).

Some document formats also include a unique identifier. For EPUB, this can be set explicitly by setting the identifier metadata field (see EPUB Metadata, above).

セキュリティに関する注記

  1. 明示的に作成することを要求するもの以外に、Pandoc 自体はファイルを作成または改変することはありませんが(PDF の作成に使用される一時ファイルを除きます)、フィルタまたはカスタムWriterは、原則としてファイルシステム上でファイルの作成や改変などを行うことができます。フィルタとカスタム Writer を使用する前に、それらを十分注意深く検証してください。

  2. Several input formats (including HTML, Org, and RST) support include directives that allow the contents of a file to be included in the output. An untrusted attacker could use these to view the contents of files on the file system. (Using the --sandbox option can protect against this threat.)

  3. Several output formats (including RTF, FB2, HTML with --self-contained, EPUB, Docx, and ODT) will embed encoded or raw images into the output file. An untrusted attacker could exploit this to view the contents of non-image files on the file system. (Using the --sandbox option can protect against this threat, but will also prevent including images in these formats.)

  4. If your application uses pandoc as a Haskell library (rather than shelling out to the executable), it is possible to use it in a mode that fully isolates pandoc from your file system, by running the pandoc operations in the PandocPure monad. See the document Using the pandoc API for more details. (This corresponds to the use of the --sandbox option on the command line.)

  5. Pandoc’s parsers can exhibit pathological performance on some corner cases. It is wise to put any pandoc operations under a timeout, to avoid DOS attacks that exploit these issues. If you are using the pandoc executable, you can add the command line options +RTS -M512M -RTS (for example) to limit the heap size to 512MB. Note that the commonmark parser (including commonmark_x and gfm) is much less vulnerable to pathological performance than the markdown parser, so it is a better choice when processing untrusted input.

  6. The HTML generated by pandoc is not guaranteed to be safe. If raw_html is enabled for the Markdown input, users can inject arbitrary HTML. Even if raw_html is disabled, users can include dangerous content in URLs and attributes. To be safe, you should run all HTML generated from untrusted user input through an HTML sanitizer.

原文の著者について

Copyright 2006–2022 John MacFarlane (jgm@berkeley.edu). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) For a full list of contributors, see the file AUTHORS.md in the pandoc source code.

1

このルールのポイントは、以下の例のような、イニシャル表記の人名から始まる通常の段落を

B. Russell was an English philosopher.

リスト項目として扱わないということです。

ただし、このルールでは、以下のような段落はリスト項目として扱われてしまいます:

(C) 2007 Joe Smith

このケースでは、バックスラッシュによるエスケープを使ってください:

(C\) 2007 Joe Smith
2

David Wheeler の提案の影響を受けています。

3

この構想は、 Markdown discussion list でこれを提案したMichel Fortinによるものです。

4

To see why laziness is incompatible with relaxing the requirement of a blank line between items, consider the following example:

bar
:    definition
foo
:    definition

Is this a single list item with two definitions of “bar,” the first of which is lazily wrapped, or two list items? To remove the ambiguity we must either disallow lazy wrapping or require a blank line between list items.