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.

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

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

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.

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)

Clone the project using git:

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.

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

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.

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

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:

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:

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.

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:

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

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

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.

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.