Pandoc User’s Guide 日本語版

注釈

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

原著者:

  • John MacFarlane

原著バージョン: 2.11.0.4

更新日: 2020/10/31

翻訳者(アルファベット順):

目次

概要

pandoc [options] [input-file]…

説明

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

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

"Markdown の Pandoc 拡張バージョンには、 tablesdefinition listsmetadata blocksfootnotescitationsmath をはじめ多数の構文を含みます。下記の 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 を参照してください。

複数のファイルが入力された場合、 Pandoc はそれらを解析する前に(それらの間に空白行を入れて)連結します。(ファイルを個別に解析するには --file-scope を使います。)

形式の指定

入出力の形式はオプションを使うことで明確に指定できます。入力形式の指定は -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 を実行することで、サポートされている形式の一覧を得られます。

もし、入力または出力形式が指定されていない場合は、 pandoc はファイル名の拡張子から推測します。例として、

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

By default, pandoc will use LaTeX to create the PDF, which requires that a LaTeX engine be installed (see --pdf-engine below). Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an intermediate format. To do this, specify an output file with a .pdf extension, as before, but add the --pdf-engine option or -t context, -t html, or -t ms to the command line. The tool used to generate the PDF from the intermediate format may be specified using --pdf-engine.

You can control the PDF style using variables, depending on the intermediate format used: see variables for LaTeX, variables for ConTeXt, variables for ``wkhtmltopdf``, variables for ms. When HTML is used as an intermediate format, the output can be styled using --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```_, ```ifxetex```_, ```ifluatex```_, ```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). The use of xelatex or lualatex as the PDF engine requires `fontspec```_. ``lualatex uses `selnolig```_. ``xelatex uses `polyglossia```_ (with ``lang), `xecjk```_, and ```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 は以下の形式が選択できます。

Note that odt, docx, epub, and pdf output will not be directed to stdout unless forced with -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 Default 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

Give verbose debugging output.

--quiet

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

--fail-if-warnings

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

--log=FILE

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

--list-input-formats

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

--list-output-formats

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

--list-extensions[=FORMAT]

List supported extensions for FORMAT, one per line, preceded by a + or - indicating whether it is enabled by default in FORMAT. If FORMAT is not specified, defaults for pandoc’s Markdown are given.

--list-highlight-languages

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

--list-highlight-styles

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

-v, --version

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

-h, --help

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

Readerのオプション

--shift-heading-level-by=NUMBER

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

--base-header-level=NUMBER

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

--strip-empty-paragraphs

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

--indented-code-classes=CLASSES

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

--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 (実行可能なものだけ)

Filters and Lua-filters are applied in the order specified on the command line.

-L SCRIPT, --lua-filter=SCRIPT

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

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

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

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

return {{Str = expand_hello_world}}

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

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

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

-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. Generally, the input will be handled the same as in YAML metadata blocks. 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.

-p, --preserve-tabs

Preserve tabs instead of converting them to spaces. (By default, pandoc converts tabs to spaces before parsing its input.) Note that this will only affect tabs in literal code spans and code blocks. Tabs in regular text are always treated as spaces.

--tab-stop=NUMBER

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

--track-changes=accept|reject|all

MS Word の「変更履歴の記録」機能によって生成された「挿入」、「削除」、および「コメント」の処理方法を指定します。 accept (既定)は全ての「挿入」を挿入し、全ての「削除」を無視します。 reject は全ての「削除」を挿入し、「挿入」は無視します。 acceptreject はどちらも「コメント」は無視します。 all は「挿入」、「削除」、そして「コメント」について、それぞれ insertdeletedcomment-start 、そして comment-end クラスの span で囲んで配置します。作成者と更新日が含まれます。all はスクリプトを書くのに便利です: 例えば、ある特定の校閲者からの、あるいは特定の日付以前の変更のみを受け入れる場合。段落が「挿入」または「削除」された場合、 track-changes=all は影響を受けた段落の改行の前に paragraph-insert / paragraph-deletion クラスの span を挿入します。このオプションは docx Readerにのみ影響します。

--extract-media=DIR

元の文書に含まれている、または元の文書からリンクされている画像やその他のメディアをパス DIR に抽出し、必要に応じて作成し、抽出されたファイルを指定するように文書内の画像参照を調整します。ソース形式がバイナリコンテナ (docx 、 epub 、または odt) の場合、メディアはコンテナから抽出され、元のファイル名が使用されます。それ以外の場合、メディアはファイルシステムから読み取られるかダウンロードされ、コンテンツの SHA1 ハッシュに基づいて新しいファイル名が構築されます。

--abbreviations=FILE

1行に1つの省略形を付けて、カスタム省略形ファイルを指定します。このオプションが指定されていない場合、 pandoc はユーザデータディレクトリからデータファイル abbreviations を読み込むか、またはシステムの既定に戻ります。システムの既定を見るには、 pandoc --print-default-data-file=abbreviations を使用します。 Markdown Reader にだけ、 pandoc はこのリストを作成します。このリストにあるピリオドで終わる文字列の後には、改行なしのスペースが続きます。そのため、ピリオドでは LaTeX のような形式の文末スペースは生成されません。

一般的な Writer のオプション

-s, --standalone

適切なヘッダーとフッター (例えば、フラグメントではなく、スタンドアロンの HTML 、 LaTeX 、 TEI 、または RTF ファイル) を使用して出力を生成します。このオプションは pdfepubepub3fb2docx 、および 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]

Set the template variable KEY to the value VAL when rendering the document in standalone mode. If no VAL is specified, the key will be given the value true.

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

出力形式 FORMAT のために、システム既定のテンプレートを出力します。(利用可能な FORMAT の一覧については -t を参照) ユーザデータディレクトリ内のテンプレートは無視されます。このオプションの出力は -o / --output によってファイルにリダイレクト出力できます。しかしコマンドラインでは -o / --output--print-default-template の前に置く必要があります。

Note that some of the default templates use partials, for example styles.html. To print the partials, use --print-default-data-file: for example, --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

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

--wrap=auto|none|preserve

テキストが出力でどのように折り返されるかを決定します(レンダリングされたバージョンではなくソースコード)。 auto (既定)の場合、 pandoc は --columns (既定では72)で指定された列幅に行を折り返そうとします。 none を指定すると、 pandocはいっさい折り返しません。 preserve を指定すると、 pandoc は元の文書からの折り返しを保護しようとします (つまり、ソースに意味のない改行がある場合、出力にも意味のない改行が含まれます)。現在、自動折り返しは HTML 出力には機能しません。 ipynb 出力では、このオプションはMarkdownセル内のコンテンツの折り返しに対して影響します。

--columns=NUMBER

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

--toc, --table-of-contents

出力文書に自動生成された目次を含めます(あるいは、 latexcontextdocxodtopendocumentrst 、または ms の場合) 。このオプションは -s/--standalone を使わない限り影響がなく、 mandocbook4docbook5jats の出力にも影響がありません。

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

画像やその他のリソースを検索するためのパス (訳注: 以下、リソースパス) のリスト。パスの区切りは : (Linux, UNIX, macOSの場合) もしくは ; (Windowsの場合) で区切ります。 --resource-path が指定されていない場合、既定のリソースパスはカレントディレクトリです。注意: --resource-path を使う場合、カレントディレクトリは他のパスとともに明示的に指定される必要があります。さもなければ検索されません。たとえば --resource-path=.:test はカレントディレクトリと test サブディレクトリを、この順番で検索します。

--resource-path は (a) 画像を埋め込む出力形式 (たとえば docx, pdf もしくは --self-contained 付きの html ) 、もしくは (b) --extract-media を同時に使う場合のみに有効です。

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

外部ファイルに依存しないようなスタンドアロンのHTMLファイルを出力します。 リンクされたスクリプト、スタイルシート、画像、動画といったコンテンツを結合するために data: URIを利用します。暗黙に --standalone を指定します。ブラウザに正しく表示するために、他に外部のファイルやネットへのアクセスを必要としないという意味で、最終的なファイルは「自己完結している」(self-contained)というべきでしょう。

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

脚注(``reference-links``オプションが設定されている場合は参考文献も)が、現在の(トップレベル)ブロックの最後、現在のセクションの最後、文書の最後のいずれに配置されるのかを指定します。デフォルトは``document``です。現在は、このオプションの影響を受けるのは、マークダウンwriterのみとなっています。

--atx-headers

マークダウン出力の際、ATXスタイルの見出しを使用します。既定では、レベル1とレベル2の見出しにはsetextスタイルを使用し、それ以外にはATXの見出しを使用します。(注意: ``gfm``出力の場合ATXの見出しが常に使用されます)。このオプションは、``ipynb``出力のマークダウンセルでも適用されます。

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

スライドの見出しレベルを指定します(beamers5slidyslideous``dzslides``が対象)。このレベルより上の見出しは、スライドショーを節に分割するために使用されます。このレベルより下の見出しは、スライド内の小見出しとなります。スライドレベルの見出しの下に含まれない内容は、スライドショーにも含まれないことに注意してください。既定では、文書の内容に基づいてスライドのレベルを設定します。Structuring the slide show を参照してください。

--section-divs

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

--email-obfuscation=none|javascript|references

HTML文書において mailto: リンクを難読化 (obfuscating) する方法を指定します。 nonemailto: リンクをそのままにします。 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を生成する場合、スタイルシートが必須です。もしこのオプション (もしくはメタデータのフィールドにおける cssstylesheet) が引数なしで指定された場合、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 のいずれかの拡張子) は、これから派生したほとんどのテンプレートと同様に機能するはずです。

PowerPointのテンプレートは、特に、以下の4枚のレイアウトスライドで始まる必要があります:

  1. タイトル スライド

  2. タイトルとコンテンツ

  3. セクション見出し

  4. 2 つのコンテンツ

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

デフォルトの reference.pptx を編集することも可能です: まず pandoc -o custom-reference.pptx --print-default-data-file reference.pptx を実行し、生成された custom-reference.pptx を、MS PowerPointを用いて編集してください (上述したように、Pandocは、最初の4つのスライドレイアウトを参照します)。

--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, 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 or none: pdflatex (other options: xelatex, lualatex, tectonic, latexmk)

  • -t context: context

  • -t html: wkhtmltopdf (other options: prince, weasyprint; 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.

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

epub3docbook4docbook5jatshtml4 および 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.jskatex.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 images of the typeset formulas and an HTML file with links to these images. So, the procedure is:

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

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

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

Exit codes

If pandoc completes successfully, it will return exit code 0. Nonzero exit codes have the following meanings:

Code

Error

3

PandocFailOnWarningError

4

PandocAppError

5

PandocTemplateError

6

PandocOptionError

21

PandocUnknownReaderError

22

PandocUnknownWriterError

23

PandocUnsupportedExtensionError

24

PandocCiteprocError

31

PandocEpubSubdirectoryError

43

PandocPDFError

47

PandocPDFProgramNotFoundError

61

PandocHttpError

62

PandocShouldNeverHappenError

63

PandocSomeError

64

PandocParseError

65

PandocParsecError

66

PandocMakePDFError

67

PandocSyntaxMapError

83

PandocFilterError

91

PandocMacroLoop

92

PandocUTF8DecodingError

93

PandocIpynbDecodingError

97

PandocCouldNotFindDataFileError

99

PandocResourceNotFound

Default files

The --defaults option may be used to specify a package of options. Here is a sample defaults file demonstrating all of the fields that may be used:

from: markdown+emoji
# reader: may be used instead of from:
to: html5
# writer: may be used instead of to:

# leave blank for output to stdout:
output-file:
# leave blank for input from stdin, use [] for no input:
input-files:
- preface.md
- content.md
# or you may use input-file: with a single value

template: letter
standalone: true
self-contained: false

# note that structured variables may be specified:
variables:
  documentclass: book
  classoption:
    - twosides
    - draft

# metadata values specified here are parsed as literal
# string text, not markdown:
metadata:
  author:
  - Sam Smith
  - Julie Liu
metadata-files:
- boilerplate.yaml
# or you may use metadata-file: with a single value

# Note that these take files, not their contents:
include-before-body: []
include-after-body: []
include-in-header: []
resource-path: ["."]

# turn on built-in citation processing.  Note that 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 below).
citeproc: true
csl: ieee
bibliography:
- foobar.bib
- barbaz.json

# 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}`.
filters:
- wordcount.lua
- type: json
  path: foo.lua

file-scope: false

data-dir:

# ERROR, WARNING, or INFO
verbosity: INFO
log-file: log.json

# citeproc, natbib, or biblatex
cite-method: citeproc
# part, chapter, section, or default:
top-level-division: chapter
abbreviations:

pdf-engine: pdflatex
pdf-engine-opts:
- "-shell-escape"
# you may also use pdf-engine-opt: with a single option
# pdf-engine-opt: "-shell-escape"

# auto, preserve, or none
wrap: auto
columns: 78
dpi: 72

extract-media: mediadir

table-of-contents: true
toc-depth: 2
number-sections: false
# a list of offsets at each heading level
number-offset: [0,0,0,0,0,0]
# toc: may also be used instead of table-of-contents:
shift-heading-level-by: 1
section-divs: true
identifier-prefix: foo
title-prefix: ""
strip-empty-paragraphs: true
# lf, crlf, or native
eol: lf
strip-comments: false
indented-code-classes: []
ascii: true
default-image-extension: ".jpg"

# either a style name of a style definition file:
highlight-style: pygments
syntax-definitions:
- c.xml
# or you may use syntax-definition: with a single value
listings: false

reference-doc: myref.docx

# method is plain, webtex, gladtex, mathml, mathjax, katex
# you may specify a url with webtex, mathjax, katex
html-math-method:
  method: mathjax
  url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
# none, references, or javascript
email-obfuscation: javascript

tab-stop: 8
preserve-tabs: true

incremental: false
slide-level: 2

epub-subdirectory: EPUB
epub-metadata: meta.xml
epub-fonts:
- foobar.otf
epub-chapter-level: 1
epub-cover-image: cover.jpg

reference-links: true
# block, section, or document
reference-location: block
atx-headers: false

# accept, reject, or all
track-changes: accept

html-q-tags: false
css:
- site.css

# none, all, or best
ipynb-output: best

# A list of two-element lists
request-headers:
- ["User-Agent", "Mozilla/5.0"]

fail-if-warnings: false
dump-args: false
ignore-args: false
trace: false

Fields that are omitted will just have their regular default values. So a defaults file can be as simple as one line:

verbosity: INFO

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

When multiple defaults are used, their contents will be combined.

Note that, where command-line arguments may be repeated (--metadata-file, --css, --include-in-header, --include-before-body, --include-after-body, --variable, --metadata, --syntax-definition), the values specified on the command line will combine with values specified in the defaults file, rather than replacing them.

テンプレート

-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 を使うことはできます)。

Templates contain variables, which allow for the inclusion of arbitrary information at any point in the file. They may be set at the command line using the -V/--variable option. If a variable is not set, pandoc will look for the key in the document’s metadata, which can be set using either YAML metadata blocks or with the -M/--metadata option. In addition, some variables are given default values by pandoc. See Variables below for a list of variables used in pandoc’s default templates.

If you use custom templates, you may need to revise them as pandoc changes. We recommend tracking the changes in the default templates, and modifying your custom templates accordingly. An easy way to do this is to fork the pandoc-templates repository and merge in changes after each pandoc release.

Template syntax

Comments

Anything between the sequence $-- and the end of the line will be treated as a comment and omitted from the output.

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

subtitle

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

abstract

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

keywords

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

subject

文書の主題・テーマ (ODT, PDF, docx, pptx のメタデータ)

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.

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.

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

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

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.

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)

beamerarticle

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

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

paper size, e.g. letter, a4

secnumdepth

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

フォント
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 の文書クラスのうちひとつ (scrartclscrbook など) を 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-htmlheader-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

フォントファミリー (例: TP など)

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, 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 セクションで網羅されます (commonmarkgfm については Markdown variants も参照) 。次に説明する拡張は、他の形式でも利用できるものを含みます。

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

タイポグラフィ

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

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

入力フォーマット

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

出力フォーマット

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 のように生の htmltex を利用できない形式へ変換しようとする際には、よい出力結果を得るために raw_htmlraw_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形式から変換する場合、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.

Pandoc’s Markdown citation syntax の一部を org 形式での入力でも可能にします。

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

Pandoc’s Markdown

Pandocは、拡張と少しの改訂が加えられたJohn Gruberの Markdown 文法を解釈します。ここでは、John GruberのMarkdown文法と、標準Markdown文法との違いについて説明します。特に注意が無い限り、 markdown フォーマットの代わりに markdown_strict フォーマットを用いることで、標準Markdown文法に従った解釈に変更できます。拡張機能を有効もしくは無効にすることで、Pandocの動作をより詳細に設定できます。以下では、Markdown形式における拡張機能について説明します。他の形式でも機能する拡張機能に関しては、上述の Extensions を参照してください。

哲学

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

標準Markdown文法では設けられていない制約ですが、Pandocでは、見出し行の前に空行が挿入される必要があります (ただし、文書のはじめの1行だけは例外です)。なぜならば、行頭に誤って # 記号を置くことがよくあるためです (行の折返し設定をしているエディタでも同様のことが起こるかもしれません)。以下の例について考えてみましょう:

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

標準Markdown記法では設けられていない制約ですが、Pandocでは、引用の前に空行が挿入される必要があります (ただし、文章のはじめの1行だけは例外です)。なぜならば、誤って行頭に > 記号を置くことがよくあるためです(行の折返し設定をしているエディタでも同様のことが起こるかもしれません)。そのため、 markdown_strict 形式が用いられていない限り、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

この文法は、 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.

順序付きリスト

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

標準Markdownでは、順序付きリストの行頭に10進の数値と,それに続く1つのピリオドおよび1つの空白を置きます。数値そのものの値は無視されるため、以下の順序付きリストは

1.  one
2.  two
3.  three

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

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

標準Markdownとは異なり、Pandocは、大文字もしくは小文字のアルファベット、およびローマ数字といった順序記号を用いて順序付きリストを作成することも可能です。この場合、これらの順序記号を括弧で囲むか、順序記号の直後に閉じ括弧もしくはピリオドを置いてください。これらの順序記号とリスト項目となるテキストは、少なくとも1つのスペースで区切られる必要があります。ただし、順序記号として大文字の英字を用いる場合は、2つ以上のスペースで区切ってください。 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つのスペースを置いてインデントしても構いません。

用語は、複数の定義を持つことが可能で、各定義は、さらに複数のブロック要素(段落やコードブロック、リストなど)を持つことが可能です。定義内に複数のブロック要素を含める場合は、それらのブロックは4つの空白もしくは1つのタブでインデントされる必要があります。定義の本体(最初の行から行頭のコロンもしくはチルダ記号を除いたものも含む)は、4つの空白でインデントされる必要があります。しかし、これ以外のMarkdownリストと同様に、段落などのブロック要素の開始地点を除き、インデントを省いた「怠惰な(lazily)」書き方も可能です:

Term 1

:   Definition
with lazy continuation.

    Second paragraph of the definition.

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

Term 1
  ~ Definition 1

Term 2
  ~ Definition 2a
  ~ Definition 2b

定義リストの項目の間には空行が必要であることに注意してください。(この要件を緩和したい場合は、 compact_definition_lists を有効にしてください。ただし、 compact_definition_lists を有効にすると、インデントを省く「怠惰(lazy)」な行折り返しは使用できなくなります。詳しくは、下記の Non-pandoc extensions を参照してください。)

順序付き用例リスト

拡張: 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 a pipe table contains a row whose Markdown content is wider 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, True15 は、フィールド名として使用できません) 。

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.

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

テンプレート変数は、メタデータから自動的に設定されます。そのため、たとえば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}}
  ```

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

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

*\*hello\**

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

<em>*hello*</em>

には変換されません。

<strong>hello</strong>

このルールは、Markdownの標準ルールと比較すると簡単に覚えられます。標準Markdownでは、以下の記号のみがバックスラッシュによるエスケープが可能です:

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

(ただし、 markdown_strict 形式が指定されているとき、標準Markdownのルールが適用されます。)

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}

スモールキャピタル

スモールキャピタルを適用したい場合は、 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.)

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構文にレンダリングされることに注意してください。

標準Markdownでは、HTML"ブロック"を文書中に置くことができます。HTMLブロックとは、空白行で周囲のテキストから分割されている必要があります。また、開始タグと終了タグで正しく囲まれ、すべて左寄せで書かれている必要があります。HTMLブロック内では、すべての要素がMarkdownではなくHTMLとして解釈されます。そのため(たとえば)、 HTMLブロック内の * は、強調記号として機能しません。

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として解釈した変換を行わないでしょう。

ただし、このルールにはひとつだけ例外があります。 <script> および <style> タグ内のテキストは、Markdownとして解釈されません。

標準Markdownを発展させたこの方法によって、HTMLブロック要素とMarkdownとを混在させることが容易になります。たとえば、Markdownとして解釈されたくないテキストを、div タグ内に置くことが可能になります。

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

Markdown citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of ‘@’ + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. The citation key must begin with a letter, digit, or _, and may contain alphanumerics, _, and internal punctuation characters (:.#$%&-+?<>~/). Here are some examples:

Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].

Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].

Blah blah [@smith04; @doe99].

pandoc detects locator terms 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.

pandoc will use heuristics to distinguish the locator from the suffix. In complex cases, the locator can be enclosed in curly braces:

[@smith{ii, A, D-Z}, with a suffix]
[@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]

マイナス記号 (-) を @ 記号の前に置くことで、著者名が表示されなくなります。この記法は、文中ですでに著者名について言及しているときに便利です:

Smith says blah [-@smith04].

引用文献を、括弧書きでなく文中の主語として用いたい場合は、以下のような書き方ができます:

@smith04 says blah.

@smith04 [p. 33] says blah.

非Pandoc拡張

以下に示したMarkdown構文の拡張機能は、デフォルトのPandocでは有効になっていませんが、フォーマット名に +EXTENSION を追加することで、それぞれの拡張機能を有効にできます。ここで、 EXTENSION は拡張機能の名前を指します。たとえば、 markdown+hard_line_breaks は、 hard_line_breaks 拡張を含むMarkdownです。

Allows attributes to be attached to any inline or block-level element. 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.

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

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

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

pandoc can also be used to produce CSL JSON bibliography from BibTeX, BibLaTeX, or markdown YAML:

pandoc chem.bib -s -f biblatex -t csljson
pandoc chem.yaml -s -f markdown -t csljson

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

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.

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

If true, citations will be hyperlinked to the corresponding bibliography entries (for author-date and numerical styles only).

lang

The lang field will affect how the style is localized, for example in the translation of labels and the use of quotation marks. (For backwards compatibility, locale may be used instead of lang, but this use is deprecated.)

notes-after-punctuation

If true (the default), pandoc will put footnote 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.

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

ここで FORMATs5slidyslideousdzslides または 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つの文書は、次のルールによっていくつかのスライドに分割されます:

  • 水平線は、常に新しいスライドを開始する。

  • スライドレベルと同じレベルを持つ見出しは、常に新しいスライドを開始する。

  • スライドレベルよりも 下位の (訳注: レベルを表す数字が大きい) 見出しは、スライドの 内部に 見出しを作る。

  • スライドレベルよりも 上位の (訳注: レベルを表す数字が小さい) 見出しは、セクションタイトルのみを表示する「タイトルスライド」を作る。これにより、一つのスライドショーを複数のセクションに分けて発表することが容易になる。この場合、見出しの直下に置かれた非スライド要素は、(HTML スライドショーの場合)タイトルスライドに含まれるか、(beamerの場合)タイトルスライドと同じタイトルを持つスライドが作られ、そのスライドに含まれるかされます。

  • タイトルページは、(もし存在すれば) 文書のタイトルブロックから自動的に生成される (beamer の場合、デフォルトテンプレートのいくつかの行をコメントアウトすることで無効にできる)。

これらのルールは、さまざまなスライドショーのスタイルに対応するために設計されています。スライドをセクションやサブセクションに分ける必要がなければ、単にレベル 1 の見出しをすべてのスライドで使用してもかまいません (この場合、レベル 1 がスライドレベルとなります)。一方、スライドショーをいくつかのセクションに分けたい場合には、上記の例のように構成してもよいでしょう。

補足: reveal.js スライドショーでは、スライドレベルが 2 の場合は、2次元レイアウトとして出力されます。レベル 1 の見出しは水平方向に、レベル 2 の見出しは垂直方向にスライドショーを構成します。reveal.jsでは、これ以上セクションレベルを深く入れ子 (nesting) にすることは推奨されません。

インクリメンタルリスト

既定では、スライドショーはリストを「すべて一気に (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

:::

incrementalnonincremental は、一時的に (on a per-case basis) インクリメンタルリストを設定する方法として推奨されています。一方で、次のような古い方法もサポートしています: 引用中のリストは、文書の既定動作に反します (これは -i オプションがなくてもインクリメンタルに表示されますし、 -i を付けても一気に表示されます)

> - Eat spaghetti
> - Drink wine

いずれの方法でも、1つの文書の中にインクリメンタルリストとそうでないリストを混在できます。

Note: Neither the -i/--incremental option nor any of the methods described here currently works for PowerPoint output.

ポーズの挿入

半角スペースで区切られた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 オプションを用いて、 themecolorthemefontthemeinnertheme 、 および 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, the only heading attribute that affects slides is the allowframebreaks class, which sets the allowframebreaks option, causing multiple slides to be created if the content overfills the frame. This is recommended especially for bibliographies:

# References {.allowframebreaks}

発表者ノート

発表者ノート (speaker notes) は、reveal.jsとPowerPoint (pptx) 出力で利用できます。次のようにMarkdown文書の中でノートを追加できます:

::: 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, t, environment, label, plain, shrink, standout, noframenumbering.

スライドの背景 (reveal.js / Beamer)

背景画像は、自己完結したreveal.jsスライドショーと、Beamerスライドショーに追加できます。

同じ背景画像をすべてのスライドに適用するには、設定オプション background-image をYAMLメタデータブロックまたはコマンドラインのテンプレート変数に指定します。(Beamerで利用できるのはこのオプションのみです。この節における残りの説明は、reveal.jsスライドショーに関するものです)

reveal.jsに関しては、代わりにreveal.js本来のオプションである parallaxBackgroundImage を利用できます。同様に parallaxBackgroundHorizontalparallaxBackgroundVertical も設定できます。これらを有効にするには、必ず parallaxBackgroundSize を設定する必要があります。(訳注: reveal.jsのParallax Background (パララックス背景) という機能。視差効果が生まれるように、スライドが進むごとに少しずつ背景画像が動いていく。詳細: GitHub hakimel/reveal.js )

To set an image for a particular reveal.js slide, add {data-background-image="/path/to/image"} to the first slide-level heading on the slide (which may even be empty).

reveal.jsのoverviewモード (訳注: 複数スライドを一覧できるモード) においては、parallaxBackgroundImageは最初のスライドのものを表示します。

その他のreveal.js用背景設定のうち、個別のスライドに対して適用できるものは次のとおりです: data-background-sizedata-background-repeatdata-background-colordata-transitiondata-transition-speed

To add a background image to the automatically generated title slide, use the title-slide-attributes variable in the YAML metadata block. It must contain a map of attribute names and values.

詳細は、 reveal.js documentation を参照してください。

reveal.jsスライドショーをつくる例を示します:

---
title: My Slideshow
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.

## {data-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-10GTIN-13UPCISMN-10DOILCCNGTIN-14ISBN-13Legal deposit numberURNOCLCISMN-13ISBN-AJPOLCC

title

文字列値、またはフィールド file-as および type のオブジェクト、またはこのようなオブジェクトのリスト。type の有効な値は mainsubtitleshortcollectioneditionextended

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

文字列値、またはその値のリスト。

description

文字列値。

type

文字列値。

format

文字列値。

relation

文字列値。

coverage

文字列値。

rights

文字列値。

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

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>

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) をリファレンス文書としても同時に利用でき、入力および出力ファイルの両方で同じスタイルが保持されるようになります。

カスタム Writer

Pandoc can be extended with custom writers written in Lua. (Pandoc includes a Lua interpreter, so Lua need not be installed separately.)

To use a custom writer, simply specify the path to the Lua script in place of the output format. For example:

pandoc -t data/sample.lua

Creating a custom writer requires writing a Lua function for each possible element in a pandoc document. To get a documented example which you can modify according to your needs, do

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

セキュリティに関する注記

Pandoc を使用して Web アプリケーションのユーザー提供コンテンツを変換する場合には、次の点に注意してください:

  1. 明示的に作成することを要求するもの以外に、Pandoc 自体はファイルを作成または改変することはありませんが(PDF の作成に使用される一時ファイルを除きます)、フィルタまたはカスタムWriterは、原則としてファイルシステム上でファイルの作成や改変などを行うことができます。フィルタとカスタム Writer を使用する前に、それらを十分注意深く検証してください。

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

  3. Pandocのパーサは、めったに起こらないいくつかの厄介なケースにおいて、病的な振る舞いをすることがあります。セキュリティ上の穴を悪用するDOS攻撃を防ぐために、Pandocにおけるあらゆる操作は一定時間内に終わらせる方がよいでしょう。実行ファイルのPandocを利用する場合は、コマンドラインオプションとしてたとえば +RTS -M512M -RTS (ヒープサイズを512MBに制限する)といったものを指定できます。

  4. 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 attributes for headings, spans, and code blocks. To be safe, you should run all the generated HTML through an HTML sanitizer.

原文の著者について

Copyright 2006–2020 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.