都市大YCの卒業研究概要集をMarkdownで快適に書くためのPandoc環境セットアップ備忘録

この記事はTokyo City University Advent Calendar 2021の3日目の記事です。

昨日の記事は @BOB さんによる辻堂にバーガーキングができたらしい - bob563’s diary でした!

弘前の人のテンションと同じ感じで好きです。

はじめに

4年生の皆様は絶賛卒業研究中かと思われます。お疲れ様です。

さて、論文や概要集を書くにあたって、Wordで書いていくのはなんとなく嫌な人、いると思います。
Markdownで書いて、いい感じにしてくれれば・・・

そんなときにはPandocを使って変換していくのですが、環境構築がなかなかに面倒です。

とりあえず1月に提出するYC用フォーマットの卒業研究概要集を出力できるように整ってきたので、備忘録としてセットアップについて記載してきます。

(いろいろなところからの寄せ集め情報です。)

割と勘の状態でやっており、詳しい人からのツッコミがすごそうな記事なので、むしろそういう方からのツッコミをお待ちしています。よろしくおねがいします。
設定を複数箇所に渡って指定したりしていますが、何故かそうしないと動かなかったりするんです。助けてください。

環境について

本記事ではLinux(Debian/Ubuntu)環境を想定しています。
(筆者が実際に使っている環境はWSL1のUbuntu 20.04です。)
Windowsユーザーの人はこの記事通りに行いたい場合はWSL1で良いのでLinux環境を用意してください。多分Windowsネイティブでも出来るとは思いますが、なんにもわかりません。

macOS(M1, Monterey)でも試していますが、フォントの問題のみ解決できませんでした。ヒラギノでいいなら行けると思います。

環境構築

Linux/WSL(Debian/Ubuntu)

pandocのインストール

ここから最新版のpandocのdebを落としてきます。
執筆時はpandoc-2.16.2-1-amd64.debです。
Releases · jgm/pandoc

wget https://github.com/jgm/pandoc/releases/download/2.16.2/pandoc-2.16.2-1-amd64.deb
sudo dpkg -i pandoc-2.16.2-1-amd64.deb

1 2	wget https://github.com/jgm/pandoc/releases/download/2.16.2/pandoc-2.16.2-1-amd64.deb sudo dpkg -i pandoc-2.16.2-1-amd64.deb

その他必要なパッケージを入れる

sudo apt install texlive texlive-luatex texlive-latex-extra texlive-lang-cjk fonts-ipaexfont

1	sudo apt install texlive texlive-luatex texlive-latex-extra texlive-lang-cjk fonts-ipaexfont

(フォントはとりあえずIPAexにしています。)

もろもろのテンプレデータ的物を入れるディレクトリを作る

mkdir ~/markdown

1	mkdir ~/markdown

このあたりは適宜好きなようにしてください

pandoc-crossrefを落とす

ここからpandoc-crossref-Linux.tar.xzを落として展開します。
Releases · lierdakil/pandoc-crossref

執筆時は0.3.12.1aでした。

cd ~/markdown
wget https://github.com/lierdakil/pandoc-crossref/releases/download/v0.3.12.1a/pandoc-crossref-Linux.tar.xz
xz -dc pandoc-crossref-Linux.tar.xz | tar xfv -

cd ~/markdown

wget https://github.com/lierdakil/pandoc-crossref/releases/download/v0.3.12.1a/pandoc-crossref-Linux.tar.xz

xz -dc pandoc-crossref-Linux.tar.xz | tar xfv -

これで~/markdownにpandoc-crossrefという実行ファイルが展開されます。

macOS(M1 + Montereyでテスト)

pandocのインストール

最新版のpandocのpkgを落としてインストールします(全てのユーザーに対してで良いかと)。
執筆時はpandoc-2.16.2-macOS.pkgです。
Releases · jgm/pandoc

その他必要なパッケージを入れる

texlive系のインストールはbrewだと思ったよりめんどくさそうなので、MacPortsを使います。

sudo port install texlive-lang-japanese texlive-luatex texlive texlive-latex-extra

1	sudo port install texlive-lang-japanese texlive-luatex texlive texlive-latex-extra

フォントを入れていきますが、macOSだとIPAex明朝ではレンダリングがコケる気がします。まぁインストールすると普通にIPAexフォントがインストールされるだけなのでとりあえず。

brew install homebrew/cask-fonts/font-ipaexfont

1	brew install homebrew/cask-fonts/font-ipaexfont

もろもろのテンプレデータ的物を入れるディレクトリを作る

mkdir ~/markdown

1	mkdir ~/markdown

このあたりは適宜好きなようにしてください

pandoc-crossrefを落とす

ここからpandoc-crossref-Linux.tar.xzを落として展開します。
Releases · lierdakil/pandoc-crossref

執筆時は0.3.12.1aでした。

cd ~/markdown
curl -LO https://github.com/lierdakil/pandoc-crossref/releases/download/v0.3.12.1a/pandoc-crossref-macOS.tar.xz
xz -dc pandoc-crossref-macOS.tar.xz | tar xfv -

cd ~/markdown

curl -LO https://github.com/lierdakil/pandoc-crossref/releases/download/v0.3.12.1a/pandoc-crossref-macOS.tar.xz

xz -dc pandoc-crossref-macOS.tar.xz | tar xfv -

これで~/markdownにpandoc-crossrefという実行ファイルが展開されます。

(以下Linux/macOS共通)pandocとpandoc-crossrefのバージョンを確認する

pandocとpandoc-crossrefのビルド元pandocバージョンは一致していないと動作しません。

$ pandoc -v
pandoc 2.16.2
Compiled with pandoc-types 1.22.1, texmath 0.12.3.2, skylighting 0.12.1,
...

$ pandoc -v

pandoc 2.16.2

Compiled with pandoc-types 1.22.1, texmath 0.12.3.2, skylighting 0.12.1,

...

$ ./pandoc-crossref -v
pandoc-crossref v0.3.12.1 git commit 0a47293d7d47aa763e82204e13deabc8f1a041c4 (HEAD) built with Pandoc v2.16.2, pandoc-types v1.22.1 and GHC 8.10.7

1 2	$ ./pandoc-crossref -v pandoc-crossref v0.3.12.1 git commit 0a47293d7d47aa763e82204e13deabc8f1a041c4 (HEAD) built with Pandoc v2.16.2, pandoc-types v1.22.1 and GHC 8.10.7

上記の場合、pandocが2.16.2、pandoc-crossrefが「built with Pandoc v2.16.2」となっており、一致しています。

metadata.yamlの用意

図や表、コードなどのPrefixを設定したり、二段組を使う場合に設定したりします。
~/markdown/metadata.yamlとして保存します。

なぜここにTitleやAuthorが入っていないのか、という点については、冒頭部分のレイアウトを自分で制御したいからというのがあります(テンプレートを弄る気力がないので)。後述します。

figureTitle: "図 "
tableTitle: "表 "
listingTitle: "コード "
figPrefix: "図"
eqnPrefix: "式"
tblPrefix: "表"
lstPrefix: "コード"
codeBlockCaptions: true
listings: true
# 見出し番号自動で付ける
numbersections: true

# 左右に段組みにする場合
header-includes:
  - \documentclass[twocolumn, a4j]{jarticle}

figureTitle: "図 "

tableTitle: "表 "

listingTitle: "コード "

figPrefix: "図"

eqnPrefix: "式"

tblPrefix: "表"

lstPrefix: "コード"

codeBlockCaptions: true

listings: true

# 見出し番号自動で付ける

numbersections: true

# 左右に段組みにする場合

header-includes:

- \documentclass[twocolumn, a4j]{jarticle}

make.yamlの用意

生成するときのオプションをまとめて書いておいたyamlファイルを用意して、生成コマンドが長くならないようにします。

macOSの場合、CJKmainfontをIPAexMinchoにしても読み込まれないことがあるので、luatexjapresetoptionsとCJKmainfontをコメントアウトしてデフォルトのヒラギノ明朝にしたほうが良いかも知れません

フォントサイズが11ptになっていますが、だいたいこれで10.5ptと同じくらいです。
TeX を使った論文作成のノウハウ

filters:
  - pandoc-crossref

pdf-engine: lualatex

standalone: true

metadata-files:
  - metadata.yaml

variables:
  documentclass: ltjarticle
  classoption: pandoc

  # 上下左右余白
  geometry:
    - top=2cm
    - bottom=2cm
    - left=2cm
    - right=2cm

  # 11pt≒10.5pt
  fontsize: 11pt

  # フォント設定
  luatexjapresetoptions: IPAexMincho
  CJKmainfont: IPAexMincho

  # 行間設定 これで縦を37行に
  linestretch: 1.28

  # 字下げ設定
  indent: true

include-in-header:
  - header.tex

listings: true

csl: sist02

filters:

- pandoc-crossref

pdf-engine: lualatex

standalone: true

metadata-files:

- metadata.yaml

variables:

documentclass: ltjarticle

classoption: pandoc

# 上下左右余白

geometry:

- top=2cm

- bottom=2cm

- left=2cm

- right=2cm

# 11pt≒10.5pt

fontsize: 11pt

# フォント設定

luatexjapresetoptions: IPAexMincho

CJKmainfont: IPAexMincho

# 行間設定これで縦を37行に

linestretch: 1.28

# 字下げ設定

indent: true

include-in-header:

- header.tex

listings: true

csl: sist02

header.texの用意

以下の内容を記載した~/markdown/header.texを用意します

コードブロックがない場合はコードブロックの色設定は必要ないですが、
最後のrenewcommandの行が無いと、図などのキャプションが英語のままになります。(さっきyamlで設定したのになんで?)

色設定等はPandocを使ってMarkdownでレポートを書いてみる - 屋根裏より拝借しました。

図の位置については R Markdownでpdf出力する時の図の位置設定 | Nylog より拝借しました。

\usepackage{listings}
\usepackage{xcolor}
\usepackage{url} % 参考文献用
\usepackage{titlesec}

% 見出しのフォント設定を特に大きくせず他と同じにする
\titleformat*{\section}{\selectfont\rmfamily}
\titleformat*{\subsection}{\selectfont\rmfamily}

% 二段組の間の間隔 これで横を22文字に
\setlength{\columnsep}{1cm}

% コードブロックの色設定
\lstset{
    basicstyle=\ttfamily,
    keywordstyle=\color[rgb]{0,0,0.6}\bfseries,
    stringstyle=\color[rgb]{0,0.6,0},
    commentstyle=\color[rgb]{0.4,0.4,0.4}\itshape,
    numberstyle=\ttfamily,
    numbers=none,
    stepnumber=1,
    numbersep=15pt,
    numberstyle=\color[rgb]{0.6,0.6,0.6},
    tabsize=4,
    breaklines=true,
    captionpos=t,
    frame=single,
    rulecolor=\color[rgb]{0.8,0.8,0.8}, 
    backgroundcolor=\color[rgb]{0.95,0.95,0.95},
    showspaces=false,
    showtabs=false,
    showstringspaces=false
}

\renewcommand{\lstlistingname}{コード}

% 図の位置を書いた位置にする
\usepackage{float}
\let\origfigure\figure
\let\endorigfigure\endfigure
\renewenvironment{figure}[1][2] {
    \expandafter\origfigure\expandafter[H]
} {
    \endorigfigure
}

\usepackage{listings}

\usepackage{xcolor}

\usepackage{url} % 参考文献用

\usepackage{titlesec}

% 見出しのフォント設定を特に大きくせず他と同じにする

\titleformat*{\section}{\selectfont\rmfamily}

\titleformat*{\subsection}{\selectfont\rmfamily}

% 二段組の間の間隔これで横を22文字に

\setlength{\columnsep}{1cm}

% コードブロックの色設定

\lstset{

basicstyle=\ttfamily,

keywordstyle=\color[rgb]{0,0,0.6}\bfseries,

stringstyle=\color[rgb]{0,0.6,0},

commentstyle=\color[rgb]{0.4,0.4,0.4}\itshape,

numberstyle=\ttfamily,

numbers=none,

stepnumber=1,

numbersep=15pt,

numberstyle=\color[rgb]{0.6,0.6,0.6},

tabsize=4,

breaklines=true,

captionpos=t,

frame=single,

rulecolor=\color[rgb]{0.8,0.8,0.8},

backgroundcolor=\color[rgb]{0.95,0.95,0.95},

showspaces=false,

showtabs=false,

showstringspaces=false

}

\renewcommand{\lstlistingname}{コード}

% 図の位置を書いた位置にする

\usepackage{float}

\let\origfigure\figure

\let\endorigfigure\endfigure

\renewenvironment{figure}[1][2] {

\expandafter\origfigure\expandafter[H]

} {

\endorigfigure

}

references.bibの用意

これは実際のMarkdownファイルがある場所に作ります。

参考文献を突っ込んでいくファイルです。

BiBTeX形式で記載します。
どんなものか、については BiBTeXとは - Qiita を参考にして下さい。

sist02.cslの用意

Zotero Style Repository からsist02.cslをダウンロードします(「SIST02 (日本語)」

wget https://www.zotero.org/styles/sist02 -O sist02.csl

1	wget https://www.zotero.org/styles/sist02 -O sist02.csl

これは参考文献のスタイルをいい感じにしてくれるものなのですが、リスト表記時や文章内の参照番号が「(1)」のように普通のカッコになってしまうので、これを[1]のようになるよう、書き換えます。

sed -i -e 's/prefix="("/prefix="["/g' sist02.csl
sed -i -e 's/suffix=")"/suffix="]"/g' sist02.csl

1 2	sed -i -e 's/prefix="("/prefix="["/g' sist02.csl sed -i -e 's/suffix=")"/suffix="]"/g' sist02.csl

生成コマンド

hoge.mdをhoge.pdfにする、というものなのですが、実はPandocのバージョンの諸々で、参考文献が入っていると
\vadjust preというコマンドが挿入され、lualatexがエラーを吐きます。
( Error with \vadjust when loading luatexja package - Jgm/Pandoc )

色々検証してみたところ、一度pandocでPDFではなくtexファイルを出力し、当該部分を削除してlualatexでコンパイルするのが良さそうです。

ということで、いきなりですが生成関数を.bashrcや.zshrcに記載します。

(なんでtex出力なのにmake.yamlでpdf-engineを書いたんだ、という話になりそうですが、別に存在してても構わなそうなので許してください)

bash/zsh用function

function mdtopdf () {

    # 終了後にもとのディレクトリに戻れるように現在のディレクトリを取得
    origdir=`pwd`

    # ファイル名から拡張子を取り除いたものを取得
    file=`echo $1 | sed -e 's/\.md//'`

    # 指定されたmarkdownがあるディレクトリの絶対パスを取得
    dirpath=$(cd $(dirname $1); pwd)

    # いろいろな設定ファイルがある~/markdownに移動
    cd ~/markdown

    # pandocでtexファイルを生成
    pandoc -d make.yaml \
    --bibliography=${dirpath}/references.bib \
    --resource-path=${dirpath} \
    --cite \
    --csl=sist02 \
    -f markdown+hard_line_breaks \
    ${dirpath}/${file}.md \
    -o ${dirpath}/${file}.tex

    # もとのディレクトリに戻る
    cd $origdir

    # texファイルからいらない部分を消す
    sed -i -e 's/\\vadjust pre{\(.*\)}%/\1/' ${file}.tex

    # コンパイルする
    lualatex ${file}.tex
}

function mdtopdf () {

# 終了後にもとのディレクトリに戻れるように現在のディレクトリを取得

origdir=`pwd`

# ファイル名から拡張子を取り除いたものを取得

file=`echo $1 | sed -e 's/\.md//'`

# 指定されたmarkdownがあるディレクトリの絶対パスを取得

dirpath=$(cd $(dirname $1); pwd)

# いろいろな設定ファイルがある~/markdownに移動

cd ~/markdown

# pandocでtexファイルを生成

pandoc -d make.yaml \

--bibliography=${dirpath}/references.bib \

--resource-path=${dirpath} \

--cite \

--csl=sist02 \

-f markdown+hard_line_breaks \

${dirpath}/${file}.md \

-o ${dirpath}/${file}.tex

# もとのディレクトリに戻る

cd $origdir

# texファイルからいらない部分を消す

sed -i -e 's/\\vadjust pre{$.*$}%/\1/' ${file}.tex

# コンパイルする

lualatex ${file}.tex

}

使い方

準備:
上記コマンドを.bashrcや、.bashrcでsourceを使って読み込ませる別ファイル等に記載し、読み込ませます。
mdファイル、references.bib、画像等のディレクトリについて:
どこでも構いませんが、
- hoge.md
- references.bib
- 画像または画像が入ったディレクトリ
  は同じ位置に置いてください(画像に関してはresource-pathでmdファイルと同じ階層以下を指定しているので)
実行方法
1. mdtopdf hoge.mdと実行します
2. hoge.mdと同じ場所にhoge.pdfが生成されます。

Markdownの書き方

基本はMarkdownなのですが、一部専用の書き方を行います。

冒頭について

PandocでTitleやAuthorをつけると自動でいい感じにタイトルや著者名をやってくれるのですが、

(これはWord)

こういうことをしたいので、自作します。

yamlで二段組を指定していますが、ここは一段組になるため、\twocolumn[]で囲って一段組にします。

\twocolumn[
\begin{flushleft}
2021年度卒業研究概要\\
\vskip\baselineskip
\end{flushleft}

\begin{center}
\fontsize{14pt}{11pt}\selectfont
ここにタイトル
\vskip\baselineskip
\end{center}

\begin{flushright}
美しい時代へ 研究室\\
0000000 五島 慶太\\
\end{flushright}
\vskip\baselineskip
]

\twocolumn[

\begin{flushleft}

2021年度卒業研究概要\\

\vskip\baselineskip

\end{flushleft}

\begin{center}

\fontsize{14pt}{11pt}\selectfont

ここにタイトル

\vskip\baselineskip

\end{center}

\begin{flushright}

美しい時代へ研究室\\

0000000 五島慶太\\

\end{flushright}

\vskip\baselineskip

]

(出力したPDF)

こんな感じです。

キャプション・参照について

画像

画像に関しては、

![画像の説明](img/hoge.jpg){#fig:識別名}

1	![画像の説明](img/hoge.jpg){#fig:識別名}

と挿入し、参照するときは

〇〇を[@fig:識別名]に示す。

1	〇〇を[@fig:識別名]に示す。

と記述することで行なえます。

参考文献参照

references.bibには以下のように記入します。(これはURLの例です。BibTex形式なので調べるとたくさん出てきます。)

@misc{tcu-namechange:online,
author = {学校法人 五島育英会},
title = {武蔵工業大学の名称変更並びにこれに伴う設置学校の名称変更について},
url = {http://goto-ikuei.ac.jp/01topics/2007/files/080314-TCU-release1.pdf},
year = {2008},
month = {3},
language = {ja},
urldate = {2021-12-01},
}

@misc{tcu-namechange:online,

author = {学校法人五島育英会},

title = {武蔵工業大学の名称変更並びにこれに伴う設置学校の名称変更について},

url = {http://goto-ikuei.ac.jp/01topics/2007/files/080314-TCU-release1.pdf},

year = {2008},

month = {3},

language = {ja},

urldate = {2021-12-01},

}

Markdownにはこのように参照させます。

武蔵工業大学は平成21年4月より武蔵工業大学へと名称変更を行った[@tcu-namechange:online].

1 2	武蔵工業大学は平成21年4月より武蔵工業大学へと名称変更を行った[@tcu-namechange:online].

実演

Markdown

\twocolumn[
\begin{flushleft}
2021年度卒業研究概要\\
\vskip\baselineskip
\end{flushleft}

\begin{center}
\fontsize{14pt}{10.5pt}\selectfont
ここにはタイトル
\vskip\baselineskip
\end{center}

\begin{flushright}
東急グループ\\
五島慶太\\
\end{flushright}
\vskip\baselineskip
]

# はじめに

こんにちは．にゃーん

![楽しいインターネットのイラスト](img/internet_heiwa.png){#fig:インターネット平和}

インターネットのあるべき姿を[@fig:インターネット平和]に示す．
これはとても平和である．
武蔵工業大学は平成21年4月より武蔵工業大学へと名称変更を行った[@tcu-namechange:online]．
他にはこんな感じ[@kizi-rei]．

# 吾輩は猫である

## 最初のところ

吾輩わがはいは猫である。名前はまだ無い。
(略)

## 続き

ようやくの思いで笹原を這い出すと向うに大きな池がある。
(略)

# 参考文献