Markdownで相互参照を使うならpandoc-crossref

Sotfware

LaTeXだと\labelと\refを使えばいい具合に相互参照できる（参照番号を付けてくれる）が、Markdownだとそういう記法は無い。

pandocというドキュメントコンバータを使うと、Markdown（など）の形式のドキュメントを入力にして、様々な処理を加え、Markdownや他の形式のドキュメントを出力することができる。その「様々な処理」はpandocに内蔵されたものの他、プラグインで拡張することができる。

そして、プラグインの1つにMarkdownドキュメント内での相互参照を実現するpandoc-crossrefがある。

例えば以下の様なMarkdownファイルを用意する。

はじまり

[@fig:a_image]に示す画像は特に意味が無い。

![これはイメージです](http://mirrors.creativecommons.org/presskit/logos/cc.logo.large.png){#fig:a_image}

[@eq:b_equation]はどこかで見たことがある数式である。

$$ x^2 + y^2 = 1 $$ {#eq:b_equation}

[@tbl:c_table]はただの表である。

| head1 | head2 |
|:--|:--|
| 1/1 | 1/2 |
| 2/1 | 2/2 |

: 例 {#tbl:c_table}

[@lst:d_code]は動きそうである。

```{#lst:d_code .python .numberLines caption="Pythonっぽいコード"}
import sys
print(sys.version())
print("Hello, Pandoc")
```

おわり

このファイルをpandocコマンドとpandoc-crossrefプラグインで処理し、Markdown形式で出力する。

$ pandoc -s --filter pandoc-crossref -f markdown -t markdown note.md

その結果が以下のとおり。

---
chapDelim: '.'
crossrefYaml: 'pandoc-crossref.yaml'
eqnPrefix:
- 'eq.'
- 'eqns.'
figPrefix:
- 'fig.'
- 'figs.'
figureTemplate: $$figureTitle$$ $$i$$$$titleDelim$$ $$t$$
figureTitle: Figure
listingTemplate: $$listingTitle$$ $$i$$$$titleDelim$$ $$t$$
listingTitle: Listing
lofTitle: |
    List of Figures
    ===============
lolTitle: |
    List of Listings
    ================
lotTitle: |
    List of Tables
    ==============
lstPrefix:
- 'lst.'
- 'lsts.'
rangeDelim: '-'
tableTemplate: $$tableTitle$$ $$i$$$$titleDelim$$ $$t$$
tableTitle: Table
tblPrefix:
- 'tbl.'
- 'tbls.'
titleDelim: ':'
...
はじまり

fig. 1に示す画像は特に意味が無い。

![Figure 1:
これはイメージです](http://mirrors.creativecommons.org/presskit/logos/cc.logo.large.png)

eq. 1はどこかで見たことがある数式である。

$$ x^2 + y^2 = 1 \qquad(1)$$

tbl. 1はただの表である。

  head1   head2
  ------- -------
  1/1     1/2
  2/1     2/2

  : Table 1: 例

lst. 1は動きそうである。

<div id="lst:d_code" class="listing python numberLines">

Listing 1: Pythonっぽいコード

``` {.python .numberLines}
import sys
print(sys.version())
print("Hello, Pandoc")
```

</div>

おわり

ファイル先頭に設定情報が書き込まれているところは置いておいて、元の入力Markdownで@...、#...としていたところが、参照番号に置き換わっていることがわかる。

pandocコマンドの出力をHTMLにすると、よくわかる。

日本語文章の中にfig.、eq.、tbl.、lst.というのは見た目が良くないが、これはYAMLで設定ファイルを書くことで変更できる。

figureTitle: "図 "
tableTitle: "表 "
listingTitle: "コード "
figPrefix: "図."
eqnPrefix: "式."
tblPrefix: "表."
lstPrefix: "コード."

pandocコマンド実行時に設定ファイルのパスを渡す

$ pandoc -s --filter pandoc-crossref -M "crossrefYaml=crossref_config.yaml" note.md

結果は以下のとおり。

---
chapDelim: '.'
crossrefYaml: 'crossref_config.yaml'
eqnPrefix: '式.'
figPrefix: '図.'
figureTemplate: $$figureTitle$$ $$i$$$$titleDelim$$ $$t$$
figureTitle: 図
listingTemplate: $$listingTitle$$ $$i$$$$titleDelim$$ $$t$$
listingTitle: コード
lofTitle: |
    List of Figures
    ===============
lolTitle: |
    List of Listings
    ================
lotTitle: |
    List of Tables
    ==============
lstPrefix: 'コード.'
rangeDelim: '-'
tableTemplate: $$tableTitle$$ $$i$$$$titleDelim$$ $$t$$
tableTitle: 表
tblPrefix: '表.'
titleDelim: ':'
...

はじまり

図.&#160;1に示す画像は特に意味が無い。

![図 1:
これはイメージです](http://mirrors.creativecommons.org/presskit/logos/cc.logo.large.png)

式.&#160;1はどこかで見たことがある数式である。

$$ x^2 + y^2 = 1 \qquad(1)$$

表.&#160;1はただの表である。

  head1   head2
  ------- -------
  1/1     1/2
  2/1     2/2

  : 表 1: 例

コード.&#160;1は動きそうである。

<div id="lst:d_code" class="listing python numberLines">

コード 1: Pythonっぽいコード

``` {.python .numberLines}
import sys
print(sys.version())
print("Hello, Pandoc")
```

</div>

おわり