Pandocで使えるマークダウン表現

Pandocはさまざまな文書形式間での変換を簡単に行える、汎用的なドキュメント変換ツールです。

マークダウン形式のファイルをdocxに変換するためにPandocを使ってみたのですが、マークダウンの書き方によっては思うように変換されない…といったことがありました。変換時に気をつけるべきこと、知っておくべきことがあったので、それをまとめます。

マークダウンを書く上で気をつけること

基本は公式ガイドの説明の通りなのですが、

あたりが特徴的です。

| left | center | right |
|:--------|:-------:|-------:|
| value1 | value2 | value3 |
| value4 | value5 | value6 |

:caption sample

その他の表の書き方の詳細はこちら。

通常の引用は問題ないが、引用のネストに癖がある。

普段GitHubなんかではこんな感じの書き方でネストを表現したりします。

> hoge
>> fuga

が、これだと以下のように変換されてしまいまい、ネストが表現できません。

どうやらネストするためには>と>の間にスペースが必要だったり、間に行が必要だったりするようです。

> hoge
> 
> > fuga

ただそれをやっても、Wordではネストが表現できないみたいで、上の状態だと下のように出力されます。

よってWordではネストの表現はあまり使わない方がよさそうです。

ちなみにPandocを実行する際、-f markdown_strictとオプションをつければ>>（スペースなし）も認識してくれます。
（ただ、Pandocが拡張しているマークダウン表現が使えなくなるので、使わない方がよいかなと思います。）

以下のように言語を指定しておけば、出力時にシンタックスハイライトしてくれます。

```python
def greet():
    print("Hello, Markdown!")
```

このシンタックスハイライトのカラーはいくつか用意されているので、色合いを変えられます。
デフォルトはpygmentsで、--highlight-style=tangoのように実行時に指定すればOKです。
※ハイライトさせたくなければ--no-highlightを指定

$ pandoc --list-highlight-styles
pygments
tango
espresso
zenburn
kate
monochrome
breezedark
haddock

なお、ハイライト適用対象の言語は以下のコマンドで確認できます。

$ pandoc --list-highlight-languages
abc
actionscript
ada
...

URLやメールアドレスを単純に配置しつつ、変換後にリンクとして扱いたい場合、山括弧で囲う必要があります。

<https://google.com>
<john@example.com>

またリンクのタイトルを指定する場合に、メールアドレスでは先頭にmailto:をつけないと正常なリンクとならないので注意が必要です。

[Google](https://google.com)
[Write me!](mailto:john@example.com)

脚注の表現もあります。採番も自動でやってくれるので楽に使えそうです。

これは複数行の脚注の例です[^1]。数字じゃなくてもOK[^hoge]

[^1]: これは脚注です。
    次の行も続けて説明を書けます。

[^hoge]: fuga

これはインライン脚注の例です^[インラインで脚注を記述することもできます]。

変換時に困ったことと、その対処法も載せておきます。

段落内で改行したい時、例えば以下の例だと

foo
bar

baz

fooの後に半角スペース2個置いていないと、以下のように変換されます。

fooの後に半角スペースを置いてやると、以下のように変換します。

常に後者の通り変換させたいですが、半角スペース2個を書いたりするのは面倒です。
そんな時は変換時のコマンドに-f markdown+hard_line_breaks とつけてやることで、半角スペース2個がなくとも後者のように変換してくれるようになります。

この章の後は改ページを入れたい…みたいなことがあります。
Pandocにはフィルターオプションがあり、これを使えば任意の場所に改ページを入れられます。

まずは以下のファイルをダウンロードします。
pagebreak/pagebreak.lua at main · pandoc-ext/pagebreak

これはマークダウン上の\newpageとなっている箇所を改ページしてくれるフィルターです。
なので改ページしたい箇所に挿入し、Pandoc実行時にダウンロードしたファイルを指定する形で--lua-filter pagebreak.luaとオプションをつければ実現できます。

hoge

\newpage

fuga

そもそもマークダウンの標準って何だろうと思い調べたところ、CommonMarkという仕様がありました。
シンプルさゆえに広く普及しましたが、多くの派生や方言が生まれたため、互換性の問題が課題となっていたことが背景のようです。

Pandocで使われているマークダウンは、Pandoc独自に拡張されているものがデフォルトのようですが、各方言を明示的に使うことも可能なようです。
参考: Pandoc User’s Guide 日本語版 | Markdown方言