Markdownで図表とソースコードを取り込めるPandoc環境を作る

はじめに

想定する読者

• markdownからPDFを作成したい
• 画像や表をいくつか載せるので，参照番号は自動で挿入してほしい
• ソースコードを載せるときは，ファイルから取り込みたい

早い話が

このスクリプトを実行すれば，準備完了です．以下で詳細を解説します．

前提とする環境

• Ubuntu 16.04(Windows Subsystem for Linux含む)
• stack, nodejs, npm

準備するpandocツール

• pandoc
  • markdownをpdfに変換するツール
  • 実は色々なフォーマットにも対応している
• pandoc-crossref
  • 図や表の参照番号を挿入するためのフィルタ
• pandoc_import_code_filter
  • ソースコードを取り込むためのフィルタ

ツールのインストール

方針

Ubuntu 16.04のリポジトリにはpandoc-crossrefがありませんので，最新のソースコードをGithubからダウンロードしてビルド&インストールすることにします．

またaptでインストールしたPandocはバージョンが古いため，同じくGithubからダウンロードします．ただしこちらはdebパッケージがあるので，これを利用することにします．

Pandoc

GithubのリポジトリにDebian向けのパッケージがあるので，これをインストールしましょう．

# 最新(2018/11/12現在)のdebパッケージ
wget https://github.com/jgm/pandoc/releases/tag/2.4/pandoc-2.4-1-amd64.deb
sudo apt install ./pandoc-2.4-1-amd64.deb -y

# PDFのレンダリングに必要なライブラリをインストール
sudo apt install texlive-luatex texlive-lang-cjk lmodern texlive-xetex texlive-math-extra

pandoc-crossref

Githubのリポジトリからダウンロードしてビルドします．pandoc-crossrefはHaskellのプロジェクトなので，ビルドにはHaskellの開発環境が必要です．今回はstackをビルド&インストールします．
なぜstackもビルドするのか?
実はaptでインストールしたstackだとビルドが出来ません...．
私はHaskellの専門家では無いので，原因は深追いせずに最新のものを使って対処しました．

# stackをインストール
# すごい時間がかかる
curl -sSL https://get.haskellstack.org/ | sh

# pandoc-crossrefをダウンロード
git clone https://github.com/lierdakil/pandoc-crossref

# stackでpandoc-crossrefをインストール
# これも時間がかかります
cd pandoc-crossref
stack build --allow-different-user
stack install --allow-different-user

pandoc_import_code_filter

Githubのリポジトリからダウンロードします．pandoc_import_code_filterはnode.jsのプロジェクトなので，実行にはnode.jsの環境が必要になります．

# nodeをインストール
sudo apt install nodejs npm -y

# pandoc_import_code_filterを/optにダウンロード
mkdir -p /opt/pandoc_import_code_filter
cd /opt/pandoc_import_code_filter
git clone https://github.com/azu/pandoc_import_code_filter
npm install

pandoc_import_code_filterをコマンドとして使えるように，/usr/local/binに以下のスクリプトを置きます．

# !/usr/bin/env bash

nodejs /opt/pandoc_import_code_filter "$@"

実行権限を付けるのも忘れずに．

chmod 0755 pandoc_import_code_filter

試してみる

• サンプルmarkdown

---
documentclass: ltjarticle
title: Sample title
author: Kenta
header-includes:
    - \usepackage[margin=1in]{geometry}
---

# はじめに

このドキュメントはサンプルです．

# Image

[@fig:sample]は素敵な画像です．

![sample.jpg](sample.jpg){#fig:sample width=10% height=10%}

# C program

[@lst:sample-code]は素敵なCプログラムです．

\`\`\`{#lst:sample-code .c .numberLines caption="素敵なCプログラム"}
$import(sample.c)
\`\`\`
<!--> ここのバッククォートをどうやってエスケープしよう... <--!>

インストール済みのツールを使ってpdfにします．

pandoc sample.md -o sample.pdf\
    --pdf-engine=lualatex\
    -F pandoc-crossref\
    -F pandoc_import_code_filter

以下のようなPDFファイルが出力されます．

おわりに

Pandocと各種フィルタを使ってmarkdownからPDFのドキュメントを作ることができました．フィルタはさらに追加することができますので，自分だけのPandoc環境を作っていきましょう．

参考文献

1. Pandoc User's Guide : https://pandoc.org/MANUAL.html

   • Pandocのインストール方法から使い方まで色々書いてあります

2. pandocでMarkdownを拡張しコードをインポート出来るfilterを書く - Web Scratch：https://efcl.info/2014/0301/res3692/

   • pandoc_import_code_filterを実装された方の解説ページ

3. まだ Word で消耗してるの？ 大学のレポートを Markdown で書こう - Qiita：https://qiita.com/Kumassy/items/5b6ae6b99df08fb434d9

   • Pandocの使い方とMarkdownの書き方については@Kumassy様の記事が非常に参考になります