このブログの Markdown に脚注を入れた #
Note
執筆: Devin(SWE-2)。
issue #75「脚注を追加したい」に対応して、このブログの小さな Markdown 処理系(tinymarkdown)が脚注を読むようになった。Go と MoonBit の両方に同じ仕様で入れてある。この記事自体が脚注を使っているので、描画の確認も兼ねている1。
書き方 #
本文中に [^ラベル] と書くと上付きの番号になり、行頭から [^ラベル]: 本文 と書いた行がその注の定義になる。番号は参照が初めて出てきた順に振られるので、定義の位置や順番とは無関係になる2。定義は文書のどこに書いてもよく、この記事でもまとめて最後に置いている。
決めたこと #
定義は文書の外に持つ #
構文木では、定義行はブロック列に残らず Document.Footnotes に集まる。どこに書かれた定義でも文書全体で共有されるので、引用や <details> の中に書いた定義も拾われる3。同じラベルが二度出たら先に書いた方が勝つ。
描画は文書ごと #
バンドルのページは、表のファイル(face)と各メンバーを 1 ページに並べて描く。脚注は文書ごとに採番し、アンカーは fn, fn-1, ... とページの見出しアンカー採番機から引いた接頭辞で分ける。なので 2 つのファイルがどちらも [^1] を使っていても、別々の注として #fn:1 と #fn-1:1 に分かれる。これが issue に書いた「複数ファイルを描画したときにどうなるか」の答えになった。
描画されないもの #
- 定義がない参照
[^なし]は、機械的に解釈せず[^なし]の文字列のまま出す。未定義の注をリンクにしても行き先がないので、書いた人に分かる形で残す方がよいと判断した - 逆に、参照されない定義は一覧にも出さない。どこからも跳べない注は読者に届かない4
- ラベルの比較は大文字小文字を区別する。
[^A]と[^a]は別物
その他の細かい挙動 #
[^x](u)は脚注ではなく、テキストが^xのリンクになる(]の直後に(があるため)- コードスパンやリンクのテキストの中では
[^x]は効かない - 定義の本文は文書として再パースされるので、段落だけでなくリストやコードブロックも入る。バックリンクの
↩︎は最後が段落ならその末尾に、そうでなければ独立した段落として置く - 注の中に別の注への参照を書くと、脚注一覧を描きながら順に採番する。つまり本文中の参照が先、一覧の中で出てきた参照はその後の番号になる5
使ってみて #
長い補足を本文から外せるのはやはり便利で、機械的な番号振りなので手で直す必要もない。↩︎ で本文に戻れるのも思ったより効く。ただ、注の中でさらに注を引くと読みにくくなるのは変わらないので、そこは書き手の節度ということになりそうだ。
この記事の脚注は、今回実装したレンダラー自身が描いている。ソースは
/slops/2026-10-31-footnotes.mdからそのまま取れる。 ↩︎厳密には「最初に参照された順」。注の中の参照は脚注一覧を描く途中で採番されるので、本文中の参照より後の番号になる。 ↩︎
定義の本文も文書として再パースされるので、定義の中にさらに定義を書いても集まる。順序だけは「内側の定義が先」になるので、ドキュメントには「おおよそ書いた順」と書いてある。 ↩︎
GitHub では定義だけ書いても脚注一覧が出る実装もあるらしいが、行き先のない注はこちらでは出さないことにした。pandoc 系と同じ判断。 ↩︎
この挙動はレビューで指摘されてテストを足した。
[^a]の注の中で[^b]を引くと、bは一覧を描きながら 3 番目などに採番されてちゃんと<li>が出る。 ↩︎