Skip to content

Latest commit

 

History

History
140 lines (118 loc) · 3.93 KB

README.adoc

File metadata and controls

140 lines (118 loc) · 3.93 KB
Raw

AsciidoctorJ Extensions

This project provides extensions for AsciidoctorJ.

Setup

The extensions are available from Maven Central repository and can be enabled by adding a dependency to the Asciidoctor Maven plugin:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.version}</version>
    <executions>
        <execution>
            <phase>process-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
        </execution>
    </executions>
    <confiuration>
        <attributes>
            <!-- extension specific attributes -->
        </attributes>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>com.buschmais.asciidoctorj</groupId>
            <artifactId>extensions</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</plugin>

URL Inline Macro Processor

Provides a macro url which adds links according to defined URL mappings. Each mapping consists of a regular expression to match and a replacement pattern to generate a URL.

Mappings
jQAssistant-(\d*) = https://github.com/buschmais/jqassistant/issues/$1,
XO-(\d*) = https://github.com/buschmais/extended-objects/issues/$1
jQAssistant-(\d*)

The regular expression containing group (\d*) which will be used in the replacement pattern as $1

https://github.com/buschmais/jqassistant/issues/$1

Defines the link to create and which refers to group $1

Using these mappings the Asciidoc snippet

For more information refer to url:jQAssistant-123[].

will be rendered as a link:

For more information refer to jQAssistant-123.

The mappings must be defined as document attribute url-mappings, e.g. in case of Maven:

pom.xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    ...
    <configuration>
        <attributes>
            <url-mappings>
                jQAssistant-(\d*) = https://github.com/buschmais/jqassistant/issues/$1,
                XO-(\d*) = https://github.com/buschmais/extended-objects/issues/$1
            </url-mappings>
        </attributes>
    <configuration>
    <dependencies>
        <dependency>
            <groupId>com.buschmais.asciidoctorj</groupId>
            <artifactId>extensions</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</plugin>
Note
 The URLs must be encoded, e.g. = must be represented by %3D.

It is possible to define an alternative name for the macro:

pom.xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    ...
    <configuration>
        <attributes>
            <url-mappings>
            ...
            </url-mappings>
        </attributes>
        <extensions>
            <extension>
                <className>com.buschmais.asciidoctorj.extensions.UrlInlineMacroProcessor</className> <!-- <1> -->
                <blockName>issue</blockName>                                                         <!-- <2> -->
            </extension>
        </extensions>
    <configuration>
    <dependencies>
        <dependency>
            <groupId>com.buschmais.asciidoctorj</groupId>
            <artifactId>extensions</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</plugin>

  1. Declares the extension explicitly.

  2. Defines the name issue.

For more information refer to issue:jQAssistant-123[].
For more information refer to url:jQAssistant-123[].

Feedback

Please report any issues here.