This library provides Asciidoctor extensions that support the Spring documentation. For now, these extensions are only designed for use with Asciidoctor.js. The extensions evolved out of the Spring Asciidoctor backends project.
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 Asciidoctor.js. Since this project does not declare Asciidoctor.js as a dependency to afford you flexibility, you must have Asciidoctor.js 2.2 or higher installed in your project.
Use the following command to install the @springio/asciidoctor-extensions package into your project:
$ npm i @springio/asciidoctor-extensionsTo use the development version instead, refer to the Development Quickstart.
The following two sections introduce the extensions provided by this library and how to activate them.
This section documents the Asciidoctor extensions that are provided by this library.
require name: @springio/asciidoctor-extensions/code-chomping-extension
The code chomping extension allows specific parts of a Java, Kotlin, or Groovy source block to be removed. The extension will not run on any other source, listing, or literal blocks. This extension is mainly useful if you have externalized code that includes comments and annotations intended for the compiler’s eyes only.
When this extension is registered, it will remove parts of the code that match chomp tags, @Suppress / @SuppressWarnings annotations, and @formatter:on / @formatter:off line comments.
You can also turn on chomping of the header (typically a Javadoc comment or license statement) and package declaration.
The following chomp tags (i.e., comments) are supported:
| Comment | Description |
|---|---|
|
Chomps the rest of the line and replaces it with |
|
Chomps the rest of the line and replaces it with <replacement>, which defaults to |
|
Chomps (drops) this line only |
|
Chomps (drops) this line to the end of the file |
Here’s an example source block that uses code chomping:
[,java]
----
public class Example {
private final Something something;
private final Other other;
public Example() {
this.something = /**/ new MockSomething();
this.other = /* @chomp:line your thing... */new MyThing();
}
}
----The output of this block will appear as follows:
public class Example {
private final Something something;
private final Other other;
public Example() {
this.something = ...
this.other = your thing...
}
}You can set the chomp AsciiDoc attribute to change the default settings.
The attribute can be set on the document or the block.
The document attribute is the default value.
The attribute value may be one of the following keywords:
| Flag | Description |
|---|---|
default |
Enable the |
all |
Enable all chomping operations |
none |
Disable all chomping operations |
tags |
Chomp the comment tags |
formatters |
Chomp any |
suppresswarnings |
Chomp any |
headers |
Chomp any file headers up to |
packages |
Chomp the package declaration, or replace the name if the |
Instead of dropping the package declaration, you can replace the name.
To do so, ensure the packages operation is enabled.
Then, set the chomp-package-replacement to the replacement name, such as org.example.
When the extension finds the package declaration, it will replace the name in the source with the replacement name you specified.
The following document is configured to update the name in the package declaration in each Java-like source file with org.example.
= My Document
:chomp-package-replacement: org.exampleIf this attribute is set and its value is empty, the original package declaration is preserved.
require name: @springio/asciidoctor-extensions/code-folding-extension
The code folding extension allows non-pertinent code in a source block to be hidden on initial view. The user can click the “unfold” button to reveal the hidden code. The extension will not run on any other source, listing, or literal blocks. This extension is mainly useful if you have externalized code that includes boilerplate lines that detract from the focus of the snippet.
When this extension is registered, all Java imports will be automatically folded.
Additional fold blocks can also be defined using fold tags.
The fold tags are @fold:on and @fold:off comment lines.
Here’s an example source block that uses code folding to hide the fields on initial view:
[,java]
----
public class Example {
// @fold:on
private final String first;
private final String second;
// @fold:off
public Example(String first, String second) {
this.first = first;
this.second = second;
}
}
----The @fold:on tag supports replacement text to show when the block is folded.
Here’s an example source block that replaces the getters and setters with a comment when folded:
[,java]
----
public class Example {
private String first;
private String second;
// @fold:on // getters / setters...
public String getFirst() {
return this.first;
}
public void setFirst(String first) {
this.first = first;
}
public String getSecond() {
return this.second;
}
public void setSecond(String second) {
this.second = second;
}
// @fold:off
}
----You can set the fold AsciiDoc attribute to change the default settings.
The attribute can be used on the document or the block.
The document attribute is the default value.
The attribute value may be one of the following keywords:
| Flag | Description |
|---|---|
default |
Enable the |
all |
Enable all folding operations |
none |
Disable all folding operations |
imports |
Fold import statements |
tags |
Fold |
This section documents the auxiliary Antora extensions that are provided by this library.
require name: @springio/asciidoctor-extensions/tabs-migration-antora-extension
In addition to Asciidoctor extensions, this library also provides one Antora extension. 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.
|
❗
|
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:
- 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.
This section provides information on how to develop on this project.
To build this project and run the tests, you need the following software installed on your computer:
First, make sure you have git installed.
$ git --version
If not, download and install the git package for your system.
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 the project using git:
$ git clone https://github.com/spring-io/asciidoctor-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.
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.
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/code-chomping-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.
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.
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/asciidoctor-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 affect immediately.
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.