Diagram Blocks
Embedded diagrams are written using diagram blocks. Diagram blocks are delimited using either the literal or listing delimiter. which can accept several attributes.
All diagram block types share a similar structure.
[diagram-type, target=output-file-name, format=output-format] (1) (2) (3) .... (4) Diagram in appropriate syntax ....
| 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 | Place the attribute list directly on top of the delimited literal block (....). You can also use an open block as an alternative (--). |
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.
Specifying 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. |
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> ----
The example below illustrates the structure of a basic PlantUML block written directly in an AsciiDoc document.
[plantuml, target=diagram-classes, format=png] (1) (2) (3)
....
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock
BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....| 1 | The diagram is written in PlantUML so the first positional attribute is assigned the plantuml diagram type. |
| 2 | The name of the diagram file is given by the target attribute. |
| 3 | The output format is specified using the format attribute |
