Configuration

npm

Install this extension

npm i -D @cppalliance/antora-cpp-reference-extension

Requirements

Before building the Antora playbook, make sure you have the following installed:

• 7z (Windows) or tar (Linux)

• git

Playbook

Append the following in your playbook.yaml:

antora:
  extensions:
    - require: '@cppalliance/antora-cpp-reference-extension' # 
      dependencies: # 
        - name: 'boost'
          repo: 'https://github.com/boostorg/boost.git'
          tag: 'develop'
          variable: 'BOOST_SRC_ROOT'
          system-env: 'BOOST_SRC_ROOT' # 

• <1> npm package name: @cppalliance/antora-cpp-reference-extension (required)

• <2> List of dependencies to be downloaded and extracted. The directory where these dependencies are extracted will be available to all components as an environment variable.

• <3> The name of the environment variable describing where the path can be found. If this path exists and is a valid directory, it will be used as the source root for the dependency, skipping the download and extraction steps. If this is different from variable, the extension will set the value of variable to the path where the dependency is already located.

Besides the dependencies configuration, you can also set the following options:

+-----------------------+-----------------------+-----------------------+ | Option | Description | Default | +-----------------------+-----------------------+-----------------------+ | version | A semver range that | * | | | specifies the version | | | | of MrDocs to use. | | +-----------------------+-----------------------+-----------------------+ | allow-master | If true, the | true | | | extension will allow | | | | the use of the | | | | master branch for | | | | MrDocs if version | | | | is *. | | +-----------------------+-----------------------+-----------------------+ | allow-develop | If true, the | true | | | extension will allow | | | | the use of the | | | | develop branch for | | | | MrDocs if version | | | | is *. | | +-----------------------+-----------------------+-----------------------+ | module | Antora module that | reference | | | will receive the | | | | generated pages | | | | (modu | | | | les/<module>/pages). | | +-----------------------+-----------------------+-----------------------+ | auto-base-url | When | false | | | 'true, the extens | | | | ion tries to override | | | | MrDocs’ `base-url | | | | with a verified | | | | GitHub blob URL (see | | | | "Auto base URL | | | | detection"). Antora | | | | forwards kebab-case | | | | options to the | | | | extension as | | | | camelCase | | | | (autoBaseUrl). | | +-----------------------+-----------------------+-----------------------+ | breadcrumbs | When true, the | false | | | extension synthesizes | | | | breadcrumbs for | | | | generated reference | | | | pages without adding | | | | them to the | | | | navigation menu. | | +-----------------------+-----------------------+-----------------------+ | skip | When true, the | false | | | extension skips | | | | MrDocs and writes a | | | | placeholder | | | | | | | | reference:index.adoc | | | | per component so | | | | navigation | | | | cross-references | | | | still resolve. See | | | | "Skipping reference | | | | generation" below | | | | for the CLI flag and | | | | environment variable | | | | equivalents. | | +-----------------------+-----------------------+-----------------------+

Components

Components that will include reference documentation should set the path of the MrDocs configuration file. Append following in your antora.yaml:

ext:
  cpp-reference:
    config: doc/mrdocs.yml # 
    module: api-ref        # 

• <1> The path to the MrDocs configuration file relative to the worktree.

• <2> (Optional) Override the Antora module used for the generated pages. If omitted the component inherits the module set at the playbook level (or reference when neither level specifies a value).

For more information about MrDocs, see https://www.mrdocs.com/docs

References in the component

To include links to the reference module, the prefix xref:reference: should be used.

You would usually include a link to the main reference page in the component's nav.adoc:

* xref:reference:index.adoc[Reference]

Coordinating with the tagfiles extension

When the tagfiles extension (https://github.com/cppalliance/antora-cpp-tagfiles-extension) is also listed in your playbook, the reference tagfile is registered automatically and picked up within the same Antora run---even if you change the module name.

antora:
  extensions:
    - require: '@cppalliance/antora-cpp-reference-extension'
    - require: '@cppalliance/antora-cpp-tagfiles-extension'

With this configuration, you don't need to copy tagfiles into your repository or commit them to source control to satisfy cpp: macros.

Auto base URL detection

Set auto-base-url: true to let the extension compute --base-url= dynamically instead of hard-coding it inside each mrdocs.yml. The feature is opt-in and only supports github.com remotes for now. Enable it globally or per collector:

antora:
  extensions:
    - require: '@cppalliance/antora-cpp-reference-extension'
      auto-base-url: true

ext:
  cpp-reference:
    config: doc/mrdocs.yml
    auto-base-url: true

When active, the extension gathers hints in priority order:

1. GitHub Actions pull-request metadata (head repository, commit, and branch) via GITHUB_* variables and the event payload referenced by GITHUB_EVENT_PATH.

2. Standard GitHub Actions push metadata such as GITHUB_REPOSITORY, GITHUB_SHA, and GITHUB_REF_NAME.

3. Optional local overrides (CPPREF_GITHUB_REPOSITORY, CPPREF_GITHUB_SHA, CPPREF_GITHUB_REF, CPPREF_GITHUB_SERVER_URL) so you can reproduce the CI environment on a workstation.

4. The local git worktree (current commit/branch plus the origin remote URL).

Every candidate is validated with git ls-remote before we emit --base-url=…. If git or the network is unavailable, or if no verified GitHub reference is found, the extension leaves the original base-url untouched. Non-GitHub hosts automatically fall back to the existing behavior.

Synthetic breadcrumbs

Set breadcrumbs: true when you want the extension to derive parent/child relationships directly from the generated MrDocs directory layout.

The extension follows a deterministic procedure to build the breadcrumb trail:

1. Immediately after each MrDocs run, every emitted .adoc is recorded alongside its component, version, and module. Both foo/index.adoc and foo.adoc variants are tracked so namespace folders and leaf pages are distinguishable.

2. During Antora's contentClassified event we match each virtual page (page.src.relative) against the recorded set, gather ancestor directories, and look for their corresponding index.adoc (folder entry) or *.adoc (leaf entry). This produces an ordered list such as [Reference → math → geometry → bounding_box].

3. Each breadcrumb entry is given the canonical Antora URL (/component/module/path.html) and marked as urlType: internal, so the default UI renders them as clickable links without any additional wiring.

This approach works without creating a nav file because Antora's UI templates already consult page.breadcrumbs. By populating that array ourselves---after the content catalog is built but before page composition---we can describe the hierarchy while leaving the sidebar untouched. End users still control their nav files for the main documentation tree, and reference-only modules avoid shipping a 10,000-line nav just to obtain breadcrumbs.

Because the algorithm infers relationships from directories, keep the standard MrDocs layout intact (each namespace/class directory should contain an index.adoc).

Skipping reference generation

Reference generation is a slow step in this extension's build path. That cost is wasted when you're iterating on prose pages or previewing a pull request that doesn't touch the public API.

Skip mode short-circuits the extension: MrDocs doesn't run, and a one-line placeholder reference:index.adoc is written per component so existing xref:reference:index.adoc[] macros (typically from your nav.adoc) still resolve. Don't enable it in CI or for published deployments; the placeholder is not a substitute for the real reference.

Any one of these three signals turns skip mode on:

• skip: true on the extension entry in your playbook --- best for a dedicated preview playbook checked in next to the production one.

• --attribute skip-cpp-reference on the antora CLI --- best for one-off invocations; append =false to force the flag off.

• ANTORA_SKIP_CPP_REFERENCE=1 in the environment --- best for IDE run configurations and make targets. Any non-empty value other than 0, false, no, or off enables.

If more than one signal is set, the placeholder lists every active source and the undo step for each, so you don't disable one and find skip mode still on from another.

Example

The example directory contains an example project with a component that uses the extension.