[Document workflow] Pandoc: markdown を github 風 html に変換する

CSS を設定して書式を github 風にします。

先日こんなことをしたのですが、pandoc でもできるように設定しておこうと調べました。

デフォルト

通常の変換はこんな書き方です。

% pandoc -s test.md -o test.html

github 風 css を適用する

書式がいまいちなので他の方法を探したところ、CSS を指定できるとのこと。

こちらで公開されている方がいるので、ありがたく頂戴します。
カレントディレクトリに github.css という名前で保存します。

オプション -c 付きで変換すると github.css が参照された html が作成できました。

% pandoc -s test.md -t html5 -c github.css -o test.html

ソースを見ると、こんな形で参照されています。

test.html
<link rel="stylesheet" href="github.css">

ユーザデータディレクトリを利用する

このままだと CSS ファイルを別途管理しなければならないので、グローバルに参照できるディレクトリにファイルを移動したいです。
ユーザデータディレクトリという仕組みがあり、以下のコマンドで場所が分かります。

% pandoc --version
pandoc 1.12.3
    :
Default user data directory: /Users/****/.pandoc
    :

さっそくディレクトリを作成して CSS ファイルを移動します。

% cd
% mkdir .pandoc
% mv github.css .pandoc

これでほんとうはユーザデータディレクトリを走査してくれるはずなんですがうまくいかず。。。

% pandoc -s test.md -t html5 -c github.css -o test.html

保留。。。

Custom Template を作成する

カスタムテンプレートファイルをユーザデータディレクトリに置くと、システムよりも優先的に探してくれるそうなので、独自のテンプレートを作成します。
下記のコマンドで、ディフォルトテンプレートを元にひな型を作成できます。

% pandoc -D html5 > github.html

今回はひな型に、以下の CSS ファイルへのリンクを追加します。

  <link rel="stylesheet" href="/Users/****/.pandoc/github.css">

このテンプレートを .pandoc/templates/ 以下に配置します。

% mkdir .pandoc/templates/
% mv github.html .pandoc/templates/

以下のオプションが有効になりました。

% pandoc -s test.md --template=github -o test.html

Custom Template をディフォルトに指定する

ちなみにこのファイル名を default.html へ変更すると、HTMLテンプレートのディフォルトに変わります。

% mv .pandoc/templates/github.html .pandoc/templates/default.html
% pandoc -s test.md -o test.html

このあたりの命名規則に従うようです。

補遺

ユーザーガイドのすばらしい日本語訳があります。
いろいろあるので使うところだけ拾い読みしました。

深い。

以前の関連記事。