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


# はじめに

## 想定する読者

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

## 早い話が

[このスクリプト](https://gist.github.com/Kenta11/e2dd25bbba42ea5cc2019849b8bac59a)を実行すれば，準備完了です．以下で詳細を解説します．

## 前提とする環境

- 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のリポジトリ](https://github.com/jgm/pandoc)に[Debian向けのパッケージがある](https://github.com/jgm/pandoc/releases/tag/2.4)ので，これをインストールしましょう．

```bash
# 最新(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のリポジトリ](https://github.com/lierdakil/pandoc-crossref)からダウンロードしてビルドします．pandoc-crossrefはHaskellのプロジェクトなので，ビルドにはHaskellの開発環境が必要です．今回はstackをビルド&インストールします．
なぜstackもビルドするのか?
実はaptでインストールしたstackだとビルドが出来ません...．
私はHaskellの専門家では無いので，原因は深追いせずに最新のものを使って対処しました．

```bash
# 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のリポジトリ](https://github.com/azu/pandoc\_import\_code\_filter)からダウンロードします．pandoc\_import\_code\_filterはnode.jsのプロジェクトなので，実行にはnode.jsの環境が必要になります．

```bash
# 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に以下のスクリプトを置きます．

```bash
#!/usr/bin/env bash

nodejs /opt/pandoc_import_code_filter "$@"
```

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

```bash
chmod 0755 pandoc_import_code_filter
```

# 試してみる

- サンプルmarkdown

```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にします．

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

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

![document.png](https://qiita-image-store.s3.amazonaws.com/0/271956/8351866f-aeaf-98a2-c77d-dd179c457101.png)

# おわりに

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様の記事が非常に参考になります