asciidoctor-maven-demo

A small example that demonstrates how Asciidoctor can be used in Maven to generate multiple backends from shared sources:

• A multi-page Maven site with a navigation sidebar, using asciidoctor-maven-plugin Doxia asciidoc sink.

• A single-page HTML handbook, using asciidoctor-maven-plugin

• A PDF handbook, using asciidoctor-pdf

• A reveal.js presentation, using asciidoctor-reveal.js

• and Github’s rendering, based on Github markup

This is inspired by asciidoctor-maven-examples, but rather than having multiple sub-modules, it generates multiple outputs inside a single project, re-using the same base material.

Interesting bits

• Fallbacking from fonts to images for admonition on the Maven site

• Using leveloffset with includes, to integrate individual fragments

• Using ifdef::backend-* when content is only needed for a specific backend, in particular for rendering on github (see some tips)

• Including source code and linking to a generated Javadoc

• Including images from sub-templates, with relative paths

• Cross-section/page links

• Using unicode Dingbat circled digits to simulate callouts in diagrams

• Using Docinfo files and tocdoc to have an auto-expanded TOC

Build

To build the project:

mvn clean site

The build will fail in case of errors, warnings or infos reported by Asciidoctor.

Deployment

The built Maven site from master branch is automatically deployed to https://rquinio.github.io/asciidoctor-maven-demo:

• Travis CI does a force push to the branch gh-pages, using a GitHub API key stored in Travis settings - see deploy.sh

• rquinio.github.io repo uses a submodule pointing to gh-pages branch of this repo

• Update of sub-module is detected by GitHub Pages - see Using submodules with Pages