APA引用付きで学術論文をMarkdownに一括変換する
執筆はWordで、公開はますますMarkdownで。本ガイドでは、docx論文が入ったフォルダを一括処理で変換し、図をすべて引き継ぎ、APAをはじめどんなスタイルでも正しく整形される引用で仕上げるバッチパイプラインを構築します。
構成要素は、バッチ変換ツール、pandocのciteprocエンジン、そして構造化された参考文献ファイルの3つです。引用は変換後ではなく変換前に準備が必要な唯一の部分なので、本ガイドの中盤はその部分を正しく仕上げることに多くの紙面を割きます。
下書きはWord、行き先はMarkdown
今も多くの研究者がWordで執筆しています。共同執筆者がそれを期待し、ジャーナルも受け入れ、変更履歴の記録は誰の習慣にも深く根付いているからです。しかし論文が実際にたどり着く場所は、ますます別の言語を話すようになっています。研究室のwiki、機関リポジトリ、Markdown対応のプレプリントサーバ、バージョン管理された原稿プロジェクト——どれも、gitで差分を取れ、テンプレートで解析できるプレーンテキストを求めています。
スケールするワークフローはバッチ処理です。下書きのフォルダをまるごと変換ツールに入れ、各ファイルを画像付きの.mdに変換し、最後に手で磨き上げる。1本ずつ手作業で変換していると、脚注番号はずれ、図のパスは腐っていきます。自動化によって、下書きの山と変換済みファイルの山は常に同期した状態を保てます。
バッチ変換のワークフロー
このサイトの変換ツールは、docxファイルをまとめて一度に受け付けます。各ファイルはキュー内の1つのジョブとなり、待機中、変換中、完了、あるいは理由付きの失敗という独立したステータスを持ちます。pandocエンジンはWebAssemblyとしてブラウザ内で動作するためアップロードは一切発生せず、未公開の原稿がマシンから外に出ることはありません。
キューが終わったら、すべてを1つのZIPとしてダウンロードします。中ではソース文書ごとに専用のサブディレクトリが作られ、変換されたMarkdownと、その文書の画像を収めたmediaフォルダが入っています。文書ごとの分離は論文では特に重要です。Wordファイルはどれも画像をimage1、image2から改めて採番するからです。
バッチ処理を快適にする習慣が2つあります。1つ目は、出力名はソース名から決まるので、変換前にファイル名を整えておくこと。2つ目は、オプションを調整している間は小さなバッチで試し、スポットチェックで問題ないことを確認してからフォルダ全体を流すことです。
引用こそが本当の難題である理由
見出し、表、数式はうまく変換できます。引用はできません。Wordの保存方法に原因があります。Wordの引用ツールが生成した文献リストも、文献管理ソフトから貼り付けたものも、本質的には整形済みのテキストです。文書内では正しく見えますが、元のレコードへ戻る構造化されたリンクは持っていません。
この文書を変換すると、文献リストは執筆時に有効だったスタイルのまま凍り付いた単なる段落として出力されます。投稿先が変われば、本文中の引用をすべて手作業で直す羽目になります。解決策は、変換後ではなく変換前に引用を構造化データへ移行することです。
90秒でわかるciteproc
pandocの引用エンジンはciteprocと呼ばれます。考え方はこうです。参考文献は文献ファイル、典型的には拡張子.bibのBibTeXファイルに入っており、各エントリにはsmith2020fieldのようなキーがあります。本文中ではアットマークに続けてそのキーを書き、括弧内の引用にしたいときは角括弧で囲みます。
変換時、citeprocはすべてのキーを整形済みの引用に置き換え、出力の末尾に整形済みの参考文献リストを追加します。整形ルール自体はCSLファイル、つまり小さなXMLによるスタイル記述から来ており、何千ものジャーナル向けに既成のファイルが用意されています。
これはZoteroやJabRefのような文献管理ソフトがエクスポート時に利用するのと同じ仕組みです。だからこそ一度の労力が報われます。1つの.bibファイルがあれば、今日はWord原稿を、明日はMarkdownのwikiを、1件も入力し直すことなく動かせるのです。
CSLファイルでAPA出力
スタイルファイルを指定しない場合、pandocはChicago author-dateにフォールバックします。APAにするには、公式のcitation-style-languageスタイルリポジトリからAPA 7th editionのCSLファイルをダウンロードし、文献ファイルと一緒に変換ツールに渡します。このサイトのPro引用オプションは、文献ファイルと任意のCSLスタイルを受け取り、citeprocをワーカー内で実行します。もちろんすべてブラウザ内の処理です。
結果はマニュアルと照らし合わせて確認してください。author-date形式の引用が正しい位置にあるか、参考文献リストが末尾にあるか、ページ番号がスタイルの求める場所にあるか。小さなずれはたいてい、.bibエントリの不完全さ、DOIの欠落、あるいは最新版ではない古いAPAスタイルファイルに行き着きます。
数式は無事にたどり着く
Wordはネイティブの数式をOMMLとして保存し、pandocはそれを読み取れるため、変換された論文はスクリーンショットではなく本物の数式を含みます。Markdown出力ではインライン数式をドル記号のデリミタで囲み、別行立ての数式は独立した行に配置します。LaTeX出力では対応する数式環境をそのまま生成します。
変換後に確認すべきことは2つあります。1つは、分数が1行に押し込まれた場合のようにWordでの表示が曖昧だったインライン数式。もう1つは数式の番号付けで、Markdownにはその概念がネイティブに存在しません。Markdownのプラットフォームに載せる番号付き数式は通常、変換ツールではなく公開システム側のラベル機能で扱う必要があります。
表と図で確認すべきこと
表は時間をかけて確認する価値があります。単純なグリッドはGitHubやObsidianがレンダリングできるパイプテーブルに変換されますが、セルの結合、段落の入れ子、複数行の内容を含むセルはこの構文では表現できず、pandocはそれらのプラットフォームが無視するMarkdown方言にフォールバックします。複雑な表は変換前にWordで平坦化しておきましょう。
図はキャプション付きで、画像参照とテキスト行に変換されます。通常はこれで問題ありませんが、各メディアファイルが実際にZIP内に存在するか、ブラウザが表示できないEMFやWMF形式のまま来ていないかを確認してください。それらはWordに戻ってPNGへ変換する必要があります。
自動化が及ばない範囲
挙げておくべき限界は3つあります。古い.docファイルはサポートされていないため、まず.docxとして保存し直してください。Wordが管理する文献リストはプレーンテキストのままです。移行するには、エントリを.bibファイルに打ち直すか、もともとそれを生成した文献管理ソフトからエクスポートすることになります。
また、LaTeXのジャーナルが整形済みの引用ではなくnatbibコマンドを要求する場合、citeprocの出力では間に合いません。その場合は適切なフラグを付けたコマンドラインのpandocが必要です。それ以外のすべてについては、バッチ変換と手入れの行き届いた.bibファイルがあれば、Wordの下書きから引用の生きたMarkdownまでの往復をカバーできます。