GBIF Asciidoctor Toolkit

The toolkit

This is a Docker container derived from docker-asciidoctor, but with the addition of:

• Asciidoctor Multipage

• Asciidoctor Question

• GBIF templates and styling

• Custom GBIF macros and extensions

  • Glossary link formatting (dotted underlines) (applied automatically)

  • Plausible analytics (applied automatically)

  • Term macro (e.g. term:dwc[decimalLatitude])

  • Translation of labels (Translation of Page Contents labels etc, applied automatically)

  • Translation links ("This page is also available in…", applied automatically)

• GBIF document build script

The Asciidoctor Docker container provides:

• Asciidoctor

• Asciidoctor BibTeX

• Asciidoctor Diagram with Graphviz integration (supports plantuml and graphiz diagrams)

• Asciidoctor PDF

• Asciidoctor EPUB3

• Asciidoctor Mathematical

• AsciiMath

• Source highlighting using Pygments, CodeRay or Rouge

• Asciidoctor Confluence

How to use it

From the top-level directory containing the GBIF document named index.en.adoc (where en is normally a two-letter language code), run:

docker run --rm -it --user $(id -u):$(id -g) -v $PWD:/documents/ docker.gbif.org/asciidoctor-toolkit

Your documents will be processed, and output in the directory en (etc).

To have the HTML document build automatically as changes to the source files are saved, use

docker run --rm -it --user $(id -u):$(id -g) -v $PWD:/documents/ docker.gbif.org/asciidoctor-toolkit continuous

Component details

glossary extension

This adds a role (style) to [crossreference] links to the glossary, to avoid a "link soup" appearance where there are many such links.

term extension macros

The term extension macro converts e.g. term:dwc[basisOfRecord] into a styled link to the property URI.

GbifHtmlConverter.rb

This overrides particular methods of the Ruby converter.

• Handling short crossreferences with the § symbol without a following space, e.g. "§1.3"

• Inline syntax highlighting using the syntax [source,javascript`var x = [];]`

• "This document is also available in PDF format and in other languages: español, français, 中文." with the languageLinks[] macro.

Limitations

• PDF output does not support inline syntax highlighting, all fonts, or the custom admonitions used in the training courses.