Antora essential extensions

This page lists Antora extensions DevCentr / OpenShellOrg / antora-supplemental treat as essential: behavior so basic that every docs site we ship should enable it, and that we argue belongs closer to Antora core (or at least in every playbook by default).

Essential Extensions / Extensions that should be in core

Site search (@antora/lunr-extension)

Package: @antora/lunr-extension (official Antora extension)

Problem: Without Lunr, the site has no client-side full-text search. Users (and Valentus Search/Ask chrome) expect a working omnibox.

Behavior: Indexes published pages at build time and ships a browser search UI. Valentus and related themes assume Lunr (or a wrapper such as @antora-supplemental/antora-search-chat) is present.

Playbook:

antora:
  extensions:
    - require: '@antora/lunr-extension'

Install the package in the playbook repo (pnpm add -D @antora/lunr-extension). Register Lunr before any wrapper that depends on it (for example antora-search-chat).

Upstream: Lunr is already the official search extension. Treat it as mandatory site plumbing for every Antora site we publish—not optional polish.

Alias versioned component root → latest start page

Package: @antora-supplemental/alias-component-to-latest

Problem: A component with only numbered versions (0.2.0, 1.0, …) publishes under /component/0.2.0/. The bare URL /component/ 404s. Shared links and naive “open the component” navigation break.

Behavior: For each component that has no empty/version: ~ version, register a versionless alias of ROOT index.adoc (latest start page) so /component/ routes to the latest start page. Same algorithm as the official Antora extension use case.

Playbook:

antora:
  extensions:
    - require: '@antora-supplemental/alias-component-to-latest'

Upstream: This should be an opt-in core playbook key (for example urls.alias_component_to_latest: true), not a forever copy-paste extension. Antora already documents the snippet; core should own the switch.

Proposal / discussion: antora/antora#291 (closed after #314; remaining gap is bare /component/ → latest, not symbolic latest/current). Comment on that thread rather than opening a duplicate unless maintainers ask for a new issue.

Official use-case docs: Redirect from component to latest version

Related