Antora Atlas Extension

The Antora Atlas Extension (herein, 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.

📌 NOTE
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, it 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, it will read the site manifest and import all the component versions and pages into the content catalog of the current site. The location of the site manifest can be a local path. If the location of the site manifest is a URL, the extension 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 provided and imported resources by the presence of the site property.

Prerequisites

In order to use this extension, you must be using at least Node.js 20 and Antora 3.2.0 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 Export

There’s no configuration necessary to export the site manifest. This behavior works automatically when the extension is enabled.

You can change the name or path of the site manifest file using the site-manifest-path attribute (though not recommended when just starting out). This value is assumed to be a relative path from the root of the site Antora is publishing.

asciidoc:
  attributes:
    site-manifest-path: _site-manifest.json

If the site.url key is set in the playbook, its value is included in the site manifest.

📌 NOTE
When the site manifest is imported in sharded mode, the site manifest export is only really intended for informational and reporting purposes. It’s not a complete site manifest and thus likely not useful for import.

Configure Import

Enable

In order to import a site manifest, you must specify the primary-site-manifest-url attribute (or, more succinctly, the primary-site-url attribute) in the Antora playbook.

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

If the site was published with this extension enabled using the default configuration, you only need to specify the URL of the primary site. The extension will automatically discover the site manifest.

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

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

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

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

If the site manifest file cannot be found, the extension silently ignores the request to import it. If the manifest URL ends with .gz, Atlas will gunzip the file.

📌 NOTE
When the extension exports the manifest, it will not contain any resources that were previously imported in sharded mode.

Merge

Normally, Atlas only imports files from a component version that are not known (meaning not created from one of the content sources). The idea is that Atlas is filling in the missing parts of the site from the manifest.

If you’re using a local content source that only provides some of the files for a component version, you’ll need to request Atlas to merge any files from the site manifest that are not known. You can enable this behavior by setting the merge subkey of the import key in the extension configuration. (This is typically used for something like a lightweight home component).

antora:
  extensions:
  - require: '@antora/atlas-extension'
    import:
      merge: true

In this mode, Atlas will not replace any files in the same component version that is provided by the build. It will only append files. It will also ignore any aliases that target a provided page as the assumption is that the provided page defines the aliases.

Atlas tries to avoid creating any file conflicts when importing the missing files. However, you must understand that this functionality creates a unique situation whereby Atlas assumes that any imported files will still be provided by the next full build. Atlas cannot detect files which are set to be deleted in this case.

Import Mode

When importing files, Atlas operates in one of two modes: sharded or same site. The sharded mode is intended for a preview build, whereas same site mode is intended for a partial build (with some help from a build script).

Same site mode is activated if the primary-site-url (otherwise the url from the site manifest) matches the site URL. Otherwise, sharded mode is used.

Sharded

In sharded mode, Atlas imports files for the purpose of resolving references when only a portion of the site is built (i.e., a subset of the content sources). If a resource (such as a page) is not provided by the build, and is found in the site manifest, the reference to that resource will resolve to a URL in the primary site.

The intent of this mode is to generate a preview of a subset of the content in the site, but still have it appear like a full site.

In this mode, the sitemap, site manifest, and redirects will only contain resources that are provided by the build. That means the resulting site manifest is really only intended for informational and reporting purposes.

Same Site

In same site mode, Atlas imports files for the purpose of making a complete site, even if only a portion of the site is built (i.e., a subset of the content sources). If a resource (such as a page) is not provided by the build, and is found in the site manifest, the reference to that resource will be exactly as it would be had the resource been included in the build. In other words, it will be a same site reference.

The intent of this mode is the be able to build a subset of the content in the site, then overlay that output onto the files in the full site as a way to update it.

In this mode, the sitemap, site manifest, and redirects will be complete, just as if all content sources were included in the build. Any imported resources reflect their state from the last full build and may still differ from the content in the actual content source.

Import Mode Selection

The following table identifies how the import mode is determined based on the configuration.

The most typical way to enable same site mode is to set the site URL and the primary-site-url attribute to the same value.

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).