動機
AsciiDocで技術文書を書いていると、
- 図1-1
- 図1-2
- 表2-1
のような章番号付きキャプションを付けたいことがあります。
Asciidoctorにはキャプション番号の機能がありますが、章ごとに番号をリセットしたり、「図1-1」「表2-3」のような形式で表示したりするには工夫が必要でした。
そこで Asciidoctor Numbered Captions を開発しました。
-
GitHub
https://github.com/YoshihideShirai/asciidoctor-numbered-captions-vscode -
VS Code Marketplace
https://marketplace.visualstudio.com/items?itemName=YoshihideShirai.asciidoctor-numbered-captions-vscode
できること
例えば次のようなAsciiDocを書きます。
= Sample Document
== はじめに
.システム構成
image::system.png[]
.設定一覧
|===
|項目 |値
|Mode
|Auto
|===
プレビューでは次のように表示されます。
図1-1 システム構成
表1-1 設定一覧
さらに章が変わると、自動的に
図2-1
表2-1
となり、章単位で番号がリセットされます。
特徴
この拡張には次のような特徴があります。
- VS CodeのAsciiDocプレビューでそのまま利用可能
- Asciidoctor.js Extensionとして実装
- Asciidoctor.js 4に対応
- JavaScriptのみで実装
- 図・表・例・リストなどキャプションを持つブロックに対応
この拡張が生まれた経緯
実は、この拡張には少し裏話があります。
以前のAsciidoctor VS Code拡張では、外部から独自のAsciidoctor Extensionを追加する仕組みがありませんでした。
私は「VS Code拡張を改造しなくても、外部拡張としてAsciidoctor Extensionを登録できる仕組みがあると、多くの拡張をコミュニティで開発できるようになる」と考え、Extension Registration API を提案しました。
コミュニティで議論を重ねた結果、このAPIは正式に採用されました。
そして、そのAPIを活用した実践例として開発したのが Asciidoctor Numbered Captions です。
OSSへの提案が実際の機能となり、その上で動く拡張機能まで公開できたことは、開発者として非常に嬉しい経験でした。
実装について
実装はAsciidoctor.jsのTreeProcessorを利用しています。
処理内容は比較的シンプルで、
- 現在の章番号を取得
- ブロック種別ごとにカウンターを管理
- キャプションを書き換える
という流れです。
Asciidoctor.js 4ではExtension APIも整理され、JavaScriptだけでも拡張を書きやすくなったと感じました。
これからAsciidoctor Extensionを書いてみたい方にとっても、参考になるサンプルになれば嬉しいです。
今後
今回作成したのは「章番号付きキャプション」という比較的小さな機能ですが、新しいExtension Registration APIによって、今後はさらにさまざまな拡張が実現できるようになります。
例えば、
- 独自マクロ
- 独自ブロック
- 独自インラインマクロ
- ドキュメント変換
- プレビュー専用の機能追加
なども、VS Code本体を変更することなく実装できます。
今回の拡張が、そのようなAsciidoctor拡張開発の第一歩になれば嬉しく思います。
おわりに
今回の開発では、自分が提案したAPIを使って拡張機能を実装・公開するところまで実現できました。
OSSでは「利用者」として参加するだけでなく、「もっとこうしたら便利になる」という提案が、コミュニティの議論を経て実際の機能になることがあります。
今回の経験は、その面白さを改めて実感する機会になりました。
AsciiDocを使っている方、Asciidoctor.jsで拡張を書いてみたい方は、ぜひ試してみてください。
IssueやPull Requestも歓迎です！