Pandocユーザーズガイド 日本語版 [2.7.2]

注釈

現在の翻訳は プレリリース版 です。不完全な翻訳を含んでいます。

原著: John MacFarlane

原著バージョン: 2.7.2

更新日: 2020/03/31

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

目次

概要

pandoc [options] [input-file]…

説明

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

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

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

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

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

pandoc の使い方

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

pandoc -o output.html input.txt

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

pandoc -s -o output.html input.txt

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

複数のファイルが入力された場合、 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

既定では、Pandoc は PDF を生成するために LaTeX を利用しようとします。その際、 LaTeX エンジンがインストールされている必要があります (下記の --pdf-engine を参照してください)

あるいは、 Pandoc は ConTeXt 、 `` pdfroff`` 、または次の HTML / CSS からの PDF 変換エンジンのいずれかを使用して PDF を作成することができます。 `wkhtmltopdf```_ 、 ```weasyprint```_ または ```prince```_ 。これを行うには、同じように拡張子 ``.pdf を付けて出力ファイルを指定しますが、 `` --pdf-engine``オプションまたは `` -t context`` 、 -t html を追加、もしくは、コマンドラインに -t ms を付けます（ `` -t html`` のデフォルトは `` --pdf-engine = wkhtmltopdf`` です）。

PDF 出力は、 variables for LaTeX (LaTeX が使用されている場合)と variables for ConTeXt (ConTeXt が使用されている場合) 、 variables for ``wkhtmltopdf`` (HTML/CSSからPDFに変換する場合、 --css も出力に影響) を使うことで制御できます。

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

LaTeX を使用する場合には、以下のパッケージを事前にインストールしておく必要があります (これらは TeX Live の最近のすべてのバージョンに含まれています):

Webからの読み込み

入力ファイルの代わりに絶対URIを指定しても良い。この場合、PandocはHTTPを使用して内容を取得する。

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

URL から文書を要求するときに、カスタム User-Agent 文字列または他のヘッダーを指定することができます :

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

オプション

一般的なオプション

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

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

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

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

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

odt、 docx、 epub の出力は -o - で強制しない限り標準出力 stdout に出力されない点に注意してください。

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

--bash-completion

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

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

冗長（verbose）なデバッグの出力を与えます。現在これはPDF出力にのみ影響を与えます。

--quiet

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

--fail-if-warnings

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

--log=FILE

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

--list-input-formats

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

--list-output-formats

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

--list-extensions[=FORMAT]

サポートしている拡張を*FORMAT* の規定で有効化されているかどうかで``+`` or - を前につけて１行に１つずつ表示します。FORMAT が指定されていない場合、Pandoc の Markdown が既定で与えられます。

--list-highlight-languages

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

--list-highlight-styles

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

-v, --version

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

-h, --help

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

Readerのオプション

--base-header-level=NUMBER

ヘッダのベースレベルを指定します（デフォルトは1）。

--strip-empty-paragraphs

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

--indented-code-classes=CLASSES

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

--default-image-extension=EXTENSION

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

--file-scope

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

-F PROGRAM, --filter=PROGRAM

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

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

は以下と等しい

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

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

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

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

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

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

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

フィルターとLuaフィルターはコマンドライン上で指定された順に適用されます。

--lua-filter=SCRIPT

JSON フィルタと同様に文書を変換(--filter を参照)しますが、 Pandoc に内蔵された lua フィルタリングシステムを使用してください。与えられた lua スクリプトは、適用される順に並べられた lua フィルタリストが返されることを期待されています。各 lua フィルタには、フィルタ関数を適用する AST 要素名でインデックスされた要素変換関数を含めなければなりません。

Pandoc の Lua モジュールは要素の作成のためのヘルパー関数を供給します。これは常にスクリプトのLua環境中にロードされます。

以下はマクロ展開のためのLuaスクリプト例です。

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

return {{Str = expand_hello_world}}

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

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

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

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

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

--metadata-file=FILE

与えられたYAML（またはJSON）ファイルからメタデータを読みます。このオプションはすべての入力形式で使うことが出来ますが、YAMLファイル中の文字列値 (スカラー) は常にMarkdownとして解釈されます。一般的に、入力は YAML metadata blocks と同様に扱われます。メタデータの値はドキュメント中で指定、または -M オプションを使用することで、オプションで指定された値で上書きできます。

-p, --preserve-tabs

タブをスペースに変換する（デフォルトの挙動）せずにそのまま残します。リテラルコードSPANとコードブロック中のタブにのみ影響を与えることに注意が必要です。通常のテキスト中のタブはスペースとして扱われます。

--tab-stop=NUMBER

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

--track-changes=accept|reject|all

MS Word の「変更履歴の記録」機能によって生成された「挿入」、「削除」、および「コメント」の処理方法を指定します。 accept (既定)は全ての「挿入」を挿入し、全ての「削除」を無視します。 reject は全ての「削除」を挿入し、「挿入」は無視します。 accept と reject はどちらも「コメント」は無視します。 all は「挿入」、「削除」、そして「コメント」について、それぞれ insert 、 deleted 、comment-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 ファイル) を使用して出力を生成します。このオプションは pdf 、 epub 、 epub3 、 fb2 、 docx 、および odt 出力に対して自動的に設定されます。native 出力の場合、このオプションはメタデータを含めます。それ以外の場合、メタデータは抑制されます。

--template=FILE|URL

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

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

文書をスタンドアロンモードでレンダリングするときは、テンプレート変数 KEY を値 VAL に設定します。 pandoc は既定のテンプレートで使用される変数を自動的に設定するので、これは一般的に --template オプションでカスタムテンプレートを指定するために使われる場合にのみ役に立ちます。 VAL が指定されていない場合、キーには値 true が設定されます。

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

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

--print-default-data-file=FILE

システム既定のデータファイルを出力します。ユーザデータディレクトリの中のファイルは無視されます。このオプションの出力は -o / --output``によってファイルにリダイレクト出力できます。しかしコマンドラインでは ``-o / --output は --print-default-data-file の前に置く必要があります。

--eol=crlf|lf|native

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

--dpi=NUMBER

ピクセルからインチ/センチメートルへの変換、および逆変換のためにdpi 値(ドット/インチ)を指定します。既定は 96 dpi です。技術的には、正しい用語はppi (ピクセル数/インチ)です。

--wrap=auto|none|preserve

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

--columns=NUMBER

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

--toc, --table-of-contents

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

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

KDE XML syntax definitionファイルを指定し、マークされたコードブロックに対して適切にシンタックスハイライトを適用します。新しい言語をサポートしたり、既存の言語に対して別のシンタックス定義を与えたりできます。

-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://... に設定する必要もあります。

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

--self-contained

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

--html-q-tags

HTMLで <q> タグを引用に利用します。

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

LaTex、ConTeXt、DocBook、TEI出力において、トップレベルの見出しを指定した単位として扱います。順序は、部(part)、章(chapter)、節(section)の順となります。すべての見出しは、トップレベルの見出しが指定したレベルとなるように遷移します。既定の挙動では、経験則によって次のように単位が決定されます。他の条件が適用されない場合、section``が選択されます。LaTeXの文書クラスが``report、book、memoir に設定された場合は (article オプションが設定されない場合)、暗黙に``chapter``が設定されます。出力形式が``beamer`` の場合、chapter、part``を設定すると、トップレベルの見出しはpart{..}``となり、レベル2の見出しは既定のままになります。

-N, --number-sections

LaTeX、ConTeXt、HTML、EPUB出力の節見出しに数字をつけます。既定では、節は数字なしとなります。unnumbered``クラスを設定した節は、--number-sections`` が指定されていても数字なしとなります。

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

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

--section-divs

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

--email-obfuscation=none|javascript|references

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

--id-prefix=STRING

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

-T STRING, --title-prefix=STRING

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

-c URL, --css=URL

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

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

--reference-doc=FILE

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

Docx

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

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

段落スタイル:

  • Normal (標準)

  • Body Text (本文)

  • First Paragraph

  • Compact

  • Title (表題)

  • Subtitle (副題)

  • Author

  • Date

  • Abstract

  • Bibliography

  • Heading 1 (見出し1)

  • Heading 2 (見出し2)

  • Heading 3 (見出し3)

  • Heading 4 (見出し4)

  • Heading 5 (見出し5)

  • Heading 6 (見出し6)

  • Heading 7 (見出し7)

  • Heading 8 (見出し8)

  • Heading 9 (見出し9)

  • Block Text (ブロック)

  • Footnote Text

  • Definition Term

  • Definition

  • Caption

  • Table Caption

  • Image Caption

  • Figure

  • Captioned Figure

  • TOC Heading

文字スタイル:

  • Default Paragraph Font

  • Body Text Char

  • Verbatim Char

  • Footnote Reference

  • Hyperlink (ハイパーリンク)

表スタイル:

  • 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

PDFを生成する際に、LaTeXエンジンを指定します。指定可能な値は、 pdflatex , lualatex , xelatex , latexmk , tectonic , wkhtmltopdf , weasyprint , prince , context , および pdfroff です。既定値は `` pdflatex`` です。指定したLaTeXエンジンがPATHにない場合、そのエンジンのフルパスを指定することもできます。

--pdf-engine-opt=STRING

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

引用文献の生成

--bibliography=FILE

文書中のメタデータ bibliography を FILE で上書きし、 pandoc-citeproc を用いて引用文献を処理します (これは --metadata bibliography=FILE --filter pandoc-citeproc と等価です)。 `` --natbib`` もしくは `` --biblatex`` が指定されている場合、 pandoc-citeproc が使用されず、 `` --metadata bibliography = FILE`` という設定と等価になります。この引数が複数回指定された場合、それぞれの FILE が引用文献に追加されます。

--csl=FILE

文書中のメタデータ csl を*FILE* で上書きします (これは --metadata csl=FILE と等価です)。このオプションは、 pandoc-citeproc のみに影響します。

--citation-abbreviations=FILE

文書中のメタデータ citation-abbreviations を*FILE* で上書きします (これは --metadata citation-abbreviations=FILE と等価です)。このオプションは、 pandoc-citeproc のみに影響します。

--natbib

LaTeX出力の際、 `natbib```_ を引用に利用します。このオプションは、 ```bibtex```_ で処理するLaTeXファイルを生成するために用いることを想定しており、 ``pandoc-citeproc フィルタやPDF出力とともに用いるものではありません。

--biblatex

LaTeX出力の際、 `biblatex```_ を引用に利用します。このオプションは、 ```bibtex```_ もしくは ```biber```_ で処理するLaTeXファイルを生成するために用いることを想定しており、 ``pandoc-citeproc フィルタやPDF出力とともに用いるものではありません。

HTMLにおける数式の生成

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

--mathjax[=URL]

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

--mathml

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

--webtex[=URL]

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

--katex[=URL]

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

--gladtex

Enclose TeX math in <eq> tags in HTML output. The resulting HTML can then be processed by GladTeX to produce 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

テンプレート

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

テンプレートの中には 変数 (variables) があります。これにより、任意の情報をファイル中のどの箇所にも含められます。変数はコマンドライン上で -V/--variable オプションを使うことで指定できます。変数が指定されていない場合、Pandocは文書のメタデータからキーを探します (訳注: Pandocはメタデータとして定義されたキーも、テンプレートの変数として扱います)。メタデータは YAML metadata blocks または -M/--metadata オプションによって指定できます。

メタデータに関する変数

title, author, date (訳注: タイトル、著者名、日付)

これらは文書を識別するための基本的な側面 (basic aspects) を提供します。LaTeX または ConTeXt をPDFエンジンに用いた場合は、その出力PDFのメタデータに含まれます。これらの変数は pandoc title block (複数の著者名を設定可) またはYAMLメタデータブロックを通じて設定できます:

---
author:
- Aristotle
- Peter Abelard
...
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 のメタデータ)

これらに加えて、任意のルートレベル (root-level) の文字列メタデータのうち、ODT, docx もしくは pptx のメタデータに含まれないものは、 カスタムプロパティ として追加されます。YAMLメタデータレベルの例を示します:

---
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) のみが完全にサポートします。

HTMLスライド用の変数

次に示す変数は producing slide shows with pandoc で説明されるようなHTML出力に影響します。すべての reveal.js configuration options が利用できます。

revealjs-url

reveal.js文書のベースURL (既定: reveal.js)

s5-url

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

slidy-url

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

slideous-url

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

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のテーマ指定

themeoptions

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

titlegraphic

タイトルスライドの画像

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
...
indent [boolean]

インデントに関する文書クラスの設定 (設定がない場合、Pandoc既定のLaTeXテンプレートはパラグラフ間のインデントと空白を削除します)

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 の文書クラスのうちひとつ (scrartcl や scrbook など) を documentclass に指定してください。(訳注: `BXjscls`_ や `LuaTeX-ja`_ の文書クラスを用いている場合は、それぞれのマニュアルに書かれているフォントサイズが利用できます)

mainfont, sansfont, monofont, mathfont, CJKmainfont

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

mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions, CJKoptions

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

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

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

前付 (front matter)

lof, lot [boolean]

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

thanks

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

toc [boolean]

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

toc-depth

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

BibLaTeXによる参考文献リスト

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

biblatexoptions

BibLaTeX用のオプションリスト

biblio-style

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

biblio-title

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

bibliography

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

natbiboptions

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

ConTeXt用の変数

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

fontsize

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

headertext, footertext

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

indenting

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

interlinespace

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

layout

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

linkcolor, contrastcolor

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

linkstyle

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

lof, lot [boolean]

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

mainfont, sansfont, monofont, mathfont

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

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

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

pagenumbering

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

papersize

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

pdfa

プリアンブルに対して、PDF/A-1b:2005 の生成に必要なセットアップを追加。PDF/Aを正しく生成するためには、ICCカラープロファイルが必須であり、コンテンツおよびすべての付属ファイル (画像など) も規格に準拠する必要があります。ICCプロファイルは ConTeXt ICC Profiles から得られます。詳細は ConTeXt PDFA を参照。

toc [boolean]

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

whitespace

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

wkhtmltopdf 用の変数

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

footer-html と header-html

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

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

用紙の余白を設定する

papersize

用紙のサイズを設定する

manページ用の変数

adjusting

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

footer

manページにおけるフッタ

header

manページにおけるヘッダ

hyphenate

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

section

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

roff ms用の変数

fontfamily

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

indent [boolean]

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

lineheight

行の高さ (例: 12p)

pointsize

文字サイズ (例: 10p)

Structural variables

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 は標準出力の場合に - となります。

toc [boolean]

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

toc-title

目次のタイトル (EPUB, opendocument, odt, docx, pptx, beamer, LaTeXでのみ働きます)

テンプレートで変数を使う

変数名に使用できる文字は、英数字、 - (ハイフン)、および _ (アンダースコア)であり、変数名は、一文字目が英字で始まる文字列である必要があります。 $ 記号によって囲まれた変数名は、その値で置換されます。例えば、 $title$ は、

<title>$title$</title>

文書のタイトルで置換されます。

リテラル $ をテンプレートで使用したい場合は、 $$ を使ってください。

テンプレートは、条件分岐を含めることができます。条件分岐の構文は以下のとおりです:

$if(variable)$
X
$else$
Y
$endif$

この例の場合、 variable が truthy な値の場合、テンプレートは X をインクルードし、そうでない場合は Y をインクルードします。truthy な値とは、以下のいずれかです:

  • 空白文字のみからなる文字列以外のあらゆる文字列

  • 最初の値が truthy な空でない配列

  • (ゼロを含む) すべての数値

  • すべてのオブジェクト

  • the boolean true (to specify the boolean true value using YAML metadata or the --metadata flag, use true, True, or TRUE; with the --variable flag, simply omit a value for the variable, e.g. --variable draft).

X and Y are placeholders for any valid template text, and may include interpolated variables or other conditionals. The $else$ section may be omitted.

When variables can have multiple values (for example, author in a multi-author document), you can use the $for$ keyword:

$for(author)$
<meta name="author" content="$author$" />
$endfor$

You can optionally specify a separator to be used between consecutive items:

$for(author)$$author$$sep$, $endfor$

Note that the separator needs to be specified immediately before the $endfor keyword.

A dot can be used to select a field of a variable that takes an object as its value. So, for example:

$author.name$ ($author.affiliation$)

The value of a variable will be indented to the same level as the variable.

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.

テンプレートでは、コメントが使用できます。 $-- から始まるあらゆる行は、コメントとして処理されて無視されます。

拡張

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

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

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

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

タイポグラフィ

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

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

入力フォーマット

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

出力フォーマット

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文字にします。すなわち、アクセント付きラテン文字からアクセントを取り除き、また、非ラテン文字も取り除かれます。

auto_identifiers によって識別子を生成するアルゴリズムを、Githubで用いられているアルゴリズムに変更します。すなわち、空白文字をハイフン (-) に変換し、大文字を小文字に変換し、- と _ 以外の記号文字を取り除きます。

数式の入力

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

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

生の HTML/TeX

以下の拡張について (特にMarkdownの入出力にどのように影響するのかについて) は、 Pandoc's Markdown の対応するセクションでも詳しく説明されています。

HTMLから変換する場合、PandocのASTで表現できない要素を、生のHTMLとして構文解析します。HTML形式のファイルを入力する際、デフォルトではこれは無効になっています。

生の LaTeX、 TeX、ConTeXt を文書に含めることを許します。

この拡張は下記の形式で有効/無効に出来ます（ ``markdown``形式に加えて ）

入力フォーマット

latex, org, textile, html (LaTeX環境 \ref, \eqref のみ), ipynb

出力フォーマット

textile, commonmark

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

HTMLが入力される際、この拡張機能はデフォルトで有効です。これにより、 div はPandocのネイティブな要素として解析されます ( -f html-native_divs+raw_html オプションを使用して、生のHTMLとして div を解析することも可能です)。

HTMLをMarkdownへ変換するとき、たとえば全ての div と span を取り除きたければこのようにします:

pandoc -f html-native_divs-native_spans -t markdown

上記の native_divs と類似の拡張です。

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

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

入力フォーマット

docx

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

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 と互換性があります。)

この文法は、クラスとキー/値の属性をつけることができますが、Pandoc Writerは必ずしも全ての属性を用いるわけではないことに注意してください。識別子、クラス、キー/値の属性は、HTMLおよびEPUBやslidyなどHTMLベースの形式において用いられます。Latex、ConTeXt、Textile、およびAsciiDocのWriterは、識別子をラベルとアンカー文字列に用います。

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

# My heading {-}

は、以下と等価です

# My heading {.unnumbered}
拡張: 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.

コンパクトリスト(compact list)とルーズリスト(loose list)

Pandocは、リストに関係する一部のエッジケースで、 Markdown.pl とは異なる動作をします。 以下のソースについて考えてみます:

+   First
+   Second:
    -   Fee
    -   Fie
    -   Foe

+   Third

Pandoc transforms this into a “compact list” (with no <p> tags around “First”, “Second”, or “Third”), while Markdown puts <p> tags around “Second” and “Third” (but not “First”), because of the blank space around “Third”. Pandoc follows a simple rule: if the text is followed by a blank line, it is treated as a paragraph. Since “Second” is followed by a list, and not a blank line, it isn’t treated as a paragraph. The fact that the list is followed by a blank line is irrelevant. (Note: Pandoc works this way even when the markdown_strict format is specified. This behavior is consistent with the official Markdown syntax description, even though it is different from that of Markdown.pl.)

リストの終わらせ方

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

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

複数の = からなる行が、見出しと表の本体とを分割します。見出しを省略する場合は、 = からなる行は必要ありません。グリッドテーブルのセルには、任意の要素をいれることができます(複数行からなる段落、コードブロック、リストなど)。セルの結合には対応していません。グリッドテーブルは、 Emacs table mode を使用することで、簡単に作成できます。

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

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

パイプテーブルのセルでは、段落やリストなどのブロック要素を置くことはできず、文字列が複数行にまたがることもできません。パイプテーブルのどこかの行が、全列幅よりも横幅の広いコンテンツを含んでいる場合 (--columns を参照してください)、そのパイプテーブルは、テキストが収まる全横幅を占有します。この際、セルの内容は折り返され、各列の区切り線の長さに相対的な列幅が与えられます (たとえば、区切り線が ``---|-` の表では、1列目の列幅はテキスト入力が可能な全横幅の3/4倍に、2列目の列幅は1/4倍になります)。一方、全列幅よりも広い横幅を持つ行がない場合は、セルの内容は折り返されず、また、セルに含まれる内容に合わせて列幅が調整されます。

注意: 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"がヘッダになります。

YAMLメタデータブロックは、有効なYAMLで書かれたブロックであり、最初の行が3つのハイフン (---) 、そして最後の行が3つのハイフン (---) もしくは3つのドット (...) で囲まれます。YAMLメタデータブロックは、文書中の任意の場所に置くことができますが、文書の先頭に置く場合を除き、必ず空行の直後に位置している必要があります。 (Pandocは、複数のファイルが入力として与えられたときに、それらのファイルを連結 (concatenate)してから以後の処理を行います。よって、メタデータを独立したYAMLファイルとして記載し、それをMarkdownファイルと共に引数としてPandocに渡すこともできます:

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

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

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

1つの文書に複数のメタデータブロックを含めることが可能です。複数のメタデータフィールドは、 left-biased union ルールによって統合されます。すなわち、2つのメタデータブロックが同じフィールドを定義しようとする場合、最初のブロックの値が採用されます。

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

YAMLメタデータブロックは、YAMLのエスケープルールに従う必要があることに注意してください。例えば、タイトルにコロンを含める場合は、引用符 (')でタイトルを囲む必要があります。パイプ文字 (|) は、インデントブロックを始めるときに使うことができます。このインデントブロック中では、エスケープをしなかったとしても、すべての文字列がそのまま文字通りに表示されます。この形式は、空行をフィールドに含める場合やブロックレベルの修飾をする場合に必要です:

---
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のルールが適用されます。)

バックスラッシュによってエスケープされた空白文字は、ノーブレークスペースとして変換されます。これは、TeXでは ~ 、HTMLおよびXMLでは \&#160; もしくは \&nbsp; として出力されます。

バックスラッシュによってエスケープされた改行文字 (すなわち、行末のバックスラッシュ) は、ソフトリターン (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.

もしも空白文字を含めた文字列を上付き文字もしくは下付き文字にしたい場合は、その空白文字は、バックスラッシュによってエスケープされる必要があります (この機能は、 ~ や ^ を文章中で使用しているときに、意図せず上付き文字・下付き文字に変換されるのを防ぎます) 。たとえば、もしも'a cat'を下付き文字にもつPという文字を出力したいならば、P~a cat~ ではなく、 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数式の区切り文字として扱われなくなります。

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

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](http://google.com)</td>
</tr>
</table>

を

<table>
<tr>
<td><em>one</em></td>
<td><a href="http://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 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.

Whether or not latex_macros is enabled, the macro definitions will still be passed through as raw LaTeX.

画像

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

![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 attributes except width and height (but including srcset and sizes) are passed through as is. The other writers ignore attributes that are not 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 are converted to inches for output in page-based formats like LaTeX. Dimensions are converted to pixels for output in HTML-like formats. Use the --dpi option to specify the number of pixels per inch. The default is 96dpi.

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

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

引用

Pandocでは、外部フィルター pandoc-citeproc を用いることで、引用および参考文献を様々なスタイルで自動的に生成できます。基本的な使い方は、

pandoc --filter pandoc-citeproc myinput.txt

この機能を使用するためには、YAMLメタデータの bibliography メタデータフィールド、もしくは --bibliography コマンドライン引数によって、参考文献ファイルを指定する必要があります。複数の参考文献ファイルを使用したい場合は、複数の --bibliography 引数を指定するか、 bibliography メタデータフィールドをYAML配列で指定してください。参考文献ファイルとして、以下のフォーマットが使用可能です:

フォーマット

拡張子

BibLaTeX

.bib

BibTeX

.bibtex

Copac

.copac

CSL JSON

.json

CSL YAML

.yaml

EndNote

.enl

EndNote XML

.xml

ISI

.wos

MEDLINE

.medline

MODS

.mods

RIS

.ris

.bib 拡張子は、BibTeXファイルとBibLaTeXファイルの両方に使用されていますが、BibTeXを強制的に用いる場合は、 .bibtex 拡張子を使用してください。

pandoc-citeproc --bib2json および pandoc-citeproc --bib2yaml は、上述した形式の参考文献ファイルを、それぞれ .json および .yaml に変換したファイルを生成します。

インフィールド・マークアップ (In-field markup): 以下の形式の参考文献ファイル中では、マークアップ修飾が可能です。 BibTeX形式およびBibLaTeX形式のファイルではLaTeXマークアップの一部が、CSL YAML形式のファイルではpandoc Markdownが、そしてCLS JSON形式のファイルでは、以下に示した HTML-like markup が使用可能です:

<i>...</i>

斜体

<b>...</b>

太字

<span style="font-variant:small-caps;">...</span> もしくは <sc>...</sc>

スモールキャピタル

<sub>...</sub>

下付き文字

<sup>...</sup>

上付き文字

<span class="nocase">...</span>

タイトルケース表記において、タグで囲まれたテキストの語頭を大文字にすることを防ぐ

pandoc-citeproc -j および pandoc-citeproc -y は、それぞれCSL JSONとCSL YAML形式のファイルを可能な限り相互に変換します。

--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: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
  language: en-GB
...

( pandoc-citeproc --bib2yaml によって、上述した形式の参考文献ファイルから、このようなYAML形式の出力を得ることができます。)

引用と参照は、 Zotero Style Repository に掲載された Citation Style Language でサポートされている任意のスタイルを使用してフォーマットできます。これらのファイルは、 --csl オプションもしくは csl メタデータフィールドを用いて指定してください。既定では、 pandoc-citeproc は Chicago Manual of Style の著者-日付フォーマットを使用します。より詳細な情報は、CSL projectによる finding and editing styles を参照してください。

引用を対応する書誌エントリにハイパーリンクするときは、YAMLメタデータに link-citations: true を追加してください。

引用は角括弧で囲まれ、それぞれの引用はセミコロンで区切られます。各引用は、データベースによって与えられる引用識別子の直前に '@' 記号を付け加えた引用キーを持ちます。引用キーは、データベースのオプションによっては、接頭語、ロケータ、および接尾語を含んでいるかもしれません。引用キーは、(はじめの '@' 記号を除くと、)アルファベット、数字、もしくは _ で始まる必要があり、それ以降に、英数字、 _ 、およびいくつかの記号文字 ( :.#$%&-+?<>~/ ) 。以下に引用キーの例を示します:

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-citeproc は、 CSL locale files で決められたロケータ語を検出します。ロケータとして、省略形もしくは非省略形のどちらかが利用可能です。たとえば en-US ロケールでは、ロケータ語は単数形もしくは複数形で書くことができます: 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.; /¶¶; §/§§ といったように。ロケータ語が事前に設定されていない場合は、与えられたロケータは“ページ”として解釈されます。

pandoc-citeproc は、ヒューリスティックな方法でロケータと接尾語を識別します。ロケータと接尾語の区別がつきにくいような複雑な場合は、波括弧で囲むことでロケータを明示することができます (この機能は pandoc-citeproc バージョン0.15 以上で使用可能です):

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

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.

書誌情報を本文中で引用せずに文献目録に加えたい場合、 nocite メタデータフィールドにダミーの引用を置いてください:

---
nocite: |
  @item1, @item2
...

@item3

この例では、本文には item3 の引用しか生成されませんが、文書末尾に生成される文献目録には、 item1, item2 および item3 の3つの書誌情報が含まれます。

本文中で引用するかどうかに関わらず、bibliography ファイルに含まれる全ての文献を文献目録として生成したい場合は、ワイルドカードを用います:

---
nocite: |
  @*
...

LaTeX出力の場合、 `natbib```_ もしくは ```biblatex```_ を用いて引用文献を生成することができます。この場合、上記で概説したように参考文献ファイルを指定し、 ``--natbib もしくは --biblatex 引数を追加してPandocを実行してください。参考文献ファイルは、それぞれの形式(BibTeXまたはBibLaTeXのいずれか)に従っていなければならないことに注意してください。

詳しくは、 pandoc-citeproc man page を参照してください。

非Pandoc拡張

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

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]: http://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

Markdown方言

Pandocの拡張マークダウンに加えて、以下のMarkdown方言をサポートしています:

markdown_phpextra (PHP Markdown Extra)

footnotes, pipe_tables, raw_html, markdown_attribute, fenced_code_blocks, definition_lists, intraword_underscores, header_attributes, link_attributes, abbreviations, shortcut_reference_links, spaced_reference_links.

markdown_github (廃止されたGitHub-Flavored Markdown)

pipe_tables, raw_html, fenced_code_blocks, auto_identifiers, gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris, space_in_atx_header, intraword_underscores, strikeout, task_lists, emoji, shortcut_reference_links, angle_brackets_escapable, lists_without_preceding_blankline.

markdown_mmd (MultiMarkdown)

pipe_tables, raw_html, markdown_attribute, mmd_link_attributes, tex_math_double_backslash, intraword_underscores, mmd_title_block, footnotes, definition_lists, all_symbols_escapable, implicit_header_references, auto_identifiers, mmd_header_identifiers, shortcut_reference_links, implicit_figures, superscript, subscript, backtick_code_blocks, spaced_reference_links, raw_attribute.

markdown_strict (Markdown.pl)

raw_html, shortcut_reference_links, spaced_reference_links.

commonmark と gfm (GitHub-Flavored Markdown, commonmark の拡張として実装されています)もサポートしています。

commonmark と gfm では、拡張機能のサポートに制限があることに注意してください。以下の項目に示した拡張機能 (加えて smart, raw_tex, hard_line_breaks) のみが機能します。 これらの拡張機能は、すべて個別に無効にできます。 また raw_tex は、 gfm 出力にのみ影響し、入力には影響しません。

gfm (GitHub-Flavored Markdown)

pipe_tables, raw_html, fenced_code_blocks, auto_identifiers, gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris, space_in_atx_header, intraword_underscores, strikeout, task_lists, emoji, shortcut_reference_links, angle_brackets_escapable, lists_without_preceding_blankline.

スライドショーをPandocで生成する

Pandocを使うと、Webブラウザで閲覧可能なHTML + JavaScript のスライドプレゼンテーションを生成できます。スライドには、 S5, DZSlides, Slidy, Slideous, `reveal.js `_ の5つの形式があります。あるいは、LaTeX ```beamer```_ によるPDFスライドや、Microsoft PowerPoint 形式のスライドを生成することもできます。

シンプルなスライドショーを作成するMarkdownソース habits.txt の例を示します:

% Habits
% John Doe
% March 22, 2005

# In the morning

## Getting up

- Turn off alarm
- Get out of bed

## Breakfast

- Eat eggs
- Drink coffee

# In the evening

## Dinner

- Eat spaghetti
- Drink wine

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

![picture of spaghetti](images/spaghetti.jpg)

## Going to sleep

- Get in bed
- Count sheep

HTML/JavaScript スライドショーを得るには、単に次のように実行します。

pandoc -t FORMAT -s habits.txt -o habits.html

ここで FORMAT は s5 、 slidy 、 slideous 、 dzslides または revealjs のいずれかです。

Slidy, Slideous, reveal.js, およびS5の場合、 -s/--standalone オプション付きで出力されたファイルには、JavaScriptおよびCSSファイルへのリンクが埋め込まれます。既定では、それらのファイルはそれぞれ次の相対パスにおいて有効とみなされます: s5/default (S5の場合) 、 slideous (Slideousの場合) 、 reveal.js (reveal.jsの場合) 、 w3.org 上のSlidyのWebサイト (for Slidy) (これらのパスは、それぞれ変数 slidy-url, slideous-url, revealjs-url, s5-url を用いて変更できます。詳しくは、上述の Variables for HTML slides を参照してください)。DZSlidesについては、既定では（比較的短い）JavaScriptとCSSが出力ファイルに含まれます。

すべてのHTMLスライド形式において、 --self-contained オプションを用いることで、画面にスライドショーを表示するためのすべてのデータ (スクリプト、スタイルシート、画像および動画) を含めて、単一ファイルとして出力できます。

beamerでPDFスライドショーを出力するには、次のように実行します。

pandoc -t beamer habits.txt -o habits.pdf

補足: reveal.js スライドショーは、ブラウザを用いてPDFとして印刷することも可能です。

PowerPoint スライドショーを出力するには、次を実行します。

pandoc habits.txt -o habits.pptx

スライドショーの構造をつくる

既定では、 スライドレベル (slide level) には、見出し以外の何らかのスライドコンテンツが直後に現れる見出しの中で、最も高い見出しレベルが設定されます。上記の例 (訳注: habits.txt ) では常に、レベル 1 の見出しの直後にレベル 2の見出しが置かれています。このレベル 2 のヘッダの直後には、スライドコンテンツが置かれています。つまりこの例では、スライドレベルは2です。この既定動作は --slide-level  オプションで変更できます。

1つの文書は、次のルールによっていくつかのスライドに分割されます:

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

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

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

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

:::

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

> - Eat spaghetti
> - Drink wine

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

ポーズの挿入

半角スペースで区切られた3つのピリオドを段落に含めることで、スライドに「ポーズ」を追加できます:

# Slide with a pause

content before the pause

. . .

content after the pause

スライドのスタイルを変える

特定の場所にカスタム済のCSSファイルを配置することで、HTMLスライドの変更できます。その場所は $DATADIR/s5/default (S5の場合)、 $DATADIR/slidy (Slidyの場合)、および $DATADIR/slideous (Slideousの場合) です。ただし $DATADIR はユーザデータディレクトリです。 (上記の --data-dir を参照)。元のCSSファイルはPandocのシステムデータディレクトリ (通常は $CABALDIR/pandoc-VERSION/s5/default) にあります。Pandocはまずユーザデータディレクトリでファイルを検索し、何も見つからない場合にシステムデータディレクトリを検索します。

dzslidesについては、HTMLファイル自身の中に必要なCSSが含まれます。CSSが変更される場合も同様です。

すべての reveal.js configuration options は、変数を介して設定されます。たとえば、テーマの設定は theme 変数を用います:

-V theme=moon

あるいは --css オプションを用いて、カスタム済のスタイルシートを指定できます。

Beamerスライドのスタイルを変えるには -V オプションを用いて、 theme 、 colortheme 、 fonttheme 、 innertheme 、 および outertheme を指定します。

pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf

Note that heading attributes will turn into slide attributes (on a <div> or <section>) in HTML slide formats, allowing you to style individual slides. In beamer, 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...
:::
::::::::::::::

フレームの属性 (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 を利用できます。同様に parallaxBackgroundHorizontal と parallaxBackgroundVertical も設定できます。これらを有効にするには、必ず 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-size 、 data-background-repeat 、 data-background-color 、 data-transition 、 data-transition-speed 。

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

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

---
title: My Slideshow
parallaxBackgroundImage: /path/to/my/background_image.png
---

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

EPUB を Pandoc でつくる

EPUB メタデータ

EPUB メタデータは、 --epub-metadata オプションを使うことで指定できます。ただし、もとの文書がMarkdown形式である場合は、 YAML metadata block を使うのがよいでしょう。例を示します:

---
title:
- type: main
  text: My Book
- type: subtitle
  text: An investigation of metadata
creator:
- role: author
  text: John Smith
- role: editor
  text: Sarah Jones
identifier:
- scheme: DOI
  text: doi:10.234234.234/33
publisher:  My Press
rights: © 2007 John Smith, CC BY-NC
ibooks:
  version: 1.3.4
...

以下の項目が認識されます：

identifier (訳注: 識別子)

文字列値またはフィールド text および scheme のオブジェクト。 scheme の有効な値は ISBN-10 、 GTIN-13 、 UPC 、 ISMN-10 、 DOI 、 LCCN 、 GTIN-14 、 ISBN-13 、 Legal deposit number 、 URN 、 OCLC 、 ISMN-13 、 ISBN-A 、 JP 、 OLCC 。

title

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

creator

Either a string value, or an object with fields role, file-as, and text, or a list of such objects. Valid values for role are MARC relators, but pandoc will attempt to translate the human-readable versions (like “author” and “editor”) to the appropriate marc relators.

contributor

creator と同じ形式。

date

YYYY-MM-DD 形式の文字列 (年 YYYY は必要な場合のみ)。 Pandoc は他の一般的な日時フォーマットを変換しようとします。

lang (古い形式: language)

BCP 47 形式の文字列。これが指定されていない場合、Pandocはローカルの言語をデフォルトとします。

subject

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

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

foreword (訳注: 前書き)

frontmatter

halftitle (訳注: 作品の最初のページまたはテキストの直前にあるタイトル)

frontmatter

introduction

frontmatter

preface (訳注: 序)

frontmatter

seriespage

frontmatter

titlepage (訳注: 作品の標題紙・タイトルページ)

frontmatter

afterword (訳注: 後書き)

backmatter

appendix (訳注: 補足情報・付録)

backmatter

colophon (訳注: 奥付)

backmatter

conclusion

backmatter

epigraph (訳注: 題辞・エピグラフ)

backmatter

リンクされたメディア

通常、Pandoc は生成された EPUB に現れる <img> 、 <audio> 、 <video> または <source> のいずれかから参照されたメディアをダウンロードし、EPUB コンテナに格納しようとします。これにより完全に独立した (self-contained) EPUBを得られます。もしユーザが替わりに外部のメディアリソースへのリンクを望む場合には、生の (raw) HTMLとして source を記述し、src 属性のあるタグに data-external="1" をつけ加えてください。たとえば：

<audio controls="1">
  <source src="http://example.com/music/toccata.mp3"
          data-external="1" type="audio/mpeg">
  </source>
</audio>

Jupyter notebookをPandocでつくる

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 をそれぞれ定義できます。

div または span を custom-style 属性とともに定義したい場合は、Pandocはユーザが指定したスタイルを、対応する要素に適用します。たとえば bracketed_spans 拡張記法を使う場合には、

[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="FirstParagraph"}
This is some text.
:::

::: {custom-style="BodyText"}
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="MyBlockStyle"}
> Here is a styled paragraph that inherits from Block Text.
:::

このようなカスタムスタイルを用いることで、出力文書として docx を作成する場合においても (下記参照)、入力文書 (docx) をリファレンス文書としても同時に利用でき、入力および出力ファイルの両方で同じスタイルが保持されるようになります。

カスタム Writer

Pandocは、lua で書かれたカスタムWriterを使うことで、その機能を拡張することができます (Pandocには、Luaインタプリタが組み込まれているため、別にLuaをインストールする必要はありません)。

カスタム Writer を使用するには、単に Lua スクリプトへのパスを出力形式として指定するだけです。例えば:

pandoc -t data/sample.lua

カスタム Writer を作成するには、Pandoc 文書中の各要素 (element) に対する Lua 関数を書く必要があります。変更の元になる文書化されたサンプルを入手するには、以下のコマンドを実行してください：

pandoc --print-default-data-file sample.lua

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

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–2019 John MacFarlane (jgm@berkeley.edu). Released under the GPL, version 2 or greater.

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.