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

To use the development version instead, refer to the Development Quickstart.

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

❗	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

❗	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

❗	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

❗	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

❗	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

❗	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

❗	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

❗	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

❗	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

❗	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

❗	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

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

Development Quickstart

This section provides information on how to develop on this project.

Prerequisites

To build this project and run the tests, you need the following software installed on your computer:

git (command: git)
Node.js (commands: node, npm, and npx)

git

First, make sure you have git installed.

$ git --version

If not, download and install the git package for your system.

Node.js

Next, make sure that you have Node.js installed (which also provides npm and npx).

$ node --version

If this command fails with an error, you don’t have Node.js installed. If the command doesn’t report an active LTS version of Node.js, it means you don’t have a suitable version of Node.js installed.

We strongly recommend that you use nvm (Node Version Manager) to manage your Node.js installation(s). Follow the nvm installation instructions to set up nvm on your machine.

Once you’ve installed nvm, open a new terminal and install Node.js 16 using the following command:

$ nvm install 16

You can switch to this version of Node.js at any time using the following command:

$ nvm use 16

To make Node.js 16 the default in new terminals, type:

$ nvm alias default 16

Now that you have git and Node.js installed, you’re ready to start developing on this project.

Clone Project

Clone the project using git:

$ git clone https://github.com/spring-io/antora-extensions &&
  cd "`basename $_`"

The previous chained command clones the project then switches to the project folder on your filesystem. Stay in this project folder when running all subsequent commands.

Install Dependencies

Use npm to install the project’s dependencies inside the project. In your terminal, run the following command:

$ npm ci

This command installs the dependencies listed in package-lock.json into the node_modules/ folder inside the project. This folder should not be committed to the source control repository.

Run Tests

This project uses mocha to run the tests and the assertion library chai to assert outcomes. To run the test suite, use:

$ npm test

By default, npm test will run all tests. You can run the tests in a single test suite by passing the path of that test suite as the final argument:

$ npm test test/partial-build-extension-test.js

You can also run a single test by adding .only to the it function (e.g., it.only). If it.only is present, npm test will only run that test.

To generate a coverage report when running the tests (enabled by default in CI), run the coverage script instead:

$ npm run coverage

A coverage report shows the lines, statements, and branches that the tests exercise. You can view the coverage report by opening the HTML file reports/lcov-report/index.html in your browser.

Verify Code Style

This project adheres to the JavaScript Standard style with some exceptions defined in .eslintrc. The code style is verified using ESLint.

To verify that the style of the code is correct, run the following command:

$ npm run lint

To format the code to adhere to the code style, run the following command:

$ npm run format

The CI workflow will fail if there are pending code style changes, so be sure to run it before you push a change.

Use Project From Source

If you want to use the project locally before it is published, you can specify the path to the project as the version in package.json.

"dependencies": {
  "@springio/antora-extensions": "/path/to/project"
}

When you run npm i in that project, npm will set up a symlink to the location of this project. Any changes to this project will take effect immediately.

License

Use of this software is granted under the terms of the Apache License, Version 2.0 (Apache-2.0). See LICENSE to find the full license text.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.adoc

README.adoc

Spring.io Antora Extensions

Prerequisites

Extensions

antora-extensions

Set Algolia Env

Collector Cache Config

Latest Version

override-navigation-builder-extension

Partial Build

Publish Docsearch Config

Root Component

Root Attachments

Tabs Migration

Static Page

Asciinema

Development Quickstart

Prerequisites

git

Node.js

Clone Project

Install Dependencies

Run Tests

Verify Code Style

Use Project From Source

License

Files

README.adoc

Latest commit

History

README.adoc

File metadata and controls

Spring.io Antora Extensions

Prerequisites

Extensions

antora-extensions

Set Algolia Env

Collector Cache Config

Latest Version

override-navigation-builder-extension

Partial Build

Publish Docsearch Config

Root Component

Root Attachments

Tabs Migration

Static Page

Asciinema

Development Quickstart

Prerequisites

git

Node.js

Clone Project

Install Dependencies

Run Tests

Verify Code Style

Use Project From Source

License