<commit_before>asciidoctor-maven-plugin
========================
:asciidoc-url: http://asciidoc.org
:asciidoctor-url: http://asciidoctor.org
:issues: https://github.com/asciidoctor/asciidoctor-maven-plugin/issues
:maven-url: http://maven.apache.org/

image:http://img.shields.io/travis/asciidoctor/asciidoctor-maven-plugin/master.svg["Build Status", link="https://travis-ci.org/asciidoctor/asciidoctor-maven-plugin"]

The asciidoctor-maven-plugin is the official means of using {asciidoctor-url}[Asciidoctor] to render all your {asciidoc-url}[AsciiDoc] documentation using {maven-url}[Apache Maven].

== Installation

As this is a typical Maven plugin, there isn't much to do to use it, simply add it to your plugins section in your pom:

[source,xml]
.Plugin declaration
----
...
<plugins>
  <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.version}</version>                   <1>
    ...
  </plugin>
</plugins>
...
----

<1> As this plugin tracks the version of asciidoctor, you can use which every version of asciidoctor you prefer

== Usage

[source,xml]
.Execution setup
----
...
  <plugin>
    ...
    <executions>
      <execution>
        <id>output-html</id>                                    <1>
        <phase>generate-resources</phase>                       <2>
        <goals>
          <goal>process-asciidoc</goal>                         <3>
        </goals>
      </execution>
    </executions>
    ...
  </plugin>
...
----

<1> This is simply an unique id for the execution
<2> The asciidoctor-maven-plugin does not run in a specific phase, so one must be specified
<3> The (only for the moment) asciidoctor maven plugin goal

=== Configuration options

There are several configuration options that the asciidoctor-maven-plugin uses, which parallel the options in Asciidoctor:

sourceDirectory:: defaults to `${basedir}/src/main/asciidoc`
sourceDocumentName:: an override to process a single source file; defaults to all files in `${sourceDirectory}`
outputDirectory:: defaults to `${project.build.directory}/generated-docs`
baseDir:: (not maven's basedir) enables to set the root path for resouces (e.g. included files), defaults to `${sourceDirectory}`
preserveDirectories:: enables to specify whether the documents should be rendered in the same folder structure as in the source directory or not, defaults to `false`.
When `true`, instead of generating all output in a single folder, output files are generated in the same structure. See the following example
[source]
----
    ├── docs                          ├── docs
    │   ├── examples.adoc             │   ├── examples.html
    │   └── examples            =>    │   └── examples
    │       ├── html.adoc             │       ├── html.html
    │       └── docbook.adoc          │       └── docbook.html
    └── index.adoc                    └── index.html
----
relativeBaseDir:: only used when baseDir is not set, enables to specify that each AsciiDoc file must search for its resources in the same folder (for example, included files). Internally, for each AsciiDoc source, sets `baseDir` to the same path as the source file. Defaults to `false`
imagesDir:: defaults to `images`, which will be relative to the directory containing the source files
backend:: defaults to `docbook`
doctype:: defaults to `article`
eruby:: defaults to erb, the version used in jruby
headerFooter:: defaults to `true`
compact:: defaults to `false`
templateDir:: disabled by default, defaults to `null`
templateEngine:: disabled by default
sourceHighlighter:: enables and sets the source highlighter (currently `coderay` or `highlightjs` are supported)
attributes:: a `Map<String,Object>` of attributes to pass to Asciidoctor, defaults to `null`
extensions:: a `List<String>` of non-standard extensions to render. Currently ad, adoc, and asciidoc will be rendered by default.
embedAssets:: Embedd the CSS file, etc into the output, defaults to `false`

==== Builtin attributes

There are various attributes Asciidoctor recognizes. Below is a list of them and what they do::

title:: An override for the title of the document.

NOTE: This one, for backwards compatibility, can still be used in the top level configuration options.

Many other attributes are possible. Until a canonical list is created for asciidoctor, you may find http://asciidoc.org/userguide.html#X88[this list] to be helpful.

More will be added in the future to take advantage of other options and attributes of Asciidoctor.
Any setting in the attributes section that conflicts with an explicitly named attribute configuration will be overidden by the explicitly named attribute configuration.
These settings can all be changed in the `<configuration>` section of the plugin section:

[source,xml]
.Plugin configuration options
----
<plugin>
  ...
    </executions>
    <configuration>
      <sourceDirectory>src/main/doc</sourceDirectory>
      <outputDirectory>target/docs</outputDirectory>
      <backend>html</backend>
      <doctype>book</doctype>
      <attributes>
        <stylesheet>my-theme.css</stylesheet>
      </attributes>
    </configuration>
    ...
</plugin>
...
----

==== Passing POM properties

It is possible to pass properties defined in the POM to the Asciidoctor processor. This is handy for example to include in the generated document the POM artifact version number.

This is done by creating a custom Asciidoc property in the `attributes` section of the `configuration`. The Asciidoc property value is defined in the usual Maven way: `${myMavenProperty}`.

[source,xml]
----
<attributes>
    <docVersion>${project.version}</docVersion>
</attributes>
----

The custom Asciidoc property then be used in the document like this `Version: {docVersion}`.

==== Setting boolean values

Boolean attributes in asciidoctor, such as `numbered`, `toc`, `copycss` or `linkcss!` can be set with a value of `true` or unset (in the case of `linkcss` vs `linkcss!`) with a value of false.

=== Multiple outputs for the same file

Maven has the ability to execute a Mojo multiple times. Instead of reinventing the wheel inside the Mojo, we'll push this off to Maven to handle the multiple executions.
An example of this setup is below:

[source,xml]
.Multiple configuration extract
----
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>0.1.4</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceHighlighter>coderay</sourceHighlighter>
                <backend>html</backend>
                <attributes>
                    <toc/>
                    <linkcss>false</linkcss>
                </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>
        <headerFooter>true</headerFooter>
        <imagesDir>../resources/images</imagesDir>                  <1>
    </configuration>
</plugin>
----

<1> `imagesDir` should be relative to the source directory. It defaults to `images` but in this example the images used in the docs are also used elsewhere in the project.

Any configuration specified outside the executions section is inherited by each execution.
This allows an easier way of defining common configuration options.

== Maven Site Integration

To author your Maven-generated site in AsciiDoc, you must first add a dependency on the Asciidoctor plugin to your maven-site-plugin config:

[source,xml]
.Maven site integration
-----
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.2</version>
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>${asciidoctor.version}</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
-----

All of your AsciiDoc-based files should be placed in `src/site/asciidoc` with an extension of `.ad`.

For example, the file `src/site/asciidoc/usage.ad` will be rendered into `target/site/usage.html`.

As always, make sure you add a `menu` item for each page:

[source,xml]
-----
<body>
...
    <menu name="User guide">
        <item href="usage.html" name="Usage" />
    </menu>
...
</body>
-----

// == Watching for changes

// TODO

// == Zipping output into a bundle

// TODO

// == Previewing generated content in the browser

// TODO

== Hacking

Developer setup for hacking on this project isn't very difficult. The requirements are very small:

* Java
* Maven 3

Everything else will be brought in by Maven. This is a typical Maven Java project, nothing special. You should be able to use IntelliJ, Eclipse, or Netbeans
without any issue for hacking on the project.

== Building

Standard Maven build:

 mvn clean install

== Testing

http://spockframework.org/(Spock) is used for testing the calling of the Mojo. This will be downloaded by Maven. Tests are run simply by:

 mvn clean test

Or any of the other goals which run tests. If I can figure out a good way to setup a ruby testing environment I'll do that as well, but none exists at this time.

<commit_msg>Maven site integration uses .adoc, not .ad<commit_after>asciidoctor-maven-plugin
========================
:asciidoc-url: http://asciidoc.org
:asciidoctor-url: http://asciidoctor.org
:issues: https://github.com/asciidoctor/asciidoctor-maven-plugin/issues
:maven-url: http://maven.apache.org/

image:http://img.shields.io/travis/asciidoctor/asciidoctor-maven-plugin/master.svg["Build Status", link="https://travis-ci.org/asciidoctor/asciidoctor-maven-plugin"]

The asciidoctor-maven-plugin is the official means of using {asciidoctor-url}[Asciidoctor] to render all your {asciidoc-url}[AsciiDoc] documentation using {maven-url}[Apache Maven].

== Installation

As this is a typical Maven plugin, there isn't much to do to use it, simply add it to your plugins section in your pom:

[source,xml]
.Plugin declaration
----
...
<plugins>
  <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.version}</version>                   <1>
    ...
  </plugin>
</plugins>
...
----

<1> As this plugin tracks the version of asciidoctor, you can use which every version of asciidoctor you prefer

== Usage

[source,xml]
.Execution setup
----
...
  <plugin>
    ...
    <executions>
      <execution>
        <id>output-html</id>                                    <1>
        <phase>generate-resources</phase>                       <2>
        <goals>
          <goal>process-asciidoc</goal>                         <3>
        </goals>
      </execution>
    </executions>
    ...
  </plugin>
...
----

<1> This is simply an unique id for the execution
<2> The asciidoctor-maven-plugin does not run in a specific phase, so one must be specified
<3> The (only for the moment) asciidoctor maven plugin goal

=== Configuration options

There are several configuration options that the asciidoctor-maven-plugin uses, which parallel the options in Asciidoctor:

sourceDirectory:: defaults to `${basedir}/src/main/asciidoc`
sourceDocumentName:: an override to process a single source file; defaults to all files in `${sourceDirectory}`
outputDirectory:: defaults to `${project.build.directory}/generated-docs`
baseDir:: (not maven's basedir) enables to set the root path for resouces (e.g. included files), defaults to `${sourceDirectory}`
preserveDirectories:: enables to specify whether the documents should be rendered in the same folder structure as in the source directory or not, defaults to `false`.
When `true`, instead of generating all output in a single folder, output files are generated in the same structure. See the following example
[source]
----
    ├── docs                          ├── docs
    │   ├── examples.adoc             │   ├── examples.html
    │   └── examples            =>    │   └── examples
    │       ├── html.adoc             │       ├── html.html
    │       └── docbook.adoc          │       └── docbook.html
    └── index.adoc                    └── index.html
----
relativeBaseDir:: only used when baseDir is not set, enables to specify that each AsciiDoc file must search for its resources in the same folder (for example, included files). Internally, for each AsciiDoc source, sets `baseDir` to the same path as the source file. Defaults to `false`
imagesDir:: defaults to `images`, which will be relative to the directory containing the source files
backend:: defaults to `docbook`
doctype:: defaults to `article`
eruby:: defaults to erb, the version used in jruby
headerFooter:: defaults to `true`
compact:: defaults to `false`
templateDir:: disabled by default, defaults to `null`
templateEngine:: disabled by default
sourceHighlighter:: enables and sets the source highlighter (currently `coderay` or `highlightjs` are supported)
attributes:: a `Map<String,Object>` of attributes to pass to Asciidoctor, defaults to `null`
extensions:: a `List<String>` of non-standard extensions to render. Currently ad, adoc, and asciidoc will be rendered by default.
embedAssets:: Embedd the CSS file, etc into the output, defaults to `false`

==== Builtin attributes

There are various attributes Asciidoctor recognizes. Below is a list of them and what they do::

title:: An override for the title of the document.

NOTE: This one, for backwards compatibility, can still be used in the top level configuration options.

Many other attributes are possible. Until a canonical list is created for asciidoctor, you may find http://asciidoc.org/userguide.html#X88[this list] to be helpful.

More will be added in the future to take advantage of other options and attributes of Asciidoctor.
Any setting in the attributes section that conflicts with an explicitly named attribute configuration will be overidden by the explicitly named attribute configuration.
These settings can all be changed in the `<configuration>` section of the plugin section:

[source,xml]
.Plugin configuration options
----
<plugin>
  ...
    </executions>
    <configuration>
      <sourceDirectory>src/main/doc</sourceDirectory>
      <outputDirectory>target/docs</outputDirectory>
      <backend>html</backend>
      <doctype>book</doctype>
      <attributes>
        <stylesheet>my-theme.css</stylesheet>
      </attributes>
    </configuration>
    ...
</plugin>
...
----

==== Passing POM properties

It is possible to pass properties defined in the POM to the Asciidoctor processor. This is handy for example to include in the generated document the POM artifact version number.

This is done by creating a custom Asciidoc property in the `attributes` section of the `configuration`. The Asciidoc property value is defined in the usual Maven way: `${myMavenProperty}`.

[source,xml]
----
<attributes>
    <docVersion>${project.version}</docVersion>
</attributes>
----

The custom Asciidoc property then be used in the document like this `Version: {docVersion}`.

==== Setting boolean values

Boolean attributes in asciidoctor, such as `numbered`, `toc`, `copycss` or `linkcss!` can be set with a value of `true` or unset (in the case of `linkcss` vs `linkcss!`) with a value of false.

=== Multiple outputs for the same file

Maven has the ability to execute a Mojo multiple times. Instead of reinventing the wheel inside the Mojo, we'll push this off to Maven to handle the multiple executions.
An example of this setup is below:

[source,xml]
.Multiple configuration extract
----
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>0.1.4</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceHighlighter>coderay</sourceHighlighter>
                <backend>html</backend>
                <attributes>
                    <toc/>
                    <linkcss>false</linkcss>
                </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>
        <headerFooter>true</headerFooter>
        <imagesDir>../resources/images</imagesDir>                  <1>
    </configuration>
</plugin>
----

<1> `imagesDir` should be relative to the source directory. It defaults to `images` but in this example the images used in the docs are also used elsewhere in the project.

Any configuration specified outside the executions section is inherited by each execution.
This allows an easier way of defining common configuration options.

== Maven Site Integration

To author your Maven-generated site in AsciiDoc, you must first add a dependency on the Asciidoctor plugin to your maven-site-plugin config:

[source,xml]
.Maven site integration
-----
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.2</version>
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>${asciidoctor.version}</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
-----

All of your AsciiDoc-based files should be placed in `src/site/asciidoc` with an extension of `.adoc`.

For example, the file `src/site/asciidoc/usage.adoc` will be rendered into `target/site/usage.html`.

As always, make sure you add a `menu` item for each page:

[source,xml]
-----
<body>
...
    <menu name="User guide">
        <item href="usage.html" name="Usage" />
    </menu>
...
</body>
-----

// == Watching for changes

// TODO

// == Zipping output into a bundle

// TODO

// == Previewing generated content in the browser

// TODO

== Hacking

Developer setup for hacking on this project isn't very difficult. The requirements are very small:

* Java
* Maven 3

Everything else will be brought in by Maven. This is a typical Maven Java project, nothing special. You should be able to use IntelliJ, Eclipse, or Netbeans
without any issue for hacking on the project.

== Building

Standard Maven build:

 mvn clean install

== Testing

http://spockframework.org/(Spock) is used for testing the calling of the Mojo. This will be downloaded by Maven. Tests are run simply by:

 mvn clean test

Or any of the other goals which run tests. If I can figure out a good way to setup a ruby testing environment I'll do that as well, but none exists at this time.


{'fraction_non_alphanumeric': 0.10423698926898081, 'fraction_numerical': 0.0018136933850571818, 'mean_word_length': 2.9283593904611123, 'pattern_counts': {'":': 0, '<': 283, '<?xml version=': 0, '>': 285, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 14}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3889864', 'n_tokens_mistral': 5546, 'n_tokens_neox': 5403, 'n_words': 2094}