Skip to content

fix: honor the Antora prompt setting and keep the content catalog alive - #1167

Merged
ggrossetie merged 1 commit into
asciidoctor:mainfrom
ggrossetie:fix/antora-support-followups
Jul 15, 2026
Merged

fix: honor the Antora prompt setting and keep the content catalog alive#1167
ggrossetie merged 1 commit into
asciidoctor:mainfrom
ggrossetie:fix/antora-support-followups

Conversation

@ggrossetie

Copy link
Copy Markdown
Member
  • asciidoc.antora.showEnableAntoraPrompt was declared and documented but never read, so it had no effect. It is now honoured and the prompt becomes opt-in: the check runs before anything else, so with the prompt disabled (the default) opening documents no longer triggers the antora.yml file system lookup at all, and the setting can be flipped mid-session without reloading the window.
  • The very first document never triggered the prompt: the document-open listener is registered during activation, but the document whose opening activates the extension fires that event before the listener exists — so a session where a single Antora page was opened never showed the prompt. The already-open documents are now scanned at activation.
  • "Enable Antora support in this workspace" now registers the gated features immediately (the { attributes completion) instead of after a window reload; registration is idempotent (prompt + command cannot stack duplicate providers) and "Disable Antora support in this workspace" tears them down symmetrically.
  • A single collision no longer kills the whole catalog. Two antora.yml files declaring the same component name and version (a clone and a copy of the same component, or overlapping folders in a multi-root workspace) made the classifier throw Duplicate version detected, and an unquoted version: 2.0 (a YAML number) made it throw as well; either failure silently disabled every Antora feature (resource id completion, go to definition, preview resolution) for all components. Duplicated antora.yml URIs are now deduplicated, entries sharing a component name and version are merged before classification — first descriptor wins, files deduplicated by their path within the component, mirroring Antora's own aggregator — and a non-string version is coerced to a string.
  • Read the antora.yml bytes explicitly as UTF-8 when building the catalog: yaml.load was handed the raw Uint8Array (the pre-existing TS error in buildAntoraConfigs) and only worked because the desktop host returns a Buffer whose toString decodes UTF-8; on any other host the implicit String() coercion produces a comma-separated byte string.
  • Clarify the "remote content sources" limitation on the Antora page: it refers to content sources an Antora playbook would fetch from remote git repositories, not to remote development setups such as VS Code Remote - SSH (there the extension runs on the remote host, so workspace files count as local). Also document that the prompt is opt-in through asciidoc.antora.showEnableAntoraPrompt.

Follow-ups to a 4.0 pre-release user report about the "enable Antora
support?" prompt and Antora resource id completion.

Prompt:

- The `asciidoc.antora.showEnableAntoraPrompt` setting was declared and
  documented but never read, so it had no effect. It is now honoured and
  the prompt becomes opt-in: the check runs before anything else, so with
  the prompt disabled (the default) opening documents no longer triggers
  the antora.yml file system lookup at all, and the setting can be
  flipped mid-session without reloading the window.
- The prompt listened to document-open events registered during
  activation, but the very document whose opening activates the extension
  fires that event before the listener exists, so a session where a
  single Antora page was opened never showed the prompt. The already-open
  documents are now scanned at activation.
- The "Enable Antora support in this workspace" command now registers the
  Antora-gated features (the `{` attributes completion) immediately
  instead of after a window reload; registration is idempotent and the
  "Disable" command tears the features down symmetrically.

Content catalog:

- Two antora.yml files declaring the same component name and version
  (a clone and a copy, or overlapping multi-root folders) made the
  classifier throw `Duplicate version detected`, and an unquoted
  `version: 2.0` (a YAML number) made it throw as well; either failure
  took the whole catalog down and silently disabled every Antora feature.
  Duplicated antora.yml URIs are now deduplicated, entries sharing a
  component name and version are merged before classification (mirroring
  Antora's own aggregator), and a non-string version is coerced.
- Read the antora.yml bytes explicitly as UTF-8 when building the
  catalog: `yaml.load` was handed the raw Uint8Array and only worked
  because the desktop host returns a Buffer whose toString decodes UTF-8;
  on any other host the implicit String() coercion produces garbage.

Docs: the "remote content sources" limitation refers to content sources
an Antora playbook would fetch from remote git repositories, not to
remote development setups such as VS Code Remote - SSH.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ggrossetie
ggrossetie merged commit 7d76682 into asciidoctor:main Jul 15, 2026
2 checks passed
@ggrossetie
ggrossetie deleted the fix/antora-support-followups branch July 15, 2026 11:43
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