### HelloWorld3.groovy Example

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/relative-path-treatment/level-1-1/level-2-1/HelloWorld3.adoc

This Groovy script is an example used for testing relative path treatment in Asciidoctor Maven Plugin.

```groovy
println "Hello World 3!"

```

--------------------------------

### Start Asciidoctor Live Preview

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Execute the Maven command to start the live preview server. The output will be accessible via a web browser.

```bash
# Start live preview — opens at http://localhost:8080/manual (no .html needed)
mvn asciidoctor:http
```

--------------------------------

### Java Hello World Example

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-converter-doxia-module/src/test/resources/errors/document-with-missing-include.adoc

A standard Java program that prints 'Hello, World' to the console. This is a basic example of a Java application.

```java
public class HelloWorld {

    public static void main(String[] args) {
        // Prints "Hello, World" to the terminal window.
        System.out.println("Hello, World");
    }

}
```

--------------------------------

### Include Processor Example

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/processors-sample.adoc

An example of the include processor used to embed content from a remote URL. This is useful for including files like Gemfiles or other configuration files directly into your documentation.

```ruby
include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
```

--------------------------------

### Configure http Goal in Maven

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/goals/http.adoc

Configure the http goal within the pom.xml to convert AsciiDoc files and start an HTTP server. This example sets the port to 8080.

```xml
<plugin>
    ...
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>http</goal>
            </goals>
            <configuration>
                <port>8080</port>
            </configuration>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Configure Asciidoctor Maven Plugin for Live Preview

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Configure the asciidoctor-maven-plugin to start an embedded HTTP server for live HTML previews. Set the port and default home page.

```xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.2.0</version>
    <configuration>
        <preserveDirectories>true</preserveDirectories>
        <attributes>
            <toc>left</toc>
            <icons>font</icons>
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>live-preview</id>
            <phase>generate-resources</phase>
            <goals><goal>http</goal></goals>
            <configuration>
                <!-- HTTP server port (default: 2000) -->
                <port>8080</port>
                <!-- Default page when browsing http://localhost:8080 -->
                <home>index</home>
            </configuration>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Resource Configuration Example

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/partials/process-asciidoc-mojo-parameters.adoc

Defines resource files to be copied to the output directory. Supports specifying directories to copy from, target paths, and includes/excludes for specific file types. This configuration follows patterns similar to the maven-resources-plugin.

```xml
<resources>
    <resource>
        <!-- (Mandatory) Directory to copy from. Paths are relative to maven's ${baseDir} -->
        <directory>DIRECTORY</directory>
        <!-- (Optional) Directory to copy to. By default uses the option `outputDirectory` -->
        <targetPath>OUTPUT_DIR</targetPath>
        <!-- (Optional) NOTE: SVN, GIT and other version control files are excluded by default, there's no need to add them -->
        <excludes>
            <exclude>**/.txt</exclude>
        </excludes>
        <!-- (Optional) If not set, includes all files but default exceptions mentioned -->
        <includes>
            <include>**/*.jpg</include>
            <include>**/*.gif</include>
        </includes>
    </resource>
    ...
</resources>
```

--------------------------------

### HelloWorld4.groovy Example

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/relative-path-treatment/level-1-1/level-2-2/level-3-1/HelloWorld4.adoc

This snippet shows a basic Groovy script named HelloWorld4.groovy. It is intended to be processed by Asciidoctor, potentially demonstrating include directives or other Asciidoctor features.

```groovy
println "Hello World 4"
```

--------------------------------

### Shared configuration for process-asciidoc and auto-refresh goals

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/goals/auto-refresh.adoc

This example shows how to apply configuration at the top plugin level, which is processed by both `process-asciidoc` and `auto-refresh` goals. Configuration within `<executions>` for `auto-refresh` is ignored due to Maven limitations.

```xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>{release-version}</version>
    <configuration> <!----1---->
        <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> <!----2---->
            <docinfo1>true</docinfo1>
        </configuration>
    </executions>
</plugin>
```

--------------------------------

### Block Processor Example

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/processors-sample.adoc

Demonstrates a custom block processor, indicated by the '[yell]' attribute. This processor transforms the enclosed content, in this case, making it stand out or applying specific styling.

```asciidoc
[yell]
----
The time is now. Get a move on.
----
```

--------------------------------

### Include HelloWorld3.groovy

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/relative-path-treatment/level-1-1/level-2-2/HelloWorld3.adoc

This snippet shows how to include the content of the HelloWorld3.groovy file within an Asciidoctor document. It is part of the relative path treatment examples.

```groovy
include::HelloWorld3.groovy[]
```

--------------------------------

### Maven Plugin Setup for process-asciidoc

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/goals/process-asciidoc.adoc

Configure the Asciidoctor Maven plugin within your pom.xml to execute the `process-asciidoc` goal. Specify an execution ID, the Maven phase (e.g., `generate-resources`), and the goal itself.

```xml
<plugin>
    ...
    <executions>
        <execution>
            <id>output-html</id>              <!--1-->
            <phase>generate-resources</phase> <!--2-->
            <goals>
                <goal>process-asciidoc</goal> <!--3-->
            </goals>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Custom Inline Block Macro Example

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/processors-sample.adoc

Shows how to use a custom inline block macro, demonstrated here with the 'man' macro for referencing man pages. Ensure the man macro is properly configured or available in your Asciidoctor environment.

```asciidoc
See man:gittutorial[7] to get started.
```

--------------------------------

### Preserve Directory Structure Example

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/partials/process-asciidoc-mojo-parameters.adoc

Illustrates how to maintain the original folder structure for converted documents in the output directory. When enabled, output files are generated in the same hierarchical layout as the source files.

```text
    ├── docs                          ├── docs
    │   ├── examples.adoc             │   ├── examples.html
    │   └── examples            =>    │   └── examples
    │       ├── html.adoc             │       ├── html.html
    │       └── docbook.adoc          │       └── docbook.html
    └── index.adoc                    └── index.html
```

--------------------------------

### Custom Block Macro Example

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/processors-sample.adoc

Illustrates the usage of a custom block macro named 'gist'. This macro is typically used to embed content from external sources like GitHub gists.

```asciidoc
.My Gist
gist::123456[]
```

--------------------------------

### Setup auto-refresh goal in Maven

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/goals/auto-refresh.adoc

Configure the auto-refresh goal within the plugin's executions. Specify a unique ID, the Maven phase, and the goal itself.

```xml
<plugin>
    ...
    <executions>
        <execution>
            <id>output-html</id>              <!----1---->
            <phase>generate-resources</phase> <!----2---->
            <goals>
                <goal>auto-refresh</goal>     <!----3---->
            </goals>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Multiple Outputs for Same File with Asciidoctor Maven Plugin

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/usage.adoc

Configure the plugin to generate multiple outputs for the same AsciiDoc source file by defining separate executions. This example shows conversions to both HTML and DocBook.

```xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>{release-version}</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html</backend>
                <attributes>
                    <toc/>
                    <linkcss>false</linkcss>
                    <source-highlighter>coderay</source-highlighter>
                </attributes>
            </configuration>
        </execution>
        <execution>
            <id>output-docbook</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>docbook</backend>
                <doctype>book</doctype>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <sourceDirectory>src/main/asciidoc</sourceDirectory>
        <standalone>true</standalone>
    </configuration>
</plugin>
```

--------------------------------

### Start Asciidoctor Auto-Refresh Watcher

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Initiate the Asciidoctor Maven plugin's auto-refresh watcher to perform live re-conversions on file changes. The watcher runs until explicitly stopped.

```bash
# Start the watcher (runs until you type exit/quit)
mvn asciidoctor:auto-refresh
# or via phase
mvn generate-resources
```

--------------------------------

### Maven Site Integration with Asciidoctor Configuration

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/site-integration/pages/parser-module-setup-and-configuration.adoc

Configure Asciidoctor options, attributes, and exclusions within the maven-site-plugin configuration block. This example includes setting a source highlighter and ignoring internal AsciiDoc files.

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>{maven-site-plugin-version}</version>
    <configuration>
        <asciidoc>
            <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>{doxia-module-name}</artifactId>
            <version>{release-version}</version>
        </dependency>
    </dependencies>
</plugin>
```

--------------------------------

### Configure Asciidoctor Maven Plugin for Batch Conversion

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Configure the `asciidoctor-maven-plugin` within your `pom.xml` to convert AsciiDoc sources to HTML during the `generate-resources` phase. This example demonstrates setting source and output directories, backend, doctype, and various attributes like table of contents, icons, and source highlighting.

```xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.2.0</version>
    <executions>
        <execution>
            <id>convert-to-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <!-- Source files location (checked in order if not set):
                     src/docs/asciidoc, src/asciidoc, src/main/asciidoc -->
                <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                <!-- Output defaults to ${project.build.directory}/generated-docs -->
                <outputDirectory>${project.build.directory}/html</outputDirectory>
                <!-- backend: html5 (default), pdf, docbook, manpage … -->
                <backend>html5</backend>
                <!-- doctype: article (default), book, manpage, inline -->
                <doctype>article</doctype>
                <!-- standalone: wrap content in header/footer (default: true) -->
                <standalone>true</standalone>
                <!-- Mirror source tree in output (default: false) -->
                <preserveDirectories>true</preserveDirectories>
                <attributes>
                    <toc>left</toc>
                    <icons>font</icons>
                    <source-highlighter>coderay</source-highlighter>
                    <imagesdir>./images</imagesdir>
                    <!-- Boolean: empty tag or "true" sets; "false" unsets -->
                    <sectnums>true</sectnums>
                    <linkcss>false</linkcss>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Configure Build Failure on Asciidoctor Errors

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/partials/process-asciidoc-mojo-parameters.adoc

Use this configuration to control build failure based on Asciidoctor message severity. Setting `outputToConsole` to `false` prevents messages from being shown as INFO in Maven output, while the `failIf` block specifies conditions that will cause a `BUILD FAILURE`. The example shows how to fail on any message with severity `DEBUG` or higher.

```xml
<logHandler>
    <outputToConsole>false</outputToConsole> 
    <failIf>
        <severity>DEBUG</severity> 
    </failIf>
</logHandler>
```

--------------------------------

### Maven Properties to Asciidoctor Attributes

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/site-integration/pages/parser-module-setup-and-configuration.adoc

Demonstrates how Maven properties are passed as Asciidoctor attributes. Maven properties with dots are converted to attributes with hyphens. This example shows a Maven property 'my-site.version' being passed as 'my-site-version' to the Asciidoctor converter.

```xml
<properties>
  <my-site.version>2.3.0</my-site.version> <!--.-->
</properties>
```

--------------------------------

### Build Maven Site with Asciidoctor

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Execute the Maven command to generate the site, which will process AsciiDoc files using the configured plugin.

```bash
mvn site:site
```

--------------------------------

### Set Source and Output Directories via Command Line

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/command-line-configuration.adoc

Use system properties to specify the source and output directories for Asciidoctor processing when running Maven.

```bash
mvn generate-resources -Dasciidoctor.sourceDirectory=src/docs -Dasciidoctor.outputDirectory=target/docs
```

--------------------------------

### Configure DocBook Backend

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/v2-migration-guide.adoc

Set the backend explicitly to 'docbook' for backward compatible configuration.

```xml
<configuration>
    <backend>docbook</backend>
</configuration>
```

--------------------------------

### Generate Maven Site with Asciidoctor

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Run the Maven site generation command. This will process AsciiDoc sources and integrate them into the project's site.

```bash
# AsciiDoc sources: src/site/asciidoc/*.adoc  →  target/site/*.html
mvn site:site
```

--------------------------------

### Include Groovy Script

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/relative-path-treatment/HelloWorld.adoc

Includes the HelloWorld.groovy script. Ensure the script is located at the specified path relative to the Asciidoctor configuration.

```groovy
include::HelloWorld.groovy[]
```

--------------------------------

### Ruby Hello World

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-parser-doxia-module/src/it/maven-site-plugin/src/site/asciidoc/sample.adoc

A basic Ruby program that prints 'Hello, World!' to the console.

```ruby
puts "Hello, World!"
```

--------------------------------

### Generate Documentation in Version-Specific Folders

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/tips-and-tricks.adoc

Use the Maven `project.version` property to specify a custom output directory that includes the project's version. This helps in organizing documentation for different releases.

```xml
<configuration>
    ...
    <outputDirectory>target/generated-docs/${project.version}</outputDirectory>
    ...
</configuration>
```

--------------------------------

### Add AsciiDoc Navigation to Maven Site

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Define navigation items in `src/site/site.xml` for AsciiDoc pages to be included in the Maven Site's menu structure.

```xml
<body>
    <menu name="User Guide">
        <item href="usage.html" name="Usage" />
        <item href="configuration.html" name="Configuration" />
    </menu>
</body>
```

--------------------------------

### Configure Multiple Output Backends

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Define multiple executions to render the same source files into different formats (e.g., HTML and DocBook) within a single Maven build. Shared options are configured at the top level.

```xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.2.0</version>
    <!-- Shared config inherited by both executions -->
    <configuration>
        <sourceDirectory>src/main/asciidoc</sourceDirectory>
        <standalone>true</standalone>
    </configuration>
    <executions>
        <!-- Execution 1: produce HTML -->
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals><goal>process-asciidoc</goal></goals>
            <configuration>
                <backend>html</backend>
                <attributes>
                    <toc/>
                    <linkcss>false</linkcss>
                    <source-highlighter>coderay</source-highlighter>
                </attributes>
            </configuration>
        </execution>
        <!-- Execution 2: produce DocBook -->
        <execution>
            <id>output-docbook</id>
            <phase>generate-resources</phase>
            <goals><goal>process-asciidoc</goal></goals>
            <configuration>
                <backend>docbook</backend>
                <doctype>book</doctype>
            </configuration>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Generate Version-Stamped Documentation

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Run the Maven `generate-resources` goal to produce documentation in version-stamped directories, e.g., `target/generated-docs/2.1.0/`.

```bash
# Output lands in target/generated-docs/2.1.0/
mvn generate-resources
```

--------------------------------

### Add Version and Build Date to Document Headers

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/tips-and-tricks.adoc

Automatically include the project version and build date in the header and footer of generated documents. Configure `maven.build.timestamp.format` in properties for custom date formatting.

```xml
<properties>
   <maven.build.timestamp.format>yyyy-MM-dd HH</maven.build.timestamp.format>  
</properties>

<configuration>
    ...
    <attributes>
        ...
        <revnumber>${project.version}</revnumber>
        <revdate>${maven.build.timestamp}</revdate>
        <organization>${project.organization.name}</organization>
    </attributes>
    ...
</configuration>
```

--------------------------------

### Copy Additional Assets with Resources

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Configure the `resources` block to copy non-AsciiDoc files like images, CSS, and fonts to the output directory. This follows the pattern of `maven-resources-plugin`.

```xml
<configuration>
    <outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
    <resources>
        <resource>
            <!-- Required: directory to copy from (relative to ${basedir}) -->
            <directory>src/docs/asciidoc/images</directory>
            <!-- Optional: sub-path inside outputDirectory -->
            <targetPath>images</targetPath>
            <includes>
                <include>**/*.png</include>
                <include>**/*.jpg</include>
                <include>**/*.svg</include>
            </includes>
            <excludes>
                <exclude>**/*.tmp</exclude>
            </excludes>
        </resource>
        <resource>
            <directory>src/docs/asciidoc/css</directory>
            <targetPath>css</targetPath>
        </resource>
    </resources>
</configuration>
```

--------------------------------

### Site Navigation Menu Item Configuration

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/site-integration/pages/parser-module-setup-and-configuration.adoc

Define a menu item in your site.xml to link to the HTML page generated from an AsciiDoc file.

```xml
<body>
    ...
    <menu name="User guide">
        <item href="usage.html" name="Usage" />
    </menu>
    ...
</body>
```

--------------------------------

### Run Unit Tests with Maven Wrapper

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/project/pages/contributing.adoc

Execute unit tests using the Maven wrapper. This is the standard way to run tests during development.

```bash
./mvnw clean test
```

--------------------------------

### Run Integration Tests with Maven Wrapper

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/project/pages/contributing.adoc

Execute integration tests using the Maven wrapper with the 'run-its' profile. This command skips unit tests and focuses solely on integration tests.

```bash
./mvnw clean verify -DskipTests -Prun-its
```

--------------------------------

### Configure Multiple Attributes via Command Line

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/command-line-configuration.adoc

Provide multiple attributes to Asciidoctor via the command line, separated by spaces. Use quotes if attribute values contain spaces.

```bash
mvn generate-resources -Dasciidoctor.attributes="toc=right source-highlighter=highlight.js imagesdir=my_images"
```

--------------------------------

### Configure Attributes via Command Line (Single Attribute)

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/command-line-configuration.adoc

Add or update a single attribute for Asciidoctor processing directly from the command line. This appends to existing attributes.

```bash
mvn generate-resources -Dasciidoctor.attributes=toc=right
```

--------------------------------

### Run Asciidoctor Conversion

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Execute the Maven goal to trigger the Asciidoctor conversion process configured in the `pom.xml`.

```bash
mvn generate-resources
```

--------------------------------

### Configure HTML Conversion in Maven

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/introduction.adoc

Configure the Asciidoctor Maven Plugin to convert AsciiDoc files to HTML. Specify the output directory and attributes like source highlighter, image directory, and table of contents.

```xml
<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>
```

--------------------------------

### Include Groovy Script

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/relative-path-treatment/level-1-1/HelloWorld22.adoc

Includes the content of the HelloWorld2.groovy script. This is useful for referencing external script logic within the Asciidoctor document.

```groovy
include::HelloWorld2.groovy[]
```

--------------------------------

### Include Remote File from GitHub

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/github-include.adoc

Include content directly from a remote URL, such as a file on GitHub. Requires a compatible Ruby environment.

```xml
include::https://raw.githubusercontent.com/cometd/cometd/4.0.x/pom.xml[]
```

--------------------------------

### Configure Version-Stamped Documentation Output

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Configure the Asciidoctor Maven Plugin to output documentation into version-specific subdirectories using Maven project properties for `revnumber` and `revdate`.

```xml
<configuration>
    <outputDirectory>target/generated-docs/${project.version}</outputDirectory>
    <attributes>
        <revnumber>${project.version}</revnumber>
        <revdate>${maven.build.timestamp}</revdate>
    </attributes>
</configuration>
```

--------------------------------

### Minimal Asciidoctor Maven Plugin Configuration

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/usage.adoc

Add this minimal configuration to your pom.xml to convert AsciiDoc documents to HTML. Ensure the plugin version is set appropriately.

```xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.maven.plugin.version}</version>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Configure Asciidoctor Auto-Refresh Goal

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Set up the `auto-refresh` goal to monitor source files for changes and automatically re-convert documents. Configure `interval` for refresh frequency and `refreshOn` (regex) to trigger a full rebuild on specific file changes.

```xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.2.0</version>
    <!-- Top-level config is used by auto-refresh when invoked directly -->
    <configuration>
        <preserveDirectories>true</preserveDirectories>
        <attributes>
            <source-highlighter>coderay</source-highlighter>
            <toc>left</toc>
            <icons>font</icons>
        </attributes>
        <!-- Check for changes every 1 second (default: 2000 ms) -->
        <interval>1000</interval>
        <!-- Full rebuild when any _include file changes -->
        <refreshOn>.*_.*\.adoc</refreshOn>
    </configuration>
    <executions>
        <execution>
            <id>auto-refresh-docs</id>
            <phase>generate-resources</phase>
            <goals><goal>auto-refresh</goal></goals>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Configure Asciidoctor to Warn on Missing Attributes and Fail Build

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/pages/tips-and-tricks.adoc

Configure the plugin to treat missing attributes as warnings and then fail the build if any warnings are encountered. This ensures that all attributes are correctly defined.

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

--------------------------------

### Include Non-Standard Source File Extensions

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Configure `sourceDocumentExtensions` to include files with extensions other than the default `.ad`, `.adoc`, or `.asciidoc` as AsciiDoc sources.

```xml
<configuration>
    <!-- Also pick up .txt files as AsciiDoc sources -->
    <sourceDocumentExtensions>
        <sourceDocumentExtension>txt</sourceDocumentExtension>
        <sourceDocumentExtension>asciidoc</sourceDocumentExtension>
    </sourceDocumentExtensions>
</configuration>
```

--------------------------------

### Configure Asciidoctor Log Handling and Build Failure

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Configure the `logHandler` to control AsciidoctorJ log messages and define conditions for Maven build failure. Set `failIf` with `severity` and/or `containsText` to trigger failures.

```xml
<configuration>
    <enableVerbose>true</enableVerbose> <!-- validate internal cross-references -->
    <logHandler>
        <!-- Print Asciidoctor messages as Maven INFO (default: true) -->
        <outputToConsole>true</outputToConsole>
        <!-- Fail after processing all sources, not on first error (default: true = fail fast) -->
        <failFast>false</failFast>
        <failIf>
            <!-- Fail on any message of severity WARN or higher -->
            <severity>WARN</severity>
            <!-- AND: only if the message text contains "include" -->
            <!-- <containsText>include</containsText> -->
        </failIf>
    </logHandler>
    <!-- Abort on missing attribute references -->
    <attributes>
        <attribute-missing>warn</attribute-missing>
    </attributes>
</configuration>
```

--------------------------------

### Configure Asciidoctor Parser Doxia Module in Maven Site

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Integrate the `asciidoctor-parser-doxia-module` with the `maven-site-plugin` to enable AsciiDoc processing for Maven sites. This configuration sets source highlighter and section numbering attributes, and excludes specific Asciidoc files.

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.21.0</version>
            <configuration>
                <asciidoc>
                    <attributes>
                        <source-highlighter>coderay</source-highlighter>
                        <sectnums>true</sectnums>
                    </attributes>
                </asciidoc>
                <moduleExcludes>
                    <asciidoc>**/_*.adoc,**/_*/</asciidoc>
                </moduleExcludes>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <!-- Parser module instead of Converter module -->
                    <artifactId>asciidoctor-parser-doxia-module</artifactId>
                    <version>3.2.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
```

--------------------------------

### Asciidoctor Extensions Configuration

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/partials/process-asciidoc-mojo-parameters.adoc

Configure Asciidoctor extensions, specifying the implementation class and optionally a block name for specific processor types. Extensions must be on the plugin's execution classpath.

```xml
<plugin>
    ...
    <executions>
        <execution>
            <configuration>
                ...
                <extensions>
                    <extension>
                        <className>org.asciidoctor.maven.SomePreprocessor</className>
                    </extension>
                    <extension>
                        <className>org.asciidoctor.maven.SomeBlockProcessor</className>
                        <blockName>yell</blockName>
                    </extension>
                </extensions>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency> &lt;!--1--&gt;
            <groupId>org.asciidoctor.maven</groupId>
            <artifactId>my-asciidoctor-extensions</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</plugin>
```

--------------------------------

### Include Maven POM Snippet

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-converter-doxia-module/src/it/maven-site-plugin/src/site/asciidoc/file-with-toc.adoc

This XML snippet demonstrates how to include a specific tagged section from a Maven POM file using Asciidoctor's include directive.

```xml
include::../../../pom.xml[tag=plugin-decl]
```

--------------------------------

### Set and Unset Boolean Attributes in XML

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/plugin/partials/setting-boolean-attributes.adoc

Demonstrates how to set boolean attributes to true or false using XML configuration. Use an empty tag or 'true' to enable, and 'false' to disable.

```xml
<embedded/>
<sectnums>true</sectnums>
<linkcss>false</linkcss>
```

--------------------------------

### Minimal Asciidoctor Maven Plugin Configuration

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/README.adoc

Configure the plugin in your pom.xml to convert AsciiDoc files during the generate-resources phase. Ensure the plugin version matches your project's requirements.

```xml
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>{release-version}</version>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Include HelloWorld2.groovy in Asciidoctor

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-maven-plugin/src/test/resources/src/asciidoctor/relative-path-treatment/level-1-1/HelloWorld2.adoc

This snippet shows how to include an external Groovy file within an Asciidoctor document. Ensure the HelloWorld2.groovy file is located in the correct relative path for the include directive to work.

```asciidoc
[source,groovy]
.HelloWorld2.groovy
----
include::HelloWorld2.groovy[]
----
```

--------------------------------

### Configure Asciidoctor Converter Doxia Module for Maven Site

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Integrate Asciidoctor with the maven-site-plugin for full-fidelity AsciiDoc support. Configure custom templates, extra Ruby gems, attributes, and logging.

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.21.0</version>
            <configuration>
                <asciidoc>
                    <!-- Custom Slim/ERB templates directory -->
                    <templateDirs>
                        <dir>src/site/asciidoc/templates</dir>
                    </templateDirs>
                    <!-- Extra Ruby gems (not bundled in AsciidoctorJ) -->
                    <requires>
                        <require>asciidoctor-diagram</require>
                    </requires>
                    <attributes>
                        <source-highlighter>coderay</source-highlighter>
                        <coderay-css>style</coderay-css>
                        <icons>font</icons>
                    </attributes>
                    <logHandler>
                        <outputToConsole>true</outputToConsole>
                        <failIf>
                            <severity>ERROR</severity>
                        </failIf>
                    </logHandler>
                </asciidoc>
                <!-- Exclude partial files (prefixed with _ ) -->
                <moduleExcludes>
                    <asciidoc>**/_*.adoc,**/_*/</asciidoc>
                </moduleExcludes>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-converter-doxia-module</artifactId>
                    <version>3.2.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
```

--------------------------------

### Update Maven Site Plugin Configuration

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/docs/modules/site-integration/pages/v3-migration-guide.adoc

When migrating to version 3.x.x, rename the maven-site-plugin dependency from `asciidoctor-maven-plugin` to `asciidoctor-converter-doxia-module`. Ensure the correct versions for the Doxia module and the plugin are specified.

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>{maven-site-plugin-version}</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>{doxia-compatible-module-name}</artifactId>
            <version>{release-version}</version>
        </dependency>
    </dependencies>
</plugin>
```

--------------------------------

### Maven Site Integration with Asciidoctor

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/README.adoc

Integrate Asciidoctor with the Maven site plugin by adding the asciidoctor-parser-doxia-module dependency. This allows AsciiDoc files to be processed as part of the Maven site generation.

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>{maven-site-plugin-version}</version>
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-parser-doxia-module</artifactId>
                    <version>{release-version}</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
```

--------------------------------

### Include Groovy Script

Source: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/main/asciidoctor-converter-doxia-module/src/test/resources/main-document.adoc

This snippet shows how to include a Groovy script file within an Asciidoctor document. Ensure the 'includes/groovy-include.groovy' file exists in the correct path.

```groovy
include::includes/groovy-include.groovy[]
```

--------------------------------

### Target Specific Source File

Source: https://context7.com/asciidoctor/asciidoctor-maven-plugin/llms.txt

Use `sourceDocumentName` to process a single named AsciiDoc file instead of an entire directory. Ensure `outputFile` and `backend` are also specified for this targeted conversion.

```xml
<configuration>
    <!-- Convert only the manual entry point -->
    <sourceDocumentName>manual.adoc</sourceDocumentName>
    <outputFile>${project.build.directory}/docs/manual.pdf</outputFile>
    <backend>pdf</backend>
</configuration>
```