Edited at

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ファイルが出力されます.

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