Usage

In your AsciiDoc document, you can either write your diagram inline or reference a diagram file using the macro form or the include directive.

Inline diagram

Declare a diagram directly in your AsciiDoc document using the block syntax:

[graphviz]
----
digraph foo {
  node [style=rounded]
  node1 [shape=box]
  node2 [fillcolor=yellow, style="rounded,filled", shape=diamond]
  node3 [shape=record, label="{ a | b | c }"]

  node1 -> node2 -> node3
}
----
eNo9jjEOwjAMRfee4itzGKBzuEjVIaldWsnEVQBBVXp3AqQdLFlP 32bxkvy04BeFUsFRCVGc7vPwi7pIxJTW Ax88FP7IK NnZC048inYomN7OIPi3 tim6 QaYTOY m0Z 1bi31ltr4k4TWYgPLM4s8Hgj5Omwmrbanzicy Wy1NX6AUS2QVQ=

Macro form

Use the macro form to reference an external diagram file:

vegalite::chart.vlite[svg,role=chart,opts=interactive]
Vega-Lite chart example

The target can be a path relative to the document, an absolute path, or an http:///https:// URL, in which case the diagram source is downloaded:

plantuml::https://example.org/diagrams/hello.puml[svg]

Include directive

Use the include directive to embed a diagram file inline:

[plantuml,alice-bob,svg,role=sequence]
----
include::alice-bob.puml[]
----
PlantUML diagram example

Antora: references and includes

If you are using Asciidoctor Kroki with Antora, all file references and includes must use Antora Resource IDs. Place diagram source files (.puml, .vlite, etc.) in the partials directory of your module.

Block macros

vegalite::partial$chart.vlite[svg,role=chart,opts=interactive]

Includes

[plantuml,alice-bob,svg,role=sequence]
----
include::partial$alice-bob.puml[]
----

Vega-Lite: loading data from a resource ID

A Vega-Lite data.url can also reference an Antora resource ID, resolved the same way as a block macro target or an include:: directive:

[vegalite,ratio,svg]
----
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {"url": "example$lowpassfilter.csv"},
  "mark": "point"
}
----

The resource family prefix depends on where the data file lives: example$ for the examples directory, partial$ for partials, or attachment$ for attachments.

Linking to other Antora pages from a PlantUML diagram

To link from an element in a PlantUML diagram to another Antora page, first set kroki-default-format: svg and enable inline SVG (either allow-uri-read: true, or kroki-fetch-diagram: true with kroki-default-options: inline; see Options). Inlining the SVG is required for the link to be clickable: a diagram referenced as a plain image target has no interactive content.

asciidoc:
  attributes:
    allow-uri-read: true
    kroki-default-format: svg
    kroki-default-options: inline
  extensions:
    - asciidoctor-kroki

Then use PlantUML’s [[url label]] link syntax, building the URL from the standard Antora UI attributes (site-url, page-component-name, page-component-version):

[plantuml,my-diagram,subs=attributes]
----
include::partial$my-diagram.puml[]
----
partials/my-diagram.puml
@startuml
agent "[[{site-url}/{page-component-name}/{page-component-version}/other-module/home.html Other module]]" as other
@enduml

The subs=attributes substitution is required: a diagram block is verbatim by default, so docs.asciidoctor.org and the other attributes would otherwise be sent to Kroki unresolved.