Spring.io Antora Extensions

This library provides Antora extensions that support the Spring documentation.

Prerequisites

In order to use this extension, you must have Node.js 16 or higher installed on your machine. These extensions are intended to be used with Antora. Be sure to register them as Antora extensions in your playbook, not as AsciiDoc extensions.

Use the following command to install the @springio/antora-extensions package into your project:

$ npm i @springio/antora-extensions

Extensions

This section documents the Antora extensions that are provided by this library and how to configure them.

antora-extensions

require name: @springio/antora-extensions

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

This extension applies the recommended Antora Extensions. It applies the following extensions in the proper order:

• _override_navigation_builder_extension
• Set Algolia Env
• Partial Build
• @antora/atlas-extension
• Latest Version
• Collector Cache Config
• @antora/collector-extension
• Root Component
• Root Attachments
• Static Page

The extension accepts the following configuration options:

• root_component_name
  The property for Root Component extension.

Example:

antora:
  extensions:
    - require: '@springio/antora-extensions'
      root_component_name: 'security'

This is the equivalent of:

antora:
  extensions:
    - require: '@springio/antora-extensions/override-navigation-builder-extension'
    - require: '@springio/antora-extensions/set-algolia-env-extension'
    - require: '@springio/antora-extensions/partial-build-extension'
    - require: '@antora/atlas-extension'
    - require: '@springio/antora-extensions/latest-version-extension'
    - require: '@springio/antora-extensions/inject-collector-cache-config-extension'
    - require: '@antora/collector-extension'
    - require: '@springio/antora-extensions/root-component-extension'
      root_component_name: 'vault'
    - require: '@springio/antora-extensions/root-attachments-extension'

Set Algolia Env

require name: @springio/antora-extensions/set-algolia-env-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

This extension sets the Algolia environment variables to enable search.

Collector Cache Config

require name: @springio/antora-extensions/inject-collector-cache-config-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

This extension caches the scan directory from the collector extension. If no cache exists locally, it will attempt to download the cache from site.url found in the playbook or base_cache_url configured for the extension. If no cache can be downloaded, then it will zip up the scan directory and place it in build/antora/inject-collector-cache-config-extension/.cache

The extension accepts the following configuration options:

• base_cache_url (optional)
  The base url for looking up cache entries. The default is the site.url + '.cache'

Latest Version

require name: @springio/antora-extensions/latest-version-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

This extension can ensure that old tags are no longer built to prevent the builds from becoming too large and so that very old tags do not need to build (which might eventually become unstable). The extension ensures all branches continue to build. It will remove all old patch releases by preserving the largest patch for each major.minor segment of a tag in the format of ${major}.${minor}.${patch} or v${major}.${minor}.${patch}.

The extension also maps the latest release to a URL that leverages only the ${major}.${minor} segments and the latest SNAPSHOT to a URL of ${major}.${minor}-SNAPSHOT.

📌 NOTE
Filtering is intentionally performed on the tags rather than versions because the Spring team calculates versions by extracting the information from the Java based build. The amount of time to calculate the version is small, but adds up with lots of tags, and we’d like to avoid this computational cost on tags that are not being used.

override-navigation-builder-extension

require name: @springio/antora-extensions/override-navigation-builder-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

The purpose of this extension is override the navigation builder to work around https://gitlab.com/antora/antora/-/issues/701

The summary is that this allows xref entries in the navigation to propagate roles to the model. The following will have a model that contains the role custom.

* xref::index.adoc[Optional Text, role=custom]

The following will have a model that contains the roles a b.

* xref::index.adoc[Optional Text, role=a b]

Additional attributes title, target, and rel are also propagated to the model.

Partial Build

require name: @springio/antora-extensions/partial-build-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

The purpose of this extension is to reconfigure Antora to run a partial build, if possible. A partial build is build that only generates a site from a single refname, and hence a single version. The complete version inventory, as well as references to resources in other versions, are resolved from the site manifest produced by the Antora Atlas extension. Once the partial build is complete, the assumption is that the files generated will synchronized with the full site.

If a request is made to build a version which has not already been published, or the prerelease status of that version has changed since the last full build, the extension will revert to a full build. It will also generate a .full-build file in the output directory as a hint to the sync script that a full build has occurred.

If the refname is HEAD, then the content source url is also updated to the local content repository and the version must be specified.

You can give this extension a try by running these commands:

$ git clone --depth=1 -b docs-build https://github.com/spring-projects/spring-security spring-security-docs-build
  BUILD_REFNAME=main ./gradlew antora

The extension accepts several configuration options:

• refname (required)
  The single refname to build (e.g., main). May be provided by the BUILD_REFNAME environment variable.
• version
  The documentation version that corresponds to the refname. This information is used to determine if the version provided by the refname is present in the site manifest. May be provided by the BUILD_VERSION environment variable. If not specified, the version will be retrieved from the gradle.properties or pom.xml file at the root of the repository at the specified refname. Ideally, this option should be set by the workflow that invokes the partial build.
• rawgit_url (default: https://raw.githubusercontent.com)
  The base URL to use to retrieve a file from the git repository. This lookup happens when the version is not specified.

By default, the site manifest will be retrieved from {site-url}/site-manifest.json, where site-url is the value of the site.url key in the playbook (i.e., the production site URL). You can configure this extension (and, in turn, Antora Atlas) to use a different site manifest by passing the primary-site-manifest-url AsciiDoc attribute. This attribute can be set in the playbook.

Publish Docsearch Config

require name: @springio/antora-extensions/publish-docsearch-config-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

The purpose of this extension is to generate and publish the docsearch configuration that is used by Algolia. It will produce a file similar to the following at ${site.url}/docsearch-config.json

{
  "index_name": "spring-security-docs",
  "start_urls": [
    {
      "url": "https://docs.spring.io/spring-security/reference/6.1/",
      "extra_attributes": {
        "component": "security",
        "version": "6.1.0",
        "version_rank": 2
      }
    },
    {
      "url": "https://docs.spring.io/spring-security/reference/(?:$|index.html$|[a-z].*)",
      "extra_attributes": {
        "component": "security",
        "version": "6.0.2",
        "version_rank": 1
      }
    },
    {
      "url": "https://docs.spring.io/spring-security/reference/5.8/",
      "extra_attributes": {
        "component": "security",
        "version": "5.8.2",
        "version_rank": 2
      }
    },
    {
      "url": "https://docs.spring.io/spring-security/reference/5.7/",
      "extra_attributes": {
        "component": "security",
        "version": "5.7.7",
        "version_rank": 2
      }
    },
    {
      "url": "https://docs.spring.io/spring-security/reference/5.6/",
      "extra_attributes": {
        "component": "security",
        "version": "5.6.10",
        "version_rank": 2
      }
    }
  ],
  "sitemap_urls": [
    "https://docs.spring.io/spring-security/reference/sitemap.xml"
  ],
  "scrape_start_urls": true,
  "stop_urls": [
  ],
  "selectors": {
    "default": {
      "lvl0": {
        "global": true,
        "selector": ".nav-panel-explore .context .title, .nav-panel-explore .context .version"
      },
      "lvl1": ".doc > h1.page",
      "lvl2": ".doc .sect1 > h2:first-child",
      "lvl3": ".doc .sect2 > h3:first-child",
      "lvl4": ".doc .sect3 > h4:first-child",
      "text": ".doc p, .doc dt, .doc td.content, .doc th.tableblock"
    }
  },
  "selectors_exclude": [
    "#section-summary"
  ],
  "min_indexed_level": 1,
  "custom_settings": {
    "advancedSyntax": true,
    "attributesForFaceting": [
      "component",
      "version"
    ],
    "attributesToRetrieve": [
      "anchor",
      "content",
      "hierarchy",
      "url",
      "component",
      "version"
    ],
    "attributesToSnippet": [
      "content:25"
    ],
    "customRanking": [
      "desc(weight.page_rank)",
      "asc(version_rank)",
      "desc(weight.level)",
      "asc(weight.position)"
    ]
  }
}

The extension accepts several configuration options:

• template_path (default is to use the default template)
  Allows overriding the default handlebars template used to generate the configuration.
• index_name (default is the latest version’s name + -docs)
  This allows overriding the index_name property of the configuration. The default is to use the name of the latest version + -docs.
• root_component_name (default is to error on ROOT component name)
  If the name of the component is ROOT the value of rootComponentName will be used for the component in the generated configuration. The default is that if a component is named ROOT and rootComponentName is undefined an error will occur.

Root Component

require name: @springio/antora-extensions/root-component-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

The extension accepts several configuration options:

• root_component_name
  A required attribute that indicates the name of the component that should not be included in the URLs.

Root Attachments

require name: @springio/antora-extensions/root-attachments-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

This removes the _attachments portion of the URL from attachments.

Tabs Migration

require name: @springio/antora-extensions/tabs-migration-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

The purpose of this extension is to migrate the AsciiDoc source from using Spring tabs to using Asciidoctor tabs. It also has the ability to unwrap unneeded example blocks.

The extension accepts several configuration options:

• save_result (default: false)
  A boolean option that controls whether the migrated source is written back to the worktree. This option is only relevant when the file is read from a local directory, which is the case for git references that have an associated worktree.
• unwrap_example_block (default: tabs)
  An enumeration option that controls when example block delimiters are removed.
  • never - Never remove example block delimiters
  • tabs - Migrate example block that contains tabs to a tabs block
  • always - Remove example block delimiters if example block has no metadata and only contains a single child
• tabs_delimiter_length (default: 6)
  An integer option that controls the length of the delimiter for a tabs block. The recommended value is 6. You can also set it to 4 to use the conventional length.
• normalize (default: false)
  A boolean option that controls whether sequential empty lines are collapsed into a single empty line. Regardless of the value of this option, the extension will relocate block metadata lines to be directly above the block. The extension will also insert an empty line between tabs if one does not exist.

Static Page

require name: @springio/antora-extensions/static-page-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

This extension adds shared pages that are picked up by the antora-ui-spring project.

Asciinema

require name: @springio/antora-extensions/asciinema-extension

❗ IMPORTANT
Be sure to register this extension under the antora.extensions key in the playbook, not the asciidoc.extensions key!

📌 NOTE
Using this extension will need a little help from an UI bundle as it is expected that named partials asciinema-load-scripts, asciinema-create-scripts and asciinema-styles are included in a same locations where javascript and styles are loaded. Extension will add these partials if those don’t already exist in an UI bundle.

The purpose of this extension is to convert asciidoc block type asciinema into an asciinema-player. Expected content is plain cast file which is automatically extracted and packaged with into antora assets and configured with player instances.

[asciinema]
....
{"version": 2, "width": 80, "height": 24}
[1.0, "o", "hello "]
[2.0, "o", "world!"]
....

💡 TIP
You don’t need to inline cast file as it can also come via asciidoc include macro.

The extension accepts several configuration options as defined in https://github.com/asciinema/asciinema-player#options.

• rows
  Optional attribute as a default value for asciinema option rows.
• cols
  Optional attribute as a default value for asciinema option cols.
• auto_play
  Optional attribute as a default value for asciinema option autoPlay.

The block type accepts several configuration options. Block type options will override options from an extension level. Not a difference between snake_case and camelCase. For example:

[asciinema,rows=10,autoPlay=true]
....
<cast file>
....

• rows
  Optional attribute as a default value for asciinema option rows.
• cols
  Optional attribute as a default value for asciinema option cols.
• autoPlay
  Optional attribute as a default value for asciinema option autoPlay.

License

Use of this software is granted under the terms of the Apache License, Version 2.0 (Apache-2.0).