@opendevise/springio-asciidoctor-extensions v1.0.0-alpha.3

Spring Asciidoctor Extensions

❗ IMPORTANT: The package at @opendevise/springio-asciidoctor-extensions is only a temporary name for this package. Depend on it at your own risk. The package will be removed from this location once it has been published under its official name, @springio/asciidoctor-extensions.

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.

Extensions

This section documents the extensions that are provided by this library.

Code Chomping

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:

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:

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

If this attribute is set and its value is empty, the original package declaration is preserved.

Code Folding

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:

Migrate Tabs Antora Extension

require name: @springio/asciidoctor-extensions/migrate-tabs-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.

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

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

License

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