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.

asciidoctor-epub-example

Demonstrates how to convert AsciiDoc to epub using Asciidoctor EPUB with the Asciidoctor Maven plugin. (contains also an example for .mobi (Kindle) output)

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>2.2.1</asciidoctor.maven.plugin.version>

2. 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 https://asciidoctor.zulipchat.com/ or https://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

Copyright © 2014 The Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.

See the LICENSE.adoc file for details.