AsciiDocの図・表に章番号付きキャプションを付けるVS Code拡張を作りました AsciiDocの図・表に章番号付きキャプションを付けるVS Code拡張を作りました

Technical writers who use AsciiDoc to produce manuals, specifications, and design documents frequently want their figures and tables to carry chapter-aware captions such as "Figure 1-1," "Figure 1-2," or "Table 2-1." A developer has released a Visual Studio Code extension intended to add exactly this kind of numbering to AsciiDoc documents, addressing a need that many authors encounter once their material grows beyond a handful of pages.

AsciiDoc is a lightweight markup language used widely for technical documentation. It resembles Markdown in spirit but offers a richer set of structural features, including admonitions, cross-references, includes, and configurable captions. The reference toolchain is Asciidoctor, a Ruby-based processor that converts AsciiDoc source into HTML, PDF, DocBook, and other formats. In Visual Studio Code, the most common way to work with the format is the AsciiDoc extension maintained by the Asciidoctor project, which provides syntax highlighting and a live preview pane.

The motivation behind the new extension lies in how Asciidoctor handles caption numbers by default. Asciidoctor can automatically prepend labels like "Figure 1" or "Table 2" to block titles, and it increments those numbers across the whole document. What it does not do conveniently, according to the author, is reset the counter at each chapter and produce the combined "chapter-and-sequence" style that many readers expect, in which the first number reflects the chapter and the second number counts items within that chapter. This compound style, written as "1-1," "1-2," and so on, is especially common in Japanese technical writing and in formal documentation standards, but it is awkward to achieve with the built-in numbering alone.

The extension appears to fill that gap by generating chapter-numbered captions for figures and tables directly within the editing environment. Rather than relying solely on Asciidoctor's runtime numbering, a tool of this kind typically scans the document structure, tracks the current chapter or section level, and assigns each figure or table a label that combines the chapter index with a per-chapter running count. Working inside VS Code has the practical advantage of keeping the numbers visible while the author writes, instead of requiring a separate build step to see how captions will appear. Readers interested in the precise behavior, such as how the extension treats nested sections or interacts with existing block titles, would need to consult the project's documentation, since implementation details vary between such tools.

It is worth noting why this is more than a cosmetic preference. Consistent, chapter-scoped numbering makes long documents easier to navigate, supports stable cross-references, and aligns with conventions used in regulated or standardized documentation, where figures and tables are often cited by chapter-relative identifiers. When numbering is sequential across an entire document, inserting a single figure early on can shift every later number, complicating reviews and revisions. Chapter-based numbering localizes those changes to one chapter, which can reduce churn in large projects.

The release fits into a broader pattern of tooling that extends AsciiDoc and similar plain-text formats for professional documentation workflows, an approach often associated with the "docs as code" movement. In that model, documentation is written in plain text, stored in version control alongside source code, and built through automated pipelines. Comparable ecosystems exist around Markdown with tools such as MkDocs and Pandoc, around reStructuredText with Sphinx, and around AsciiDoc itself with Antora for multi-repository documentation sites. Each of these stacks wrestles with the same underlying challenge of cross-references and numbering, and authors commonly reach for extensions or custom processing to match house style.

For users considering the extension, a few caveats apply. Editor-side numbering and Asciidoctor's own numbering can diverge if both are active, so it is sensible to verify how the captions render in the final output format, particularly PDF or HTML produced by a build pipeline. Behavior may also depend on how chapters and sections are marked up in the source. As with any newly published extension, prospective users are likely to benefit from checking its compatibility with their existing AsciiDoc setup, reviewing the supported syntax, and testing it on a representative document before adopting it across a larger documentation set.