マークダウンで論文を書いてみる （準備編）

マークダウンとは

マークダウン言語 (Markdown)は文書を構造的に記述するための言語です。テキスト形式で書いた文書に特定の記号を使って見出し、箇条書きやフォントの修飾を指定することできます。

どんなテキスト・エディタでも書くことができますが、プログラミング言語に使うテキスト・エディタの多くにマークダウンのプレビュー機能があるので、完成形を見ながら書くことができます。VS Code、Atom、Sublime Textなどがテキスト・エディタの一例です。

最近メモ用にマークダウンを使うことが多いく、特にプログラミングをする環境ではテキスト・エディタを開いているので、MS Wordなど別のプログラムを立ち上げずに使えるので便利です。MS Wordのように多機能ではない分、軽くてシンプルで使いやすいです。MS Wordは最近開くたびに職場のライセンス確認をするのも使いたくない一因です。

マークダウンを使って論文を書くことができると知りて調べてみることにしました。

論文を書くのに必要な機能

論文を書くのに必要な機能はそれほど多くなく、文書を作ること自体はテキスト・エディタを使ってマークダウンで十分だと思います。マークダウンの利点としてはテキスト・ベースなので軽いし、お気に入りのテキスト・エディタを使えます。例えばVS CodeとGitHubを併用すると編集履歴などのコントロールも簡単にできます。manuscript_ver12とか数字を付けてヴァージョン毎に保存する必要がなくなり、更新部分などの差分表示も可能です。

共著者に論文をレビューしてもらう時にはマークダウン形式は難しいでしょう。ジャーナルへの提出時にもMS Word形式に変換が必須になります。

今回、論文が仕上がった最終段階でマークダウン形式からMS Word形式への変換が問検証しました。併せて、共著者がMS Wordでコメントや変更した場合を想定して、MS Word形式からマークダウン形式への変換機能も試して見ました。

Pandocとは

Pandocはマークダウン、HTML, MS Word、PDFなどの種々の文書形式から別の文書形式に変換できるオープン・ソースのツールです。

Haskellというプログラミング言語でかかれていて、コマンド・ラインから操作することになります。

コンピュータの環境

Macの環境で試しましたが、コマンド・ラインの書き方などが一部違う点を除けばWindowsでもほぼ同じだと思います。

テキスト・エディタはVS Codeを使っていますが、他の機種でも大丈夫です。引用文献の挿入の仕方、マークダウン・プレビューの見え方が少し異なるかもしれません。

PandocとZoteroのインストール

Pandocと文献引用ソフト(Zotero)の二つのプログラムが必要になります。2022年01月の段階でPandoc version 2.16.2、Zotero version 5.0.97-beta.63を使っています。

Pandoc

Pandocはマークダウン形式のファイルをMS Wordの.doc(docx)形式に変換するプログラムです。他にもPDFやhtmlに変換などもできます。MacOSではHomebrewが入っている環境なら以下のコマンドでダウンロードできます。 

brew install pandoc

コマンド・ラインからでなくてもPandocのホームページからダウンロードすることもできます。

Zotero

Zoteroは文献引用に使うのソフトです。Zoteroのダウンロードや設定はこの記事を参考にしてください

Zoteroのプラグインは Better BibTeXが必要になります。設定はZoteroのpreferenceから以下の通りです 

Preference/Better BibTeX/CitationKeys
  force citation key to plain text: checked
  enable citation key search: checked
Preference/Better BibTeX/Export/QuickCopy
  Pandoc citation
  surround pandoc citation with brackets: checked
Preference/Export/item format
  Better BibTex Quick Copy

VS Codeをテキスト・エディタとして使うならVS Code Citation Picker for Zoteroが便利です。引用論文をマークダウン文書に挿入するときに使います。あとで述べますがMarkdown Extendedというエクステンションもあるといいです。

必要なファイルの準備

いくつかのファイルが必要になります。下のようなファイル構造になっています。 

User
  ├── Documents
  │       └── Manuscript
  │               ├── input.md
  │               ├── library.bib
  │               ├── custom-reference.docx
  │               ├── fig1.jpg
  |               └── pandoc_md2docs.sh
  └── Zotero
          └── styles
                  └── nature.csl
input.md

マークダウン・ファイルの雛形です。文頭の---に囲まれた部分はyaml形式で書かれたメタデータで後で述べるPandocで使われます。下のテキストをコピーしてinput.mdと保存してください。

引用文献の挿入、文字の修飾、表と図の挿入のテストも兼ねているので余計な文章や表などが入っています。 

---
title: This is the title
author:
  - Naoki Takahashi
  - Thelonius Monk
date: 01-16-2022
link-citations: false
link-bibliography: false
...

### Abstract

**strong** (**), __strong__ (__), <strong>strong</strong> (str)

*italic* (*), _italic_ (_), <em>italic</em> (em)

***str_ital*** (*), ___str_ital___ (_), <strong><em>str_ital<<em></strong> (st/em)

^13^C (^), <sup>13</sup>C (sup)

H~2~O (~), H<sub>2</sub>O (sub)

~~Not~~ (~~), <s>Not</s> (s)

<u>underline</u> (u), <ins>underline</ins> (ins)

### Introduction

Single citation is entered here
[@arifClinicallySignificantProstate2020].

### Material and Methods

Multiple citations are combined with semicolon [@arifClinicallySignificantProstate2020;
@takahashiProstateMRICharacteristics2021].

### Results

### Discussion

### Tables

Pipe method

|  Right | Left  | Default  |   Center   |
| -----: | :---- | -------- | :--------: |
| orange | apple | melon    | strawberry |
|  horse | tiger | elephant |    bear    |
|      3 | 2     | 1        |     1      |


Grid method

+--------+-------+----------+-------------+
|  Right | Left  | Default  |    Center   |
+=======:+:======+==========+:===========:+
| orange | apple | melon    | strawberry\ |
|        |       |          | blueberry   |
+--------+-------+----------+-------------+
|  horse | tiger | elephant |     bear    |
+--------+-------+----------+-------------+
|    3   | 2     | 1        |      1      |
+--------+-------+----------+-------------+

### Figures

![](figure1.jpg)

**Figure 1A** This figure shows that.

### References
library.bib

Zoteroの文献ライブラリーを.bibフォーマットで出力したファイルです。Zoteroのプラグ・インのBetter BibTeXを使って書き出します。ZoteroでLibraryもしくはCollectionを選択し、右クリックからExport Library(collection)でダウンロードできます。'keep updated'をチェックしておくとZoteroのライブラリが更新されると.bibの方も自動的に更新してくれます。

custom-reference.docx

Pandocを使ってdocxに書き換える際に使うフォーマットです。コマンド・ラインで下のコマンドを走らせるとcustom-reference.docxという文書がManuscriptのフォルダ内に書き出されます。 

cd Documents/Manuscript

pandoc
  -o custom-reference.docx
  --print-default-data-file reference.docx

custom-reference.docx をMS Wordで開くといくつかの項目が青字になっていると思います。右上のスタイルのリボンをクリックすると見出し1, 見出し２などがでてくるのと思います。変更したい見出しなどを右クリックして変更します。実際のMS Wordのテキストを変更してもスタイルは変更されないので注意してください。

fig1.jpg

論文に挿入するfigureのファイルです。なにか適当な図を保存してください。

pandoc_md2docs.sh

これはPandocを動かすファイルです。一行目はinput.mdをoutput.docxに変換させるというコマンドです。二行目以降で文献ライブラリー・引用スタイル、文書のスタイルを指定しています。下のテキストをコピーしてpandoc_md2docs.shと保存してください。 

pandoc -s input.md -o output.docx
  --bibliography=library.bib
  --csl=../../../Zotero/styles/nature.csl
  --reference-doc=custom-reference.docx
  --citeproc

ついでにこのファイルをコマンド・ラインから実行できるようにpermissionを変えておきましょう。 

chmod +x pandoc_md2docs.sh
nature.csl

これはZoteroの文献引用スタイルです。Zoteroのpreferenceからciteで引用スタイルが選択できます。nature.csl はデフォルトで入っていますが、違うスタイルを使うにはここから検索してインポートします。インポートしたファイルはZoteroのStylesフォルダに保存されます。

準備編のまとめ

準備編ではPandocとZoteroのインストール、変換に必要になるファイルを見ていきました。

マークダウンで論文-検証編に続きます。

　

最終更新日：2022年11月1日