@antora/atlas-extension

Antora Atlas Extension

The Antora Atlas Extension (Antora Atlas) manages references across discrete runs of Antora through the use of a site manifest.

⚠️ WARNING
This extension is currently ALPHA software! That means this extension experimental and likely to change without notice. You’re welcome to test it and give feedback, but take caution when relying on it in a production site. If you’re looking for the precursor release line, which is a stable release line for users of this extension’s predecessor, refer to the v0.0.x branch.

Overview

The purpose of the extension is to support site composition (i.e., sharding) and partial builds.

When this extension is enabled, Antora will create and publish a site manifest to the root of the site. The site manifest is a JSON file named site-manifest.json. This file contains reference information for all pages and aliases in the site, grouped by component then version. This information is intended to be used to resolve references to these pages from a discrete site (e.g., an archive site) or partial build (only select components and/or versions).

When this extension is enabled and either the primary site manifest URL or primary site URL is specified, Antora will read the site manifest and import all the component versions and pages into the content catalog of the current site. If the location of the site manifest is remote, Antora will download and cache it. The virtual files the extension creates are merely stubs, enough to allow Antora to resolve references to them through their resource ID. The target URL of these files are external, pointing to the location in the published site rather than relative to the current site. Internally, Antora is able to distinguish between local and imported resources by the presence of the site property.

Prerequisites

In order to use this extension, you must be using Node.js 16 and Antora 3.2.0-alpha.2 or newer. The following instructions assume you’ve already set up an Antora playbook file (i.e., antora-playbook.yml) to build your site.

To learn about using extensions with Antora, see the Antora extension documentation.

Install

Use the following command to install the extension into your Antora playbook project:

$ npm i @antora/atlas-extension

Register

Open your Antora playbook file and register the extension as an entry in the antora.extensions key. If this key doesn’t yet exist in your playbook, first create it.

antora-playbook.yml

antora:
  extensions:
  - '@antora/atlas-extension'

Configure

There’s no configuration necessary to export the site manifest. That happens automatically. If the site.url key is set in the playbook, it will be included in the site manifest. You can change the name of the manifest file using the site-manifest-path attribute, though it’s not recommended.

In order to import a site manifest, you must specify either the primary-site-url or primary-site-manifest-url attributes in the Antora playbook. Assuming the primary site was published using this extension, you can specify the URL to that site.

asciidoc:
  attributes:
    primary-site-url: https://docs.example.org

The extension will then look for the site manifest at https://docs.example.org/site-manifest.json, download it, and cache it. Antora will attempt to download it again only if the --fetch option is specified (or runtime.fetch=true in the playbook).

Alternately, you can specify the URL or path of the site manifest to import. If the value is a URL, Antora will download it. Otherwise, it will read it from the location specified.

asciidoc:
  attributes:
    primary-site-manifest-url: ./primary-site-manifest.json

If the manifest URL ends with .gz, Antora will gunzip the file.

When the extension exports the manifest, it will exclude any resources that were previously imported.

Copyright and License

Copyright (C) 2022-present by OpenDevise Inc. and the individual contributors to this project.

Use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0).