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:
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.
Installation
Add this line to your application’s Gemfile:
gem 'asciidoctor-diagram'
And then execute:
$ bundle
Or install it yourself as:
$ gem install asciidoctor-diagram
Additional Requirements
Certain diagram types require other tools to be installed seperately.
-
PlantUML and Graphviz: the Graphviz
dot
tool. -
Shaape: the Shaape Python package
-
Block/Seq/Act/Nw diag: the block/seq/act/nw diag Python packages
Usage
Enable the extensions
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/plantuml
: to enable the plantuml extension -
asciidoctor-diagram/shaape
: to enable the shaape 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.
Using the extensions
Once the extensions are enabled the following block types becomes available for your documents:
-
blockdiag
,actdiag
,seqdiag
,nwdiag
,rackdiag
andpacketdiag
-
ditaa
-
graphviz
-
plantuml
-
shaape
Detailed descriptions of the supported syntax inside these blocks is available on the PlantUML, Graphviz and ditaa websites.
At this point you can start adding diagrams to your application, like the following example:
["plantuml", "asciidoctor-diagram-classes", "png"]
---------------------------------------------------------------------
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock
BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
---------------------------------------------------------------------
The diagram blocks support the following attributes:
-
target
(or 2nd position): the basename of the file to generate. If not specified an auto-generated name will be used. -
format
(or 3rd position): 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 Adciidoctor Diagram library, otherwise your diagam 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
Contributing
-
Fork it
-
Create your feature branch (
git checkout -b my-new-feature
) -
Commit your changes (
git commit -am 'Add some feature'
) -
Push to the branch (
git push origin my-new-feature
) -
Create new Pull Request