Asciidoctor Diagram is a set of extensions for Asciidoctor, the Ruby-based AsciiDoc processor. These extensions allow you to embed plain text diagrams inside your AsciiDoc documents using one of the following syntaxes:
Additionally Asciidoctor Diagram includes a basic meme generator extension.
The extension takes care of running the diagram processor to generate the images from the input text and insert them into the rendered document.
This gem was inspired by the AsciiDoc PlantUML filter for AsciiDoc Python.
Add this line to your application’s Gemfile:
gem 'asciidoctor-diagram'
And then execute:
$ bundle
Or install it yourself as:
$ gem install asciidoctor-diagram
Certain diagram types require other tools to be installed seperately.
-
Block/Seq/Act/Nw diag: the block/seq/act/nw diag Python packages
-
Graphviz: the Graphviz package
-
Meme: ImageMagick
-
PlantUML: Graphviz package for certain diagram types.
-
Shaape: the Shaape Python package
-
WaveDrom: the WaveDrom editor application
The diagram extensions consist of a set of block processors for Asciidoctor. In order to use extensions you should need to invoke Asciidoctor via the Ruby API. In your script you can then either require one or more of the following files:
-
asciidoctor-diagram
: to enable all the diagramming extensions -
asciidoctor-diagram/blockdiag
: to enable the block/act/seq/nw diag extension -
asciidoctor-diagram/ditaa
: to enable the ditaa extension -
asciidoctor-diagram/graphviz
: to enable the graphviz extension -
asciidoctor-diagram/meme
: to enable the mermaid extension -
asciidoctor-diagram/mermaid
: to enable the mermaid extension -
asciidoctor-diagram/plantuml
: to enable the plantuml extension -
asciidoctor-diagram/shaape
: to enable the shaape extension -
asciidoctor-diagram/wavedrom
: to enable the wavedrom extension
Requiring one or more of these files will automatically register the extensions for all processed documents.
If you need more fine grained control over when the extensions are enabled or not, asciidoctor-diagram/ditaa/extension
, asciidoctor-diagram/graphviz/extension
and asciidoctor-diagram/plantuml/extension
can be used instead.
These load the extensions themselves but do not register them.
You should then register the extensions yourself at the appropriate time using the Asciidoctor::Extensions
API.
Once the extensions are enabled the following block types becomes available for your documents:
-
blockdiag
,actdiag
,seqdiag
,nwdiag
,rackdiag
andpacketdiag
-
ditaa
-
graphviz
-
meme
-
mermaid
-
plantuml
-
shaape
-
wavedrom
Detailed descriptions of the supported syntax inside these blocks is available on websites of the respective projects.
At this point you can start adding diagrams to your application. Here’s an example to get you started:
["plantuml", "asciidoctor-diagram-classes", "png"] --------------------------------------------------------------------- class BlockProcessor class DiagramBlock class DitaaBlock class PlantUmlBlock BlockProcessor <|-- DiagramBlock DiagramBlock <|-- DitaaBlock DiagramBlock <|-- PlantUmlBlock ---------------------------------------------------------------------
All the diagram blocks except meme
support the following attributes:
-
target
(1st positional attribute): the basename of the file to generate. If not specified an auto-generated name will be used. -
format
(2nd positional attribute): the output format. PlantUML blocks supportpng
,svg
andtxt
. Graphviz, Shaape and BlockDiag supportpng
andsvg
. Ditaa only supportspng
.
Once you have all of this in place and your original AsciiDoc file contains a diagram block, it’s time to build it into an HTML file with Asciidoctor Diagram magic! When executing Asciidoctor, you must reference the Asciidoctor Diagram library, otherwise your diagram blocks won’t be recognized as such. When executing Asciidoctor from the command line, do it using the -r parameter to reference this external library:
$ asciidoctor -r asciidoctor-diagram doc.adoc
If you don’t want to embed your diagram code in your document then you can use the diagram extension as block macros. The target of diagram block macro should refer to the file containing the diagram source code. The attributes for the block macros are the same as for the inline blocks. The example above in block macro form becomes
plantuml::mydiagram.puml["asciidoctor-diagram-classes", "png"]
The meme extension provides a basic 'Advice Animal' style image generator. It’s usage is easiest to explain with an example.
meme::doge.jpg[Perhaps haters...,Just hate to \\ love?]
The target of the block macro tells the extension which image to use as background.
The first two positional attributes are top
and bottom
and are used for the top and bottom label.
Occurrences of ` \\ ` are interpreted as line breaks.
The block macro also supports the following named attributes:
-
fillColor
: the fill color for the text. Defaults towhite
. -
strokeColor
: the outline color for the text. Defaults toblack
. -
strokeWidth
: the width of the text outline. Defaults to2
. -
font
: the font face to use for the text. Defaults toImpact
. -
options
: a comma separate list of flags that modify the image rendering. Currently onlynoupcase
is supported which disable upper casing the labels. -
target
(3rd positional attribute): the basename of the file to generate. If not specified an auto-generated name will be used. -
format
(4th positional attribute): the output image format. The meme extension supportspng
andgif
.