Diagram Blocks
Embedded diagrams are written using diagram blocks. Diagram blocks are delimited using either the literal or listing delimiter.
Diagram Block Structure
All diagram block types share a similar structure.
[diagram-type, target=output-file-name, format=output-format] (1) (2) (3) .... (4) Diagram code (5) ....
| 1 | The first value in the attribute list specifies the diagram syntax that is being used. |
| 2 | The target attribute specifies the basename of the image file that will be generated. If this attribute is omitted an auto-generated name will be used instead. |
| 3 | The format attribute determines the output image format to use. If a format is not specified, the default output format for the chosen diagram type will be used. |
| 4 | The asciidoc block type can be literal (….), listing (----) or open --. |
| 5 | The block content is written in syntax of the chosen diagramming tool. |
Diagram Macros
The diagram extensions can also be used in inline, or block macro form.
diagram-type::source-file-name[format=output-format] (1) (2) (3)
| 1 | The macro name specifies the diagram syntax that is being used. |
| 2 | The source file name specifies the external file that contains the diagram source code. |
| 3 | The format attribute determines the output image format to use. If a format is not specified, the default output format for the chosen diagram type will be used. |
When the source file name is a relative path it is resolved with respect to the location of the document being processed.
Diagram Attributes
Some diagram types allow image generation to be customized using attributes.
Attributes can be assigned to individual diagram blocks by adding them to the attribute list of the block.
If the same attribute value should be applied to all blocks of a given diagram type, the attribute can also be assigned indirectly by defining an attribute at the document level. The attribute name at the document level should be prefixed with the diagram type name and a dash.
This is illustrated for the blockdiag fontpath attribute in the example below.
= Asciidoctor Diagram :blockdiag-fontpath: /path/to/font.ttf (1) [blockdiag] (2) .... .... [blockdiag, fontpath="/path/to/otherfont.ttf"] (3) .... ....
| 1 | Attributes can be specified for all diagram of a certain type at the document level by prefixing them with <blocktype>-.
In this example, the fontpath attribute is specified for all diagrams of type blockdiag. |
| 2 | The first diagram does not specify an explicit value for fontpath so the global blockdiag-fontpath value will be used |
| 3 | The second diagram does specify a fontpath value.
This overrides the global blockdiag-fontpath value. |
Common Attributes
A number of attributes are common to all diagram types.
These can be specified per block using their name, for each block of a diagram type using the diagram type as prefix, or globally for all diagram blocks using the diagram- prefix.
| Name | Default value | Description |
|---|---|---|
nocache |
unset |
When set disables the diagram cache. |
cachedir |
.asciidoctor/diagram |
The directory in which to write diagram cache entries |
svg-type |
unspecified |
When the output format is SVG, this attribute determines the SVG interactivity level. |
Example
The example below illustrates the structure of a basic ditaa block written directly in an AsciiDoc document.
[ditaa]
....
+-------------+
| Asciidoctor |-------+
| diagram | |
+-------------+ | PNG out
^ |
| ditaa in |
| v
+--------+ +--------+----+ /---------------\
| | --+ Asciidoctor +--> | |
| Text | +-------------+ | Beautiful |
|Document| | !magic! | | Output |
| {d}| | | | |
+---+----+ +-------------+ \---------------/
: ^
| Lots of work |
+-----------------------------------+
....The ditaa block above results in the following diagram.
The rendered ditaa diagram above gets the file name 58372f7d2ceffae9e91fd0a7cbb080b6.png.
That long number is the checksum of the source code calculated by asciidoctor-diagram.
If you want to give your image files a more meaningful name, fill in the target attribute.
This can be done by either specifying it as the second positional attribute or as a named attribute.
Both examples below would result in a file called ditaa-diagram.png.
[ditaa, target="ditaa-diagram"] ---- <snip> ---- [ditaa, "ditaa-diagram"] ---- <snip> ----