Skip to content

spring-io/spring-asciidoctor-extensions

Repository files navigation

Spring Asciidoctor Extensions

Requirements

  • AsciidoctorJ 2.x

  • Java 1.8 or later

Getting the extensions

Releases are published to Maven Central. Snapshots are published to the https://repo.spring.io/snapshot Maven repository.

Available extensions

Block switch

io.spring.asciidoctor:spring-asciidoctor-extensions-block-switch

Post-processes Asciidoctor’s HTML output to collapse multiple code blocks into one and provides tabs that can be used to switch between them. Requires one block that has a role="primary" attribute and one or more blocks that have a role="secondary" attribute. The tabs are named using the block titles.

For example:

[source,xml,indent=0,role="primary"]
.Maven
----
<dependency>
    <groupId>com.example</groupId>
    <artifactId>some-library</artifactId>
    <version>1.2.3</version>
</dependency>
----

[source,indent=0,role="secondary"]
.Gradle
----
compile 'com.example:some-library:1.2.3'
----

Spring Boot

io.spring.asciidoctor:spring-asciidoctor-extensions-spring-boot

Description

Extension for writing Spring Boot-related documentation, providing the following functionality:

  • A macro for verifying that individual configuration properties exist.

  • Opt-in support for verifying the keys in a properties listing exist as configuration properties.

Inline property validation

The configprop macro can be used to reference a configuration property in line as shown in the following example:

Use the configprop:server.port[] property to configure the server's port.

The property referenced by the preceding example is server.port. If the property exists a debug message is logged. If it does not exist or it exists and it is deprecated a warning message is logged. A deprecated property can be documented without a warning being logged using the deprecated attribute, as shown in the following example:

The configprop:example.property[deprecated] property has been deprecated.

If the deprecated attribute is specified and the property is not deprecated a warning message will be logged.

The macro outputs the name of the property as monospaced text. The format attribute can be used to change the output to that required for use as an environment variable, as shown in the following example:

Use the configprop:server.port[format=envvar] environment variable to configure the server's port.

The output of the macro in the preceding example is SERVER_PORT.

Properties listing validation

The extension validates the properties found in a properties listing when it has the configprops attribute, as shown in the following example:

[source,properties,configprops]
----
example.property.alpha=a
example.property.bravo=b
example.property.charlie=c
----

Three properties will be validated in the preceding example:

  • example.property.alpha

  • example.property.bravo

  • example.property.charlie

A debug message is output for every property in the listing that exists. A warning message is output for every property in the listing that does not exist. Properties that are bound to a map or that use [] notation to configure an item in a list are supported.

Automatically generating different config blocks

The extension can generate different config source format blocks from a single listing. Currently you can generate a .properties block given a .yaml source. The generated listings use the "Block Switch" extension to give the user a tabbed view.

For example, given the source:

[source,yaml,configblocks]
----
example:
  property:
    alpha: a
----

The user will be provided with a "block switch" containing:

example.property.alpha: a

and

example:
  property:
    alpha: a

Section IDs

io.spring.asciidoctor:spring-asciidoctor-extensions-section-ids

Description

Validates a document’s section IDs. Ensures that each ID uses kebab-case and that the IDs of nested sections being with their parent section’s ID following by a .. The following IDs are valid:

  • top-level

    • top-level.nested-child

      • top-level.nested-child.grandchild

A warning is logged for each invalid ID.

Adding the extensions to your project

The extensions can be added to your project using the standard mechanism for your build system. Please consult the relevant documentation for details: