PlantUML/Kroki do support interactive diagrams when format is SVG, but the plugin preview cannot handle such links

[andi-huber]

Given this adoc example we expect the diagram to have a note with a http link to www.google.com. We can use kroki to preview the expected outcome: https://kroki.io/plantuml/svg/eNpLzkksLlZwSc3N58rLL0lVKMpMzyjhio7OKCkpKLbS1y8vL9dLz89Pz0nVS87PjY3lSs1LUQCpBABUGRST

[plantuml%interactive,demo,svg]
----
class Demo
note right
[[https://www.google.com]]
end note
----

The asciidoctor-intellij-plugin does render a preview of the above and it looks as expected. However, the http link to www.google.com is not interactively usable. (Clicking on it does not resolve the underlying URL).

To make things even more complicated, we have a use-case, where instead of linking to external URLs, we link to pages on the same site, using relative URLs. This allows for an interesting idea: Have a system overview diagram, where the user (interested reader) can interactively click on subsystems shown, such that a more detailed diagram opens. Inspired by the c4 model.

We already have a proof of concept that this works with Antora, meaning we build the site with Antora, use kroki as diagram engine and apply the following playbook settings:

asciidoc:
  extensions:
    - asciidoctor-kroki # requires: npm i ... @asciidoctor/core@2.2.0 asciidoctor-kroki
    - ./antora/lib/lorem
    - ./antora/lib/jira-issue
  attributes:
    experimental: ""
    idprefix: ""
    idseparator: "-"
    # kroki
    # for more options see https://github.com/Mogztter/asciidoctor-kroki
    kroki-default-format: svg # (default)
    kroki-default-options: interactive # only available for SVG
    kroki-fetch-diagram: true
    kroki-server-url: https://kroki.io # (default)

I don't care too much about external links for the preview. But a really cool feature would be to resolve site-local page links, that are referenced from within such interactive diagrams. Meaning, when I click on a diagram link that refers to a page on the same IntelliJ project, that the preview is smart enough to change the IDE's focus to this referenced page, such that the preview then automatically renders the page that just got the focus.

AsciiDoc Plugin Version: 0.31.20

IDE Name and Version: IntelliJ IDEA 2020.2.1 (Community Edition) Build #IC-202.6948.69, built on August 24, 2020 Runtime version: 11.0.8+10-b944.31 amd64 VM: OpenJDK 64-Bit Server VM by JetBrains s.r.o. Windows 10 10.0 GC: ParNew, ConcurrentMarkSweep Memory: 1979M Cores: 16 Registry: ide.tooltip.initialDelay=590, ide.balloon.shadow.size=0 Non-Bundled Plugins: Lombook Plugin, SequenceDiagram, com.jetbrains.ChooseRuntime, com.mallowigi, MavenRunHelper, in.1ton.idea.spring.assistant.plugin, org.jetbrains.kotlin, com.chrisrm.idea.MaterialThemeUI, org.asciidoctor.intellij.asciidoc

[andi-huber]

[ahus1]

Hi @andi-huber, the AsciiDoc plugin for IntelliJ currently renders all PlantUML diagrams als PNG.

This is a legacy as the old JavaFX and Swing previews didn't display SVG correctly. The AsciiDoc plugin for IntelliJ tweaks the SVG to PNG on the fly.

As JCEF preview is available from 2020.2+, it is now time to disable the workaround for JCEF. I haven't found the time yet, but I'll track the progress of this in this ticket.

[andi-huber]

Thx for tracking this! Also note, as I have a feeling, this feature request (resolve site-local page links) might not be trivial to implement, I just want to let you know, that unless there are others that vote this one up, its also fine with me, if you say 'won't fix ... too much effort'.

[ahus1]

There is now pre-release 0.31.25 that implements most of the functionality asked for. It turned out that I needed to modify more than one place to make it work.

When using JCEF both Asciidoctor Diagram and Kroki

• will use SVG when this is indicated via the parameter
• support interactive and inline mode
• only when using inline mode the plugin will intercept links. Internal links will open in the editor of the IDE (if it manages to resolve them) and external URLs open in the browser. When using interactive, external links will open in the preview and internal links will most likely be broken unless the file exists

Why it didn't work out for interactive: The redirection is based on some JavaScript that processes the rendered HTML. I wasn't able to access the SVG from JavaScript when it is only interactive, that is within an <object>, possibly due to a CORS issue when using local file:// urls. Therefore please use inline instead.

I've added an example to the documentation and described some ins-and-outs and caveats. If you find something is missing or unclear, please create a pull request for the docs (located in this repository in "/doc").

I didn't test a complex Antora example to see if local links work out. Once you have an example ready and some links don't work out, please share it in a branch or as a snippet so I can investigate.

I leave this issue open. Please let me know how this works for you.

The pre-release of the plugin is available from GitHub releases and the IntelliJ AsciiDoc EAP repository.

[andi-huber]

With the pre-release 0.31.25 installed, I was able to verify that site internal links do get resolved. Great stuff!

What I discovered in the process:

• I was not able to get the preview working, when I enabled kroki in the plugin (even when using allow-uri-read as mentioned in the docs).
• The preview does generate svg- (and when switching format, also png-) files for any diagrams declared and places them into the same folder where the originating adoc file resides. I guess that happens when using inline mode.
• The Antora build only works with interactive mode, and fails with inline mode: SecurityError: Jail is not an absolute path: modules/ROOT/pages/demo ... I did find your workaround in the docs, but did not try yet.

So I guess there are 2 desired solutions, either the interactive mode can be fixed to work for site internal links, or those image files can be created else where and automatically purged when no longer needed.

[andi-huber]

My example setup that does work with Antora (interactive):

pages/demo
+---diagram1.adoc
+---diagram2.adoc

diagram1.adoc

[plantuml%interactive,diagram1,svg]
----
class Demo1
note right
[[../demo/diagram2 link to Diagram-2]]
end note
----

diagram2.adoc

[plantuml%interactive,diagram2,svg]
----
class Demo2
note right
[[../demo/diagram1 link to Diagram-1]]
end note
----

[ahus1]

I checked and placing temporary files in the project folder was a regression. I fix this in the new pre-release 0.31.26. So this got one of your desired solutions working I suppose.

The pre-release of the plugin is available from GitHub releases and the IntelliJ AsciiDoc EAP repository.

As I said, interactive is not linking to editor files as of now; it will need some more fiddling/thought on my side if/how that can be done.

About Kroki preview: Adding attributes to the plugin's settings is a bit tricky from the UI perspective. Sometimes you'll need to click outside of the text field/into another text field until the "Apply" button activates. Please double check and go to the settings if it has been saved properly.

You could add this small snippet to see if it has been set successfully by adding this to the source in the editor and watch if the text appears in the preview:

ifdef::allow-uri-read[allow-uri-read is set!]

[andi-huber]

Indeed pre-release 0.31.26 no longer creates those temporary image files in the current directory.

Also figured out that my kroki issues had been due to diagram syntax errors when testing these. (was feeding c4plantuml syntax, to kroki's plantuml endpoint)

I'm now able to have both working, the preview and the Antora build, by adding following 2 lines to every adoc file that provides diagrams:

:plantuml-opts: interactive
ifdef::env-idea[:plantuml-opts: inline]

[plantuml, diagram1, svg, opts="{plantuml-opts}"]
----
class Demo1
note right
[[../demo/diagram2 link to Diagram-2]]
end note
----

Out of curiosity, is there some way to declare this plantuml-opts logic at one place for the entire site?

[ahus1]

You could put the settings in different places: one with "interactive" where only Antora sees it, and one with "inline" where only the plugin sees it.

The plugin doesn't look in the Antora playbook, so you can put :plantuml-opts: interactive (in YAML syntax) into the playbook.

Antora doesn't know about the .asciidoctorconfig files the plugin supports. Place such a file in any parent folder where your components are, and put :plantuml-opts: inline into the file. To be extra-safe you could the whole two-line prefix in there.

Read more about the .asciidoctorconfig file here. Hopefully the docs from the Wiki will move over to the manual soon. Please note that while the plugin supports preprocessor macros in an .asciidoctorconfig file, you'll need to name it .asciidoctorconfig.adoc if you want to use it as a standard include to make preprocessor macros work.

Let me know if this works out for you.

[andi-huber]

Yes that works. (Antora + Preview)

@ahus1 impressive commitment, thank you sir!

[ahus1]

You're welcome. I'm looking forward to a link once you have a working example online.

[andi-huber]

I'm working on automated ascii-doc generation (written in Java) doing source-code mining on the Apache Isis project, also inspired by structurizr. As a starting point I want some documentation auto-created based on the discovered maven/gradle project structure at a top level, where one can then dive into, to discover more details. Was experimenting with plantuml diagrams to visualize these tree structures, but yet found these rendered graphs a little bit too large. Instead I'll resort to ascii-doc tables for that.

However, we still want some hand-written c4 style system overview diagrams I suppose, that also can be dived into interactively. So once we have some working examples online, I'll let you know.

[ahus1]

I need to update my findings: the latest release of kroki requires "opts=inline", but asciidoctor-diagram requires "svg-type=inline". I updated the docs, and will raise this with asciidoctor-diagram.