理系学生日記

おまえはいつまで学生気分なのか

MarkdownをpandocでHTML化するときのノウハウ

pandoc markdown

MarkdownファイルをPandocでHTML化する際、どのような指定が良いかを迷っていたのですが、いまのところ以下のようなオプションで落ち着きました。

$ pandoc \
    --standalone \
    --self-contained \
    --resource-path=/path/to \
    --toc \
    --toc-depth 2 \
    --shift-heading-level-by=-1 \
    --metadata title='タイトル' \
    --template=html_templates/bootstrap_menu.html \
    --fail-if-warnings \
    --output=${destdir}/guide.html \
    /path/to/target.md

HTMLテンプレート

Pandocでは、出力フォーマットに応じたテンプレートを内包しています。 デフォルトのテンプレートはpandoc -D 'html'で確認できます。

$ pandoc -D 'html' | head -5
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="$lang$" xml:lang="$lang$"$if(dir)$ dir="$dir$"$endif$>
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />

テンプレートは自身でも記述可能なのですが、オシャレなテンプレートもGitHub等で公開されています。 例えば僕が使ったのはこちらのテンプレートです。

screenshotフォルダを見れば、出力されるHTMLが理解できるでしょう。 ぼくはテンプレートとしてbootstrap_menu.htmlを利用しました。 以下のように、ローカルにテンプレートをダウンロードして、pandocの`--template=で指定すれば良いです。

$ curl 'https://raw.githubusercontent.com/ryangrose/easy-pandoc-templates/master/html/bootstrap_menu.html' > html_templates/bootstrap_menu.html

Table of Contents(TOC)の作成

上記のテンプレートはサイドバーに索引を表示してくれますが、この索引を生成するのが--tocオプションです。 一方で、Markdownではトップレベルの#がページのタイトルを構成することが多く、これを索引に表示したくないケースがあります。 このようなケースでは--shift-heading-level-byオプションを利用しましょう。これは索引に表示するレベルを「ずらす」ことができるオプションです。例えば-1を指定すると、#は索引に表示されなくなります。 どこまでを索引に表示するかは、--toc-depthで指定します。

例えばpandoc --toc --toc-depth=2 --shift-heading-level-by=-1と指定した場合を考えます。 この場合、Markdown上の# headerは索引が除去され、## headerと### headerは索引に表示されます。

画像ファイルの同梱

HTMLファイルを生成しても、画像ファイルを同梱しなければHTMLから参照できません。一般的には。

Pandocのすごいところはここで、--self-containedオプションを使用すると、画像や動画に関してはdata:スキームに置き換えてくれます。つまり、画像や動画をファイルとして一緒に配布することなく、HTMLファイル1枚を配布するだけですみます。便利。

もちろん、どこに画像や動画が配置されているかを指定する--resource-pathを忘れずに。