Explain how to link Antora objects inside PlantUML diagrams

[ggrossetie]

Integrate the following procedure in the documentation to explain how to link Antora objects inside PlantUML diagrams.

Cyrille Chopelet said:

I am very interested in combining Puml and Antora. My goal was to link from Puml objects inside Puml diagrams (which are included in the Antora generated documentation) to Antora content. But I did not find a solution and I gave up. Did you?

I suppose you mean "link Antora objects inside Puml diagrams?"

If so, yeah, I think I found a way. The project is corporate and not open-source, so I can't give you the repo. I'll try to write something a bit more elaborate soon, but here are some pointers to get started with:

Use asciidoctor-kroki

Use asciidoctor-kroki as your diagram extension, not asciidoctor-plantuml: you need to inline the generated diagrams and asciidoctor-plantuml is not capable of that at the moment (see this topic: https://antora.zulipchat.com/#narrow/stream/282400-users/topic/Inlining.20and.20styling.20PlantUML.20SVG.20diagrams)

Generate inline SVGs

Add the following options in your Antora playbook ("interactive" instead of "inline" should also work):

asciidoc:
    attributes:
        # Allow URI read to retrieve SVG on compilation
        allow-uri-read: true
        # use SVG unless otherwise specified
        kroki-default-format: svg
        # Make SVG inline so that we can get interactive (can be overridden by schema with "opts=none")
        kroki-default-options: inline
    extensions:
        - asciidoctor-kroki

Insert links in your diagrams

The syntax should be something like the following:

agent "[[{site-url}/{page-component-name}/{page-component-version}/myothermodule/home.html MyModule]]" as mymodule

Get Asciidoctor to process attributes

By default, a diagram block is verbatim (no substitution applied). You must explicitly tell Antora/Asciidoc to apply substitutions. See https://docs.asciidoctor.org/asciidoc/latest/subs/apply-subs-to-blocks/

So in my case, I wrote this:

[plantuml,my-diagram,subs=attributes]
----
include::partial$diagrams/my-diagram.plantuml[]
----

If you use a macro instead of my hard-to-read and brittle URL, you should use [plantuml,my-diagram,subs=macros] instead.

Hope this helps!