Adock

Adock is an Asciidoctor CLI wrapper that lets you compile and live preview Asciidoctor documents.

Here’s how to get started:

1. Make sure you have the following tools installed:

   1. Docker version 28.2.2 or later. You can check this by running docker --version.

2. Download the adock script and optionally put it in your PATH.

3. Run echo 'Hello, world!' >foo.adoc to create a simple Asciidoctor document, then run adock foo.adoc to compile it into foo.html.

4. Run adock -s foo.adoc to do the same thing as the previous step, but this time also running an HTTP server on 0.0.0.0:8080 to preview the document. Open http://127.0.0.1:8080 in a browser and click on foo.html to view the document. The document will be automatically recompiled and your browser will automatically refresh as you make changes to foo.adoc. When you’re done, press Ctrl+C to stop and remove the Docker container.

5. Run adock -ds foo.adoc to do the same thing as the previous step, but this time running the Docker container in the background instead of the foreground. When you’re done, run docker rm -f adock to stop and remove the Docker container.

6. Run adock -u to pull the latest version of the Docker image and download and replace adock itself with the latest version of adock.

7. For more advanced usage, see the man page.

Asciidoctor PDF support

Adock includes an Asciidoctor PDF theme file /adock-theme.yml that can be used to add KaTeX fonts to the font catalog. The fonts are named KaTeX_Main and KaTeX_Typewriter. The fonts also have some extra glyphs added to them. Here’s an example of how to use this in your own theme file:

extends:
  - /adock-theme.yml

base:
  font-family: KaTeX_Main

code:
  font-family: KaTeX_Typewriter

codespan:
  font-family: KaTeX_Typewriter

Math support

• Asciidoctor Mathematical is patched to improve the size of math expressions.

• Lasem, which is a dependency of Asciidoctor Mathematical, is patched with the following changes:

  • KaTeX fonts are used instead of generic fonts.

  • A bug that was preventing \mathtt from working is fixed.

Diagram support

Asciidoctor Diagram can be enabled using the -r option of asciidoctor with asciidoctor-diagram as the argument. For example: adock -r asciidoctor-diagram foo.adoc.

The following diagram types are supported:

• BPMN (example)

• Graphviz (example)

• Pikchr (example)

  • Pikchr is patched to allow \< and \> escapes to be used in strings, which emit < and > directly into the SVG code instead of > and <. This allows SVG tags such as <tspan> to be used. For example: box "\<tspan style=\"fill: red\"\>foo\</tspan\>".