Render Mermaid diagrams from an included .mermaid-file

[mcbeelen]

User store

In order to being able to reuse diagrams and keep code isolated
As a site developer
I want to be able to include mermaid diagrams from source-files

If I want o render a mermaid diagram in the generated site the diagram as text currently has to be inside the

Current

[mermaid]
----
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;

Wanted

[mermaid]
----
include::flow.mermaid[]

First attempt

Mar 05, 2024 8:40:48 AM uri:classloader:/gems/asciidoctor-2.0.20/lib/asciidoctor/reader.rb preprocess_include_directive
SEVERE: <stdin>: line 8: include file not found: /var/model/flow.mermaid
Mar 05, 2024 8:40:48 AM uri:classloader:/gems/asciidoctor-2.0.20/lib/asciidoctor/reader.rb preprocess_include_directive
SEVERE: <stdin>: line 8: include file not found: /var/model/flow.mermaid
Mar 05, 2024 8:40:48 AM uri:classloader:/gems/asciidoctor-2.0.20/lib/asciidoctor/reader.rb preprocess_include_directive
SEVERE: <stdin>: line 8: include file not found: /var/model/flow.mermaid
Mar 05, 2024 8:40:48 AM uri:classloader:/gems/asciidoctor-2.0.20/lib/asciidoctor/reader.rb preprocess_include_directive
SEVERE: <stdin>: line 8: include file not found: /var/model/flow.mermaid

References

• Asciidoctor Kroki Includes

[mcbeelen]

In the workspace.dsl I have !docs docs
The fact that the .adoc-file and the included file reside in a subdirectory is lost when triggering the processing of the .adoc-file.

I'm running the site generator using docker on windows.
docker run -it --rm -p 8080:8080 -v %CD%:/var/model ghcr.io/avisi-cloud/structurizr-site-generatr generate-site -w workspace.dsl

[jp7677]

This scenario is indeed currently not supported, see https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/site/model/ToHtml.kt#L84

Since you are familiar with the topic and setup for this, any chance your could create a PR for this?

[mcbeelen]

@jp7677

I did some research into this topic in order to create a PR, but I fail to see a path forward. The problem I see is that there is a separation between the moment where the .adoc-files are being read and where the asciidocToHtml is being done.

Reading the files is being done as part of the Structurizr DSL DocsParser
The parsed workspace is handed down towards the asciidocToHtml function of the SiteGenerator
The comments in that function already indicate the wish to support partial includes.

The AsciiDoctor Options does not support setting a different basePath.

A possible solution could be found in a custom implementation of the DocumentationImporter and adjust the DSL to trigger the DocsParser to use that one.

The custom implementation might be given the responsibility to preprocess the content, resolve the includes and inline the partials into the content of the documentation. This would be aligned with the statement in the AsciiDoc documentation about include being a preprocessor directive

[jp7677]

Thanks for the assessment, yeah, looks like a non-trivial feature to implement correctly. Unfortunately we don't use AsciiDoc internally, so I would prefer if this is added by someone who is actually using this feature and knows how to use this in real life. The initial support for AsciiDoc was also a contribution. Sorry.