Markdownで書いた実験レポートをTeX組版の美しいPDFに変換するDockerイメージを作った
こんにちは、@p1assです。
皆さんは、実験レポートを何で書いていますか？ Wordですか？それともLaTeXですか？
私はそのどちらでもなく、Markdownで書いています。 Markdownはシンプルなシンタックスで様々な表現ができ、多くのエンジニアに愛されています。 しかし、Markdownは実験レポート用途にあまり使われていないため、そのままでは美しいPDFを作成することができません。
この記事では、pandocという様々なフォーマットのドキュメントを相互変換するツールを使って、Markdownで書いた実験レポートをTeX組版の美しいPDFにする方法をご紹介します。
これは、マークダウンから変換したPDFです。
依存は全てDockerイメージにまとめてあるので、Dockerさえあれば、ローカルに何もインストールすることなく、誰でも簡単に美しい実験レポートを作成できるので、皆さん是非試してみてください。
特徴
まずはじめに、今回私が作成したDockerイメージの特徴を一覧で紹介します。
- MarkdownをPDFに変換
- Markdownを保存するたびにPDFに変換
- TeX組版を使用した美しい見た目
- セクション番号の自動付与
- LaTeX形式の数式入力
- 数式・図表番号とその参照
- LaTeXコマンド
- マークダウンの様々な記法がそのまま使用可能
- etc…
このように様々な特徴があります。
「Wordで書くと番号付けや数式入力が面倒くさいからLaTeXで書いているけど、LaTeXの文法も上長で面倒くさい、、、😔」 という人にはとてもおすすめできます。
実際の変換前のMarkdownファイルとPDFファイルは次のリンク先から見ることができます。
MarkdownをPDFに変換する方法
Dockerを使ってPDFに変換を行います。 Dockerのインストール方法は各自調べてください。
今回使用するDockerイメージはこのリポジトリで管理しています。スターしてくれると泣いて喜びます😂
PDFに変換する方法は簡単3STEPです。
STEP1 : Dockerイメージをpullする
$ docker pull plass/mdtopdf※ このDockerイメージのサイズは1.68GBです。速いネット回線を使ってpullすることをおすすめします。
STEP2 : 変換したいMarkdownファイルがあるディレクトリに移動する
$ cd path/to/directorySTEP3 : PDFに変換する
INPUT.mdは各自自分のファイルに書き換えてください。処理が完了するとINPUT.pdfが生成されます。
$ docker run -it --rm -v `pwd`:/workdir plass/mdtopdf mdtopdf INPUT.md以上です。とても簡単ですね！
発展的な使い方
保存するたびにPDFに変換する
いちいち保存するたびに変換コマンドを打っていては面倒くさいですよね。
そこで、Markdownファイルを保存するたびに変換するようにできるようにしましょう。
$ docker run -it --rm -v `pwd`:/workdir plass/mdtopdf w-mdtopdf INPUT.md1秒間隔でファイルを監視し、変更があればPDFに変換します。
このスクリプトは以下のブログを参考にさせていただきました。
aliasを使って簡単に変換を実行できるようにする
上で書いたコマンドは長くて覚えづらいですよね。
alias コマンドを使って簡単に呼び出せるようにしましょう。
$ echo "alias mdtopdf='docker run -it --rm -v `pwd`:/workdir plass/mdtopdf mdtopdf'" >> ~/.bash_profile
$ echo "alias w-mdtopdf='docker run -it --rm -v `pwd`:/workdir plass/mdtopdf w-mdtopdf'" >> ~/.bash_profile
$ source ~/.bash_profile
$ mdtopdf INPUT.md
$ w-mdtopdf INPUT.mdzsh: .bash_profile を .zshrc にしてください。
Ubuntu: .bash_profile を .bashrc にしてください。
Markdownファイルをtexファイルに変換する
TeX組版を使っていることからも分かる通り、今回のPDF生成は内部的には一度texファイルにしてから行われています。 そのため、その中間ファイルを生成することもできます。
$ docker run -it --rm -v `pwd`:/workdir plass/mdtopdf mdtotex INPUT.mdpandocを使った変換
さて、ここではpandocを使った変換の方法を(おまけ程度に)見ていきます。
上で紹介した変換は全てシェルスクリプトでラップしていましたが、内部的にはpandocを使っています。
pandocはMarkdownやHTML、EPUB、Word、LaTeX、PDFなど多種多様なドキュメントフォーマットを相互に変換してくれるHaskell製のツールです。 Windows、macOS、Linuxなどに対応していて大体の環境では動くと思われます。
MarkdownからPDFへの変換には次のスクリプトを実行しています。
#!/bin/bash
# mdtopdf
input=$1
pandoc -s -N ${input%.*}.md -o ${input%.*}.pdf \
-V documentclass=ltjarticle --pdf-engine=lualatex \
-V geometry:margin=1in \
-F pandoc-crossref \
-M "crossrefYaml=/config/crossref_config.yaml" -Nオプションで自動でセクション番号を付与してくれます。
-F pandoc-crossrefでは pandoc-crossref という相互参照のためのフィルタを使っています。 次の行の-M "crossrefYaml=..."と合わせて、図表番号を正しく表示できるようにしています。
figureTitle: '図'
tableTitle: '表'
listingTitle: 'コード'
figPrefix: '図'
eqnPrefix: '式'
tblPrefix: '表'
lstPrefix: 'コード'
--pdf-engine=lualatexでPDF生成のエンジンにはLuaLaTeXを使用するように指定しています。これは他のエンジンでは正しく日本語を認識してくれないためです。 また、-VでLuaLaTeX用のオプションを指定しています。
保存するたびにPDFに変換するのは簡単で、次のスクリプトを使っています。
#!/bin/bash
# w-mdtopdf
watcher $1 mdtopdf $1２回同じファイル名を引数に指定しなくても良いようにしているだけですね。
mdtotexはmdtopdfとほとんど同じなので省略します。
終わりに
pandocを使うことで、Markdownファイルから美しいTeX組版のPDFを生成することができました。 また、Dockerとシェルスクリプトを使うことで、使用者側はpandocなどを意識せず、簡単に扱うことができます。
皆さんも是非使ってみてください！
Issue、Conrtibute、Starどれもお待ちしています！