Skip to content

Treat section titles as cross-reference targets#80

Merged
bbatsov merged 1 commit into
masterfrom
section-auto-ids
Jun 5, 2026
Merged

Treat section titles as cross-reference targets#80
bbatsov merged 1 commit into
masterfrom
section-auto-ids

Conversation

@bbatsov

@bbatsov bbatsov commented Jun 5, 2026

Copy link
Copy Markdown
Owner

Phase 1 of the Antora/xref work. Real AsciiDoc - and especially the Antora docs I maintain (rubocop/docs, cider/doc) - almost never uses explicit [[id]] anchors; references point at sections by their auto-generated id (e.g. xref:cljs/figwheel.adoc#clojure-cli-setup[] targets === Clojure CLI Setup). Until now adoc-mode only knew about explicit anchors, so none of those resolved or completed.

This generates each section's auto-id the way Asciidoctor does and feeds it into completion (<< / xref:), the xref backend (definitions + completion table), and adoc-goto-ref-label. The id style is detected automatically: a document's own :idprefix: / :idseparator: win; otherwise files inside an Antora component (an antora.yml above them) use Antora's kebab-case style (My Title -> my-title) and everything else uses Asciidoctor's default (_my_title). adoc-section-id-style forces a specific style.

The id-generation algorithm is the fiddly bit, so I validated it against the real asciidoctor CLI over a spread of titles (and a Buttercup spec does the same when asciidoctor is installed). The level-0 doctitle is excluded, and == lines inside code blocks are skipped (reusing the heading validation the nav/imenu code already does).

Next phases (separate PRs): Antora cross-file xref resolution (open xref:page.adoc#frag, complete page targets, project-wide references, include/image resources), then paste-image-from-clipboard.

  • The commits are consistent with our contribution guidelines
  • You've added tests (if possible) to cover your change(s)
  • All tests are passing (eldev test)
  • The new code is not generating bytecode or M-x checkdoc warnings
  • You've updated the changelog (if adding/changing user-visible functionality)
  • You've updated the readme (if adding/changing user-visible functionality)

Real AsciiDoc - especially Antora docs - references sections by their
auto-generated id far more than explicit [[id]] anchors. Generate each
section's id the way Asciidoctor does and feed it into completion, the
xref backend, and adoc-goto-ref-label, so a fragment like
xref:page.adoc#clojure-cli-setup resolves to its == Clojure CLI Setup
section.

The id style is detected: a document's own :idprefix:/:idseparator: win,
else files under an antora.yml use Antora's kebab-case style and the rest
use Asciidoctor's underscore default; adoc-section-id-style forces one.
The generation algorithm was validated against the asciidoctor CLI.

This is phase 1 of the Antora/xref work; cross-file resolution follows.
@bbatsov bbatsov merged commit 18a73ff into master Jun 5, 2026
8 checks passed
@bbatsov bbatsov deleted the section-auto-ids branch June 5, 2026 09:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant