DOCSEARCHbyAlgolia
Submit Docs

Asciidoctor Maven Plugin

repository·main·Indexed 43 days ago

https://github.com/asciidoctor/asciidoctor-maven-plugin

Official plugin to integrate Asciidoctor into the Apache Maven build lifecycle for converting AsciiDoc documents into formats like HTML or DocBook. Features include the process-asciidoc goal for standard builds, auto-refresh for continuous conversion, and an http goal for live HTML previews via an embedded server. Supports Maven 3.8.8+ and Java 11+ for version 3.0.0 and later.

Tokens
17.2K
Snippets
45
Records
74
Agent score
55%

What's inside Asciidoctor Maven Plugin

  1. Overview of Asciidoctor Maven Plugin usage flavors

    main

    The Asciidoctor Maven Plugin provides a thin layer over AsciidoctorJ to convert AsciiDoc documentation during an Apache Maven build. It supports two primary integration patterns:

    1. Standalone Maven Plugin: Converts AsciiDoc files using the full power of Asciidoctor independently of the Maven Site lifecycle.
    2. Maven Site Integration: Integrates AsciiDoc files with Maven Doxia tools for use within a Maven Site module, though this mode has certain limitations compared to the standalone plugin.

  2. Overview of Asciidoctor Maven Plugin goals

    main

    The plugin provides three distinct goals to support different documentation workflows. None of these goals are bound to a specific Maven lifecycle phase by default; you must specify the phase and goal explicitly in your execution block.

    • process-asciidoc: The primary goal used to convert AsciiDoc documents into a target format (like HTML) during a standard Maven build.
    • auto-refresh: A development-focused goal that runs continuously. It monitors document modifications and converts them online as you write.
    • http: An extension of the auto-refresh capability that also pushes the converted HTML documents to a local HTTP server for live previewing.

  3. Understand the two flavors of Asciidoctor conversion

    main

    The Asciidoctor Maven tools provide two distinct ways to handle AsciiDoc conversion:

    1. As a Maven plugin: Converts AsciiDoc files using the full power of Asciidoctor independently of the Maven site. This is the preferred method for maximum feature support.
    2. As a Maven site integration: Integrates AsciiDoc files with Maven reports. This is useful for generating documentation as part of a standard Maven site, but has functional limitations compared to the standalone plugin.

  4. Understand how Asciidoctor metadata is exposed via Doxia

    main
    When using the Asciidoctor Maven Site integration, certain metadata from the Asciidoctor document header is automatically integrated with Doxia to be exposed in the generated site. This metadata is primarily used to populate HTML <meta> tags in the <head> section of the generated pages or to inform breadcrumb navigation.

  5. Configure auto-refresh parameters

    main

    The auto-refresh goal inherits all configuration parameters from the process-asciidoc goal and adds its own specific parameters.

    Important Configuration Note: Due to Maven limitations, configuration defined inside an <execution> block is ignored when running the goal directly via the command line (e.g., mvn asciidoctor:auto-refresh). To ensure your settings are applied, place shared configuration (like <attributes> or <preserveDirectories>) at the top-level <plugin> configuration block. Configuration inside <executions> is only applied when the plugin is run as part of a Maven lifecycle phase.

    <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>{release-version}</version>
    <configuration> <!-- Applied to all executions -->
        <preserveDirectories>true</preserveDirectories>
        <attributes>
            <source-highlighter>coderay</source-highlighter>
            <imagesdir>./images</imagesdir>
            <toc>left</toc>
            <icons>font</icons>
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
        </execution>
        <configuration> <!-- Ignored if running 'mvn asciidoctor:auto-refresh' directly -->
            <docinfo1>true</docinfo1>
        </configuration>
    </executions>
</plugin>

  6. Choose between Converter and Parser Doxia modules

    main

    The Asciidoctor Maven Site integration offers two different Doxia modules for authoring content with the Maven Site Plugin. Your choice depends on whether you prioritize standard Asciidoctor output or seamless Maven Site integration:

    1. Converter Doxia Module: Converts AsciiDoc sources into HTML using standard Asciidoctor. It provides the exact same HTML as the standalone Asciidoctor tool, but because it doesn't account for Maven Site's Doxia Skins, some elements might not look correct. You may need to provide custom CSS or Asciidoctor templates to fix presentation issues.

    2. Parser Doxia Module: Converts AsciiDoc sources into HTML using custom converters designed to adapt the output to Maven Site styles. This provides a better out-of-the-box experience and typically requires no extra CSS. Note: This module is currently considered experimental and does not yet support all AsciiDoc structures.

  7. Configure directory structure preservation

    main

    By default, all output files are generated in a single flat folder. Use preserveDirectories to maintain the source folder hierarchy in the output.

    • preserveDirectories: Set to true to mirror the source directory structure in the output directory.
    • relativeBaseDir: If preserveDirectories is not used, setting this to true tells each AsciiDoc file to search for its resources (like included files) in its own local folder.
    <!-- Example of preserveDirectories: true structure -->
├── docs
│   ├── examples.adoc             
│   └── examples
│       └── html.adoc             
└── index.adoc

Resulting output:
├── docs
│   ├── examples.html             
│   └── examples
│       └── html.html             
└── index.html

  8. Configure a simple HTML conversion with process-asciidoc

    main

    To convert AsciiDoc documents to HTML during a Maven build, add the asciidoctor-maven-plugin to your pom.xml. You must explicitly define the <phase> (e.g., generate-resources) and the <goal> (e.g., process-asciidoc) within an <execution> block.

    Configuration details:

    • Use <outputDirectory> to specify where the converted files should be placed.
    • Use the <attributes> section to pass Asciidoctor attributes (key-value pairs) to the conversion engine.
    • The default backend is html5.
    <project>
    ...
    <build>
        ...
        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>{release-version}</version>
            <executions>
                <execution>
                    <id>convert-to-html</id>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>${project.build.directory}/html</outputDirectory>
                        <attributes>
                            <source-highlighter>coderay</source-highlighter>
                            <imagesdir>./images</imagesdir>
                            <toc>left</toc>
                            <icons>font</icons>
                        </attributes>
                    </configuration>
                </execution>
            </executions>
        </plugin>
  ...
</project>

  9. Integrate Asciidoctor with Maven Site

    main

    To use AsciiDoc to generate your Maven site, add the asciidoctor-maven-plugin as a dependency to the maven-site-plugin declaration.

    Important: When configuring Asciidoctor within the maven-site-plugin, all Asciidoctor-specific settings must be wrapped inside an <asciidoc> element within the <configuration> block.

    <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.12.1</version>
    <configuration>
        <asciidoc>
            <templateDirs>
                <dir>src/site/asciidoc/templates</dir>
            </templateDirs>
            <requires>
                <require>asciidoctor-diagram</require>
            </requires>
            <attributes>
                <source-highlighter>coderay</source-highlighter>
                <coderay-css>style</coderay-css>
            </attributes>
        </asciidoc>
        <moduleExcludes>
            <asciidoc>**/_*.adoc,**/_*/</asciidoc>
        </moduleExcludes>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.3</version>
        </dependency>
    </dependencies>
</plugin>

  10. Fail the build on missing attributes

    main

    By default, Asciidoctor ignores attributes whose values cannot be resolved. To treat missing attributes as errors and abort the Maven build, configure the attribute-missing attribute to warn and use the logHandler configuration to fail the build when a WARN severity message is encountered.

    <configuration>
    <attributes>
        <attribute-missing>warn</attribute-missing>
    </attributes>
    <logHandler>
        <failIf>
            <severity>WARN</severity>
        </failIf>
    </logHandler>
</configuration>

  11. Configure the http goal in pom.xml

    main

    To use the http goal, you must explicitly define an execution in your pom.xml because the plugin does not run in any phase by default. You must specify a Maven lifecycle phase (e.g., generate-resources).

    Setup Steps:

    1. Add the asciidoctor-maven-plugin to your <build><plugins> section.
    2. Create an <execution> block.
    3. Assign a unique <id>.
    4. Specify a <phase> (e.g., generate-resources).
    5. Set the <goal> to http.
    6. (Optional) Configure parameters like <port> within the <configuration> block.
    <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>VERSION</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>http</goal>
            </goals>
            <configuration>
                <port>8080</port>
            </configuration>
        </execution>
    </executions>
</plugin>

  12. Use the auto-refresh goal to convert documents on change

    main

    The auto-refresh goal automatically converts AsciiDoc documents whenever they are modified or a new one is added. This is designed to speed up the writing process by removing the need for full manual rebuilds.

    To preview changes in a browser, you can combine this goal with a browser refresh extension or use it alongside the http goal.

    Once the goal is started, the Maven process remains active. You can stop it by typing exit or quit in the console, or by using Ctrl+C.

    <plugin>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>auto-refresh</goal>
            </goals>
        </execution>
    </executions>
</plugin>