pandocでmarkdown形式ファイルからwordドキュメント(*.docx)を作成する

こんにちは、DI部の岩澤です。

最近は何か書く時にはmarkdownでサクサク書いているのですが、たまにひな形を参考にwordドキュメントを書いてほしいと要望されたります。
markdownからひな形のスタイルに合わせつつドキュメントが作成できたら便利だなーと探したところ、ちょうどよいpandocというツールを見つけましたので、ここでご紹介したいと思います。

確認環境

  • pandoc (version 2.5)
  • word 2010
  • windows 10

pandocについて

Pandoc ユーザーズガイド 日本語版 - Japanese Pandoc User's Association

Pandocは Haskell で書かれたライブラリおよびコマンドラインツールであり、 あるマークアップ形式で書かれた文書を別の形式へ変換するものです。

このツールを使えばmarkdownやHTMLで書いたものを別のマークアップ形式やPDF、wordドキュメントなどに変換することができます。
今回はmarkdown形式からwordドキュメントに変換してみます。

pandocの入手

以下のURLから入手することができます。
Pandoc - Installing pandoc

補足:
mac環境ならばbrewで簡単にインストールすることができます。

$ brew install pandoc

早速変換してみる

pandocを使ったmarkdown->docx変換は以下の手順で行います。

  1. markdownファイルの用意
  2. 参照ファイルの用意
  3. 変換処理の実行

1.markdownファイルの準備

当然ですがmarkdownで書かれたファイルを準備する必要があります。

markdown記法といっても色々あるわけですが、pandocは複数の記法に対応しています。

フォーマット名 対応するスタイル
commonmark CommonMark Markdown
gfm GitHub-Flavored Markdown
markdown pandoc拡張のMarkdown
markdown_mmd MultiMarkdown
markdown_phpextra PHP Markdown Extra
markdown_strict originalの拡張なしのMarkdown

また、各フォーマットをベースとして拡張を追加や削除することもできます。
※入力ファイルフォーマットのオプションにて、フォーマット名に続いて「+拡張名」で拡張を追加、「-拡張名」で拡張を削除できます。

多数の拡張があるため、ここでは以下によく使うものやひっかかりやすいものについて記載しておきます。

ヘッダと見出し

wordドキュメントでは、ヘッダ1~9が見出し1~見出し9スタイルに変換されます。
9まで行くとちょっと#の数多い
なおpandoc拡張として、最初の行以外には前に空行が必要となっています(blank_before_header拡張)。

# 見出し1に対応
本文  

## 見出し2に対応
本文  

### 見出し3に対応
本文  

#### 見出し4に対応
本文  
(中略)  

######### 見出し9に対応
本文  

ヘッダへの属性付与と内部リンク

ヘッダに属性を付与し、それを指定した内部リンクを作成することができます。

# 見出しその1 {#header1}
本文  

## 見出しその2 {#header2}
...  
(中略)  
...  

これについては[見出しその2](#header2)を参照してください。  

脚注

脚注を記載することができます。脚注の内容を記述するには前後にスペースを空ける必要があります。
wordドキュメントでは、脚注文字列スタイルに変換されます。

脚注のサンプル[^1]です。

[^1]:脚注の内容を記載するには前後に空行が必要です。

間に脚注の内容を書いてもちゃんと判別してくれるので便利です。

改行

末尾にスペース2つで強制改行となります。
このとき、段落替えではなく改行(shiftキーを押しながらReturn)に変換されます。

リスト

記号付きリストや順序付きリストを作成することができます。 wordドキュメントでは、どちらもConpactスタイルに変換されます。

* 記号*か+か-を先頭につける。テキストとの間にはスペース
* 記号*か+か-を先頭につける。テキストとの間にはスペース
    + インデントさせる場合は4つスペース
        + さらにインデントさせる場合は8つスペース

1. 数字,ピリオドで順序付きリスト本文との間にはスペース
1. 数字,ピリオドで順序付きリスト本文との間にはスペース

テーブル

テーブルの記述方法は4種類ありますが、グリッドテーブルあたりがおすすめです。

テーブルの前には空行が必要です。

+---------------+---------------+--------------------+
| 名称          | 金額          | Advantages          |
+:=============:+==============:+:===================+
| お茶          | 2000円        | - 名産品            |
|               |               | - 新茶             |
+---------------+---------------+--------------------+
| お水          | 130円         | - 天然水            |
+---------------+---------------+--------------------+

2.参照用のWordドキュメントを用意する

変換処理実行時にオプションとして参照ファイルを指定すると、出力するwordドキュメントのスタイルや文書プロパティ(余白、ページサイズ、ヘッダー、フッターなど)を参照ファイルに合わせることができます。
※(ドキュメントでは推奨されていませんが)既に作成済みのWordドキュメントを利用しても可能です。

一から作成する場合は、ひな形となるdocxファイルを、以下のコマンドで取得できます。

> pandoc --print-default-data-file reference.docx > reference.docx

markdownからwordドキュメント(*.docx)への変換では、主に次のスタイルを参照しますので、必要に応じて変更します。

本文
First Paragraph
Compact
見出し1~見出し9
脚注文字列
ハイパーリンク

また、ひな形をそのまま使用すると見出しにアウトライン番号が設定されていません。
番号を表示したい場合は、新しいアウトラインの定義を追加し、レベルと対応する見出しを設定する必要があります。

3.変換を行う

必要なものがそろったので、マークダウン形式で書かれたsample.mdをwordドキュメントのsample.docxへ変換してみます。

> pandoc sample.md --from=markdown --to=docx --standalone --reference-doc=reference.docx --output=sample.docx

※指定したオプションは以下の通りです

  • sample.md:元となるmarkdown形式のファイル
  • --from=markdown:入力ファイルの形式。
    ※ヘッダの前に空行が不要にしたい場合は--from=markdown-blank_before_header と記述
  • --to=docx:出力ファイルの形式。docxを指定
  • --standalone:ヘッダ・フッタを追加
  • --reference-doc=reference.docx:参照ドキュメントの指定。このファイルのスタイルと文書プロパティを参照して作成する
  • --output=sample.docx:出力ファイルの指定

変換前の内容です。

# heading1 {#p2}
heading1本文一行目

## heading2 
heading2本文

##### heading5
heading5本文  
Here is a footnote reference,[^1] and another.[^longnote]

[^1]: 脚注その1

[^longnote]: これは脚注その2に割り振られます

######### heading8
heading8本文。  

######### heading9
heading9本文。  

+---------------+---------------+--------------------+
| 名称          | 金額          | Advantages          |
+:=============:+==============:+:===================+
| お茶          | 2000円        | - 名産品            |
|               |               | - 新茶             |
+---------------+---------------+--------------------+
| お水          | 130円         | - 天然水            |
+---------------+---------------+--------------------+

[heading1へのリンク確認](#p2)  

* 記号*か+か-を先頭につける。テキストとの間にはスペース
* 記号*か+か-を先頭につける。テキストとの間にはスペース
    + インデントさせる場合は4つスペース
        + さらにインデントさせる場合は8つスペース


1. 数字,ピリオド,スペースで順序付きリスト
1. 数字,ピリオド,スペースで順序付きリスト

画像も。

![テストイメージ](test.bmp)

変換するとこんな感じで出力されます。

まとめ

以上、pandocのご紹介でした。
みなさんもこれを機会にpandocを使ってみてはいかかでしょうか?

参考文献

Pandoc - Pandoc User’s Guide
Pandoc ユーザーズガイド 日本語版 - Japanese Pandoc User's Association