Asciidoctor Maven Plugin: Examples

This repository contains a collection of sample projects that demonstrate numerous ways to use the Asciidoctor Maven plugin in a Maven project.

Getting the examples

Clone the example repository using git:

$ git clone https://github.com/asciidoctor/asciidoctor-maven-examples

Refer to the README file in each individual project to learn how to run it.

Example catalog

asciidoc-to-html-example (aka “The Quickstart”): Demonstrates how to convert AsciiDoc to HTML5 using the Asciidoctor Maven plugin.
docbook-pipeline-docbkx-example: Demonstrates how to convert AsciiDoc to DocBook and feed it to the DocBook pipeline to generate a PDF using the Asciidoctor and Docbkx Maven plugins.
docbook-pipeline-jdocbook-example: Demonstrates how to convert AsciiDoc to DocBook and feed it to the DocBook pipeline to generate a PDF using the Asciidoctor and jDocBook Maven plugins.
asciidoctor-diagram-example: Demonstrates how to integrate Asciidoctor Diagram with the Asciidoctor Maven plugin.
asciidoctor-pdf-example: Demonstrates how to convert AsciiDoc to PDF using Asciidoctor PDF with the Asciidoctor Maven plugin.
asciidoc-maven-site-example: Demonstrates how to process AsciiDoc in a Maven site using the Asciidoctor Maven plugin.
asciidoc-multiple-inputs-example: An example project that demonstrates how to convert multiple input AsciiDoc documents to HTML5 and PDF using the Asciidoctor Maven plugin.
java-extension-example: An example project that demonstrates how to create an extension for Asciidoctorj (written in Java) and how to use it in an other documentation Maven module.
asciidoc-to-revealjs-example: Demonstrates how to convert AsciiDoc to reveal.js using Asciidoctor revealjs with the Asciidoctor Maven plugin.

Root pom.xml

The root pom.xml (aggregate build) is provided to allow you to run all the example projects at once using a single invocation of Maven. It also drives the continuous integration (CI) build. The root pom.xml does not contain any shared build configuration so that each of the projects can be used independently. This makes the examples suitable as independent references and as a starting point for your own project.

Usage

Invoke the compile goal (configured as the default goal) on this folder (asciidoctor-maven-example):

$ mvn

On JRuby dependency

Asciidoctor Maven plugin relies on asciidoctor project to do the actual rendering. This is a Ruby implementation integrated thanks to the JRuby project, which is a required dependency to run the plugin. The maven plugin provides a default version of the jruby-complete artifact to ease its configuration. However, it can be overwritten just adding a custom version in the plugin’s dependency section as seen in the following example:

  <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>${asciidoctor.maven.plugin.version}</version>
      <dependencies>
          <dependency>
              <groupId>org.jruby</groupId>
              <artifactId>jruby-complete</artifactId>
              <version>${jruby.version}</version>
          </dependency>
      <dependencies>
  </plugin>

Updating Asciidoctor Maven plugin version

In case it is required to test a specific version of the plugin (e.g. local SNAPSHOT version), a tool has been included to update the version in all examples. Properties can be updated in two ways.

First, define the new versions using the versions system property, this will update in examples as well as in the parent. The following example shows how to update two properties.

  $ mvn validate -Pupdate-properties -Dversions=asciidoctor.maven.plugin.version=1.6.0-SNAPSHOT,asciidoctorj.pdf.version=1.5.0-alpha.12

Secondly, copying the properties values from the parent pom to the example projects. For example, to change the plugin’s version follow the next steps:
1. Set the desired version in the <asciidoctor.maven.plugin.version> property in the pom.xml file located at the root (asciidoctor-maven-examples folder). For instance:

  <asciidoctor.maven.plugin.version>1.6.0-SNAPSHOT</asciidoctor.maven.plugin.version>

Execute the validate maven goal with the update-properties profile:

  $ mvn validate -Pupdate-properties

Contributing

We want you! Yes, you.

Anyone can contribute to an Asciidoctor project. If you have a specialty, or just some creativity to share, we need your participation. We have big aspirations for the project and we need an assortment of skill sets in order to reach them. Make no mistake, contributing is not just for developers.

Of course, we’ll always need help with the code as it’s the basis of the project. But code isn’t going to make the project successful alone. We also need documentation, automation, design, marketing, communication, advocacy and more for it to make an impact.

Here are just a few of the ways you can contribute to the project:

Reporting bugs (The easiest way to get started!)
Sharing ideas on http://discuss.asciidoctor.org
Suggesting new feature or improvements in the issue tracker
Speaking about the technology
Advocating for the technology
Assisting with design and/or UX (stylesheets, themes, logos, etc)
Conducting user studies and collecting feedback
Automating system administration tasks (releases, changelog, announcements, hosting, etc)
Writing, editing or maintaining the documentation
Organizing the content (information architecture & content strategy)
Using or extending the software in a creative way
Testing a prerelease, a pull request or master
Reviewing or providing feedback on pull requests
Writing code (No patch is too small!)
- Fixing typos
- Adding or revising comments or API docs
- Fixing issues
- Writing tests
- Refactoring the code
Something we haven’t suggested…seriously!

The best way to get involved is just to show up and express your interest. We have a very friendly and encouraging culture. Harassment or offensive behavior is simply not tolerated. We are positive, even when being critical. We also strive to lift others up and help them be successful. We want your choice to participate in an Asciidoctor project be the start of an exciting and rewarding journey. So thanks for showing up!

Code conventions

Even when this project does not contain much code, we encourage the following good practices to improve accessibility and ease the use of the examples:

Document relevant details of an example in the appropriate README file
- what makes this example useful
- relevant components used (backends, extensions, …)
- how to execute the example and see the results
- possible use scenarios
Comment relevant Java methods and classes, especially when writing extensions
Follow simples code conventions to improve readability on the web
- Use 4 white spaces instead of tabs
- Avoid long lines in the Java code (they’re good in AsciiDoc files though)

To help fixing some style conventions a small script has been included. Currently, it only checks for tabs, which should be replaced by white spaces. To see what files contain some inconsistency, run this command from the parent project.

  $ mvn validate -Pcheck-styles

If you want it to fix the issues for you, just add -Dfix to the command.

  $ mvn validate -Pcheck-styles -Dfix

Copyright and Licensing

See the LICENSE.adoc file for details.

jh12z/asciidoctor-maven-examples