Pandocの--Templateオプションを利用して、Markdownから完全なHTMLを出力するときにTemplateを使うためのメモ。
Pandoc User’s GuideやPandoc ユーザーズガイド 日本語版を基に記載。 環境はWindows 10 (64bit)。 随時更新。
正確な一次ソースとしてはPandoc User’s GuideのTemplatesがあります。
デフォルトテンプレートを確認する
単に-s/--standaloneオプションを利用した際に使われるデフォルトのテンプレートはpandoc -D *FORMAT*で確認できる。
FORMATは出力フォーマットを指定する。
PS D:\SandBox> pandoc -D markdown $if(titleblock)$ $titleblock$ $endif$ $for(header-includes)$ # *sinp* PS D:\SandBox> pandoc -D html <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="$lang$" xml:lang="$lang$"$if(dir)$ dir="$dir$"$endif$> <head> # *snip*
Templateを使って変換する
一番簡単なのはtemplateファイルを--templateオプションで指定すること。
(--templateを指定すると、自動的に-s/--standaloneオプションも有効になる)
PS D:\SandBox> pandoc --template=template.html D:\Sandbox\PandocでTemplateを使うためのメモ.md
テンプレートファイルの優先順位
テンプレートファイルの利用優先順位は以下の通り。
どの優先順位でテンプレートやユーザデータディレクトリが使われるかは、（よく読めば）Pandocのユーザーズガイドに書かれています。
*snip*
- カレントディレクトリを見る
- 指定されている文字通りのファイル名を探す
- 拡張子が無い場合は、出力フォーマットに対応する拡張子を勝手に補う
- --data-dir で指定されるユーザデータディレクトリの中にある「templates」ディレクトリを探す
- デフォルトユーザデータディレクトリの中にある「templates」を探す
- Pandoc既定のデータディレクトリの中にある「templates」を探す
自作テンプレートを作る
- テンプレートファイルに記載された
$body$部がPandocにより生成したHTMLに置き換わる。 - 自分で定義した変数も
$var$のように利用できる(--variable=*KEY*:*VAL*なり、--metadata=*KEY*:*VAL*で指定する)。 - ifやforといった制御構造も利用できる
- 各種組み込みの変数もある。メタデータ向けの変数はファイルで読める(
--metadata-file=*FILE*))
その他
以下のような拡張機能も便利そう。
Extension: pandoc_title_block
- 入力ファイル冒頭の%で始まる行を、
title,author,dataという変数として読み込んでくれる。 - デフォルトで有効だが、明示的に指定したい場合は
--from *FORMAT*+pandoc_title_blockする。 - Lintツール(markdownlintなど)によっては警告が出力されるので、Lintツール側で無効化する必要あり。
