More than 1 year has passed since last update.

Markdown+Pandoc+Paperpileで論文を書きたい for Mac

Last updated at 2022-02-23Posted at 2022-02-17

Markdownでの論文執筆環境について，備忘録も兼ねて共有したいと思います．

（2022/02/22 追記)
pandoc-crossrefがとりあえず動いたので追記．

こんな人向け

論文を書く際，Wordは使いたくないがLaTeXもめんどくさそう．
引用リストを自動作成したり，文中での引用を簡単にしたい．
共著者に回すときや，英文校閲に出すときは，結局Wordにしないといけない．
フリーのMarkdownソフトを使ってみたが，かゆいところに手が届かない．

便利なこと

本文中でインタラクティブに論文を引用できる．
引用文献リストが自動で作成される．
数式がきれいに書ける
挿入した画像が自動で更新される
本文に反映されないコメント等を書き込める
ファイルが軽い（動作が早い）
Gitでバージョン管理ができる

概要

VS codeをエディターとして，Markdownで論文を書く．
PaperpileやZoteroなどの論文管理ソフトでbibtexファイルを作成し，Pandoc Citerを使って引用する．
Pandocとテンプレートを使って，Markdown文書をフォーマットが整ったWordファイルやpdfに変換する．

MarkdownやPandocの詳細については，より丁寧な他の記事に譲ることにします．
以下の記事がとても参考になりました．

この記事では，必要最低限の環境構築の手順と，実際に論文を書く際に得たノウハウを共有したいと思います．

論文執筆中のイメージはこのような感じです．

Markdownについて

Jupyter Notebookなどを使っている方は馴染みがあると思います．
章立てや数式の記述が簡単できれいです．
LaTeXで作成したような文書を簡単に作成することができます．
もちろんLaTeXの方が自由度は高いのですが，できることが多すぎてむしろ複雑です（個人の感想です）．
Markdownなら必要最低限のカスタマイズ性を持ちつつ，Pandocと組み合わせて使うことで簡単にWordやpdfに出力できるので，ボスがwordしか使わないという方にもおすすめです．

Paperpileについて

Paperpileは文献管理ソフトです．
有料（月300円くらい）ですが，UIがきれいなのでZoteroやMendeleyではなくPaperpileを使っています．
上の記事で紹介されているように，PaperpileにはWordプラグインがあり，Wordで本文中に引用を追加したり，文献リストを自動で作成したりと便利です．
しかし，残念ながら本文中での引用のスタイルがあまり柔軟ではなく，(Hogehoge et al. 20xx)のように，必ずカッコがついてしまいます．
また，複数の論文を引用する際などに(e.g., Hogehoge et al., 20xx; Fuga and Hoge, 20xx)のような引用もできません．
私がよく投稿する分野の雑誌では，文頭で"Hogehoge et al. (20xx) reported that ..."のような引用の仕方や，e.g., をよく使用するので，これは困ります．

ということで，Paperpileは使いつつ，Markdown，Pandoc，VScodeでうまく活用する方法を紹介します．

Bibtexファイルの自動エクスポート機能

BibTexを使うと，MarkdownでもLaTeXと同じようにエディター上でインタラクティブに引用を追加することができます．
詳しくはこちらから．

Paperpileには，登録されているすべての論文のメタデータを含むBibTexファイルを常に最新の状態でエクスポートする拡張機能があります．
この機能を使うことで，VScode上でいい感じに引用を追加することができます．

拡張機能を追加するには，画面右上の設定（歯車マーク）の，Workflows and Integrationsから，BibTex Exportという機能を選択します．
アップロード先はGitHub，Google Drive，ローカルフォルダから選ぶことができます．
今回は，Google Driveにpaperpile.bibとして保存し，パソコン版Google Driveへパスを通すようにしています．

Zoteroにも似たような機能があるとかないとか聞いたことがあるので，そちらでもいいと思います．

Pandocのインストール

Pandocを使うことで，引用リストを作成したり，Markdownファイルをwordやpdfに変換することができます．
Pandocのインストール方法は以下の記事が参考になります．

今回はHomebrewを使ってインストールしました．

brew install pandoc
brew install pandoc-crossref

citeprocは引用文献を自動で表示するのに必要になります．
（2022/02/22 追記）citeprocはhomebrewにはありませんでした．ただ動いてはいるので，pandocに内蔵されているのかもしれません．
crossrefは本文中で図や表を相互参照するのに必要なのですが，残念ながらうまく動きませんでした．
対策をご存知の方がいれば教えていただきたいです，，，
（2022/02/22 追記）バージョン違い問題は解決していませんが，とりあえずcrossrefを使った相互参照ができるようになりました．記事の最後の方に設定を追記しました．

VScodeのインストール

今回はMarkdownエディターとして，VScodeを使用しました．VScodeにしたのは，Pandoc Citerという拡張機能があったからですが，おそらくAtomでもほぼ同じようなことができると思います．

インストールは公式ページから行いました．

Markdownに関する拡張機能のインストール

VScodeで以下の拡張機能をインストールしました．

Markdown All in One
Markdown Preview Enhanced
vscode-pandoc
Pandoc Citer

LaTeXのインストール

mdファイルをpdfに変換するには，LaTeXが必要になるようです．
今回はBasicTexをインストールしました．
インストール方法は以下のリンクを参考にしました．

具体的な使い方

以上で最低限の環境構築は完了です．
以下では，具体的な使い方を説明していきます．

YAMLの設定

Markdownファイルの最初に，YAMLという情報を記載することで，使用するBibTexファイルや，cslファイル，wordやpdfのテンプレートファイルを指定できます．
前述のように，Paperpileから自動エクスポートしたBibTexファイルへのパスを通しておくと，いちいちファイルを手動で更新しなくても常に最新の文献リストを使用できます．
上下に---を入力して，その間にメタデータを記入します．

---
csl: [/Volumes/GoogleDrive/マイドライブ/hoge.csl]
bibliography: [/Volumes/GoogleDrive/マイドライブ/fuga.bib]
output: 
   word_document:
---

cslファイルは，雑誌ごとの引用のフォーマットの情報が含まれるファイルです．
cslファイルを指定することで，自動で引用のフォーマットを整えてくれます．
異なる雑誌のcslファイルを同じフォルダに保存しておくと，YAMLですぐに変更できるので，
投稿する雑誌を変える際にとても便利です．
雑誌ごとのcslファイルはZoteroやMendeleyのサイトからダウンロードできます．

ただし，Paperpileでは，同じ著者であってもBibTexでの表記が文献ごとに異なることがよくあり，そのせいで雑誌によってはたまに問題が発生します．
例えば，片方は名前がイニシャル表記で，もう片方ではフルネーム表記だったりすると，別の著者として引用される場合があります（Hogehoge et al.と引用したいのに，H. Hogehoge et al.として引用される）．
これはcslファイル自体をいじると解決します（そのうちまとめます）．

Pandoc Citerの使い方

＠を入力すると，BibTexファイルに含まれる論文がプルダウンで表示されます．
[]で囲むと(Hogehoge et al., 20xx)のように，何もつけないとHogehoge et al. (20xx)のように引用してくれます．
頭にe.g., 等をつけることもできます．
引用リストも自動で文書の最後に作成されます．
これで引用リストが間違っているとエディターに怒られる心配もありません．

It is known that ... [@hogehoge-20xx].
@fuga-20xx reported that ...
It is important to ... [e.g., @hogehoge-20xx; @hoge-20xx].

Pandoc-crossrefの設定

プレビュー上で図表番号や式番号などを自動で表示するには，Markdown Preview Enhancedの設定でフィルターにpandoc-crossrefを指定する必要があります．

Markdown Preview Enhancedの設定で，Pandoc Argumentsのところからsettings.jsonで編集をクリックし，以下のコードを追加します．

"markdown-preview-enhanced.pandocArguments": ["--filter=pandoc-crossref"],

これで，プレビュー上で図表番号などを表示することができるようになります．
ただ，PandocとPandoc-crossrefのバージョン違いは解決していないので，プレビュー画面の最上部に

WARNING: pandoc-crossref was compiled with pandoc 2.17.0.1 but is being run through　2.17.1.1. This is not supported. Strange things may (and likely will) happen silently.

という警告文は表示されたままになります．
silentlyというところが何だか怖いですが，今のところ特に不具合は起こっていません．

しかし，このままwordに変換しても相互参照は有効になりません．
wordファイルでも図表番号などを表示するには，YAMLのところにもフィルターの情報を書く必要があります．
下のような感じです．

---
output:
  word_document:
    pandoc_args: ['--filter=pandoc-crossref']
---

これで，変換したwordファイルにも反映されるようになります．
ちなみに，図表番号の前の表記や，文中で参照したときの表記もYAMLで指定できます．
下のページを参考にしてください．

Wordファイルに変換する

プレビュー画面で右クリック→Pandocを選択すると，Wordファイルが作成されます．
このままでもいいのですが，デフォルトのテンプレートがダサいので，テンプレートを自分で作成し，YAMLでpandoc_argsの--reference-doc=にパスを通しておくといい感じになります．

---
output: 
   word_document:
     pandoc_args: ['--filter=pandoc-crossref',"--reference-doc=/Volumes/GoogleDrive/マイドライブ/template.docx"]
---

Macでのテンプレートの作成方法についてはそのうち記事を書くかもしれません．
雑誌が公式に配布しているテンプレート等を指定すれば，そのまま投稿できるクオリティになります．

数式や図のキャプション，引用文献もきちんと反映されています．

pdfファイルに変換する

前述の通り，pdfに変換するにはLaTeXの環境を構築しておく必要があります．
また，YAMLで変換先をpdfに指定する必要があります．

output:
  pdf_document:
    template: /Volumes/GoogleDrive/マイドライブ/tex_template.tex
    pandoc_args: ['--filter=pandoc-crossref']

M1ではないMacだと必要なかったのですが，おそらくM1 Macの場合は，Markdown Preview Enhancedの設定でLaTeX Engineを/Library/TeX/texbin/pdflatexのようにパスで指定する必要があるようです．

あとはWordのときと同じで，プレビュー上で右クリック→Pandocでpdfに変換されます．
こちらもテンプレートを用意しておくと便利です．

その他細かい設定

数式のレンダリングが初期設定ではKaTeXだったのですが，プレビュー上で表示されませんでした．MathJaxに変更すると表示されるようになりましたが，理由はわかりません．PC環境にもよると思いますが，とりあえずメモしておきます．
こちらも理由はわかりませんが，Markdown Preview Enhancedの設定で，Pandoc Parserにチェックを入れるのが良いようです．

その他便利なVS Code拡張機能

Selection Word Count：単語の数を数えてくれます．選択部分の単語数なども数えてくれます．

他に便利なのを見つけたら，随時追加していきます．

今後の改善点

pandoc-crossrefはなんとか動いてくれていますが，バージョン違い問題は解決していません．とりあえず，アップデートされるのを待とうと思います．
Markdownは表作成が弱いと個人的に思っているので，何かしらの拡張機能を使った方がいいかと思っています．Wordみたいな感じで表を作成できると完璧なのですが．．．
この記事の最初にgitでバージョン管理ができると書きましたが，筆者はgitのことをよくわかっていないので現状使っていません．使いこなせればもっと便利になる気がします（勉強します．．．）．
Markdownの仕様上，epsやpdfなどのベクター画像は挿入できないようです．残念．

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up