pandocによりmarkdownからhtmlを出力する

はじめに

markdownから余計な装飾の無いhtmlを得るために、pandocによる変換環境を構築します。

参考資料

• 公式pandocドキュメント(英語)
• Pandoc ユーザーズガイド 日本語版

英語との格闘を覚悟していたのですが、@sky_yさんが日本語訳を行って公開されているので感謝しつつ利用します。

pandocをインストールする

macOSならbrewによりインストールできます。

ringo@stupiddog ~ $ brew install pandoc
Updating Homebrew...
==> Downloading https://homebrew.bintray.com/bottles/pandoc-2.1.3.sierra.bottle.tar.gz
######################################################################## 100.0%
==> Pouring pandoc-2.1.3.sierra.bottle.tar.gz
==> Caveats
Bash completion has been installed to:
  /usr/local/etc/bash_completion.d
==> Summary
🍺  /usr/local/Cellar/pandoc/2.1.3: 173 files, 65.2MB

変換する

markdownファイルをhtmlファイルへ変換するには次のコマンドを実行します。 – 入力ファイル = input.md – 出力ファイル = output.html (出力ファイルを省略すると標準出力へ出力されます)

ringo@stupiddog ~ $ pandoc input.md -o output.html

コードブロックへの属性追加

何も設定をしなくてmarkdownからhtmlに変換できますが、コードハイライト用のjsライブラリを利用している場合などはクラス属性で言語の指定を行う必要があります。

コードブロックにprism.js向けのclass属性を追加する方法

markdownのコードブロックの始まりでオプションを波括弧で括って指定します。 – idなら #example – classなら .example – 属性なら example=“100”

prism.jsでハイライトする際はclass属性に“language-言語名”を指定します。例としてPHP言語ならば以下のようになります。(Prismj – Full list of featuresを参照)

markdownの記述

``` {.language-php}
<?php
echo "hello world" . PHP_EOL;
```

出力結果

<?php
echo "hello world" . PHP_EOL;

画像で<figure>が利用されないようにする方法

![代替テキスト](画像URI)を利用してhtmlに変換すると、<figure>タグで括られて出力されます。これを<img>タグのみにするには、![代替テキスト](画像URI)\のように末尾に\を付けます。(正確には改行以外なら何でもいいらしいので、<figure>タグを出力したい場合に余計な文字が末尾にあると出力出来ません)

見出しにid属性が付かないようにする方法

オプションを指定せずにmarkdownからhtmlへ変換すると、自動で見出しタグ(<h>)にid属性が付きます。日本語で見出しを書いている場合、このid属性も日本語で付けられてしまうため宜しくありません。

この自動で見出しタグにid属性が付けられる機能は、markdownの拡張(auto_identifiers)として実装されているので個別に無効にできます。

コマンドラインで変換を行う際に読み込みフォーマット側でmarkdownに続けて拡張名に-を付けてauto_identifiersを指定します。

ringo@stupiddog ~ $ pandoc -f markdown-auto_identifiers input.md -o output.html