mermaid: links support (#1482)

Author: MykolaGolubyev

znai-cli/src/main/resources/simplelogger.properties

@@ -0,0 +1 @@
+org.slf4j.simpleLogger.log.io.netty.resolver.dns.DnsServerAddressStreamProviders=off

znai-diagrams/src/main/java/org/testingisdocumenting/znai/diagrams/mermaid/MermaidFencePlugin.java

@@ -52,7 +52,9 @@ public PluginResult process(ComponentsRegistry componentsRegistry, Path markupPa
         this.content = content;
         Map<String, Object> props = new LinkedHashMap<>(pluginParams.getOpts().toMap());
         processIconPacks(componentsRegistry, props);
-        props.put("mermaid", content);
+
+        String processedContent = processLinks(componentsRegistry, markupPath, content);
+        props.put("mermaid", processedContent);
 
         return PluginResult.docElement("Mermaid", props);
     }

znai-diagrams/src/main/java/org/testingisdocumenting/znai/diagrams/mermaid/MermaidIncludePlugin.java

@@ -57,7 +57,9 @@ public PluginResult process(ComponentsRegistry componentsRegistry, ParserHandler
         content = componentsRegistry.resourceResolver().textContent(mermaidPath);
 
         Map<String, Object> props = new LinkedHashMap<>(pluginParams.getOpts().toMap());
-        props.put("mermaid", content);
+
+        String processedContent = processLinks(componentsRegistry, markupPath, content);
+        props.put("mermaid", processedContent);
         processIconPacks(componentsRegistry, props);
         return PluginResult.docElement("Mermaid", props);
     }

znai-diagrams/src/main/java/org/testingisdocumenting/znai/diagrams/mermaid/MermaidLinkResolver.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2026 znai maintainers
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.testingisdocumenting.znai.diagrams.mermaid;
+
+import org.testingisdocumenting.znai.structure.DocStructure;
+import org.testingisdocumenting.znai.structure.DocUrl;
+import org.testingisdocumenting.znai.utils.UrlUtils;
+
+import java.nio.file.Path;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+class MermaidLinkResolver {
+    // matches: click nodeId "url" or click nodeId href "url"
+    private static final Pattern CLICK_URL_PATTERN = Pattern.compile(
+            "click\\s+\\S+\\s+(?:href\\s+)?\"([^\"]+)\"");
+
+    private MermaidLinkResolver() {
+    }
+
+    static String validateAndResolveLinks(DocStructure docStructure, Path markupPath, String mermaidContent) {
+        Matcher matcher = CLICK_URL_PATTERN.matcher(mermaidContent);
+        StringBuilder result = new StringBuilder();
+        while (matcher.find()) {
+            String url = matcher.group(1);
+            if (UrlUtils.isExternal(url)) {
+                matcher.appendReplacement(result, Matcher.quoteReplacement(matcher.group()));
+                continue;
+            }
+
+            DocUrl docUrl = new DocUrl(url);
+            docStructure.validateUrl(markupPath, "inside mermaid diagram", docUrl);
+
+            String resolvedUrl = docStructure.createUrl(markupPath, docUrl);
+            String replacement = matcher.group().replace("\"" + url + "\"", "\"" + resolvedUrl + "\"");
+            matcher.appendReplacement(result, Matcher.quoteReplacement(replacement));
+        }
+        matcher.appendTail(result);
+        return result.toString();
+    }
+}

znai-diagrams/src/main/java/org/testingisdocumenting/znai/diagrams/mermaid/MermaidPluginBase.java

@@ -23,6 +23,7 @@
 import org.testingisdocumenting.znai.structure.DocStructure;
 import org.testingisdocumenting.znai.utils.UrlUtils;
 
+import java.nio.file.Path;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -35,17 +36,18 @@ public Stream<AuxiliaryFile> auxiliaryFiles(ComponentsRegistry componentsRegistr
         return additionalAuxiliaryFiles.entrySet().stream().filter(e -> e.getValue() == Boolean.FALSE).map(Map.Entry::getKey);
     }
 
+    protected String processLinks(ComponentsRegistry componentsRegistry, Path markupPath, String content) {
+        return MermaidLinkResolver.validateAndResolveLinks(componentsRegistry.docStructure(), markupPath, content);
+    }
+
     protected void processIconPacks(ComponentsRegistry componentsRegistry, Map<String, Object> props) {
         ResourcesResolver resourcesResolver = componentsRegistry.resourceResolver();
         DocStructure docStructure = componentsRegistry.docStructure();
         if (!props.containsKey("iconpacks")) {
             return;
         }
-        if ((props.get("iconpacks") instanceof List<?>)) {
-            List<?> iconPacks = (List<?>) props.get("iconpacks");
-            iconPacks.forEach(iconPack -> {
-                        tweakIconpackUrl(resourcesResolver, docStructure, iconPack);
-                    }
+        if ((props.get("iconpacks") instanceof List<?> iconPacks)) {
+            iconPacks.forEach(iconPack -> tweakIconpackUrl(resourcesResolver, docStructure, iconPack)
             );
         }
     }

znai-diagrams/src/test/groovy/org/testingisdocumenting/znai/diagrams/mermaid/MermaidFencePluginTest.groovy

@@ -18,6 +18,8 @@ package org.testingisdocumenting.znai.diagrams.mermaid
 
 import org.testingisdocumenting.znai.extensions.include.PluginsTestUtils
 import org.testingisdocumenting.znai.extensions.PluginParamsFactory
+import org.junit.After
+import org.junit.Before
 import org.junit.Test
 
 import static org.testingisdocumenting.znai.parser.TestComponentsRegistry.TEST_COMPONENTS_REGISTRY
@@ -26,6 +28,13 @@ import static org.testingisdocumenting.webtau.Matchers.throwException
 
 class MermaidFencePluginTest {
     static PluginParamsFactory pluginParamsFactory = TEST_COMPONENTS_REGISTRY.pluginParamsFactory()
+
+    @Before
+    @After
+    void init() {
+        TEST_COMPONENTS_REGISTRY.docStructure().clear()
+    }
+
     @Test
     void "should process mermaid diagram without iconpacks parameter"() {
         def mermaidContent = '''graph TD
@@ -88,6 +97,37 @@ class MermaidFencePluginTest {
         } should throwException(IllegalArgumentException.class, "iconpack url is missing")
     }
 
+    @Test
+    void "should resolve relative links and keep external links"() {
+        TEST_COMPONENTS_REGISTRY.docStructure().addValidLink("doc/page")
+        TEST_COMPONENTS_REGISTRY.docStructure().addValidLink("ref/another#section")
+
+        def mermaidContent = '''flowchart TD
+    A[Start] --> B[Process] --> C[End]
+    click A "doc/page"
+    click B href "ref/another#section" "Go to page"
+    click C "https://example.com"'''
+
+        def elements = process(mermaidContent, Collections.emptyMap())
+
+        elements.mermaid.should == '''flowchart TD
+    A[Start] --> B[Process] --> C[End]
+    click A "/test-doc/doc/page"
+    click B href "/test-doc/ref/another#section" "Go to page"
+    click C "https://example.com"'''
+    }
+
+    @Test
+    void "should validate links and report invalid ones"() {
+        def mermaidContent = '''flowchart TD
+    A[Start] --> B[End]
+    click A "doc/page"'''
+
+        code {
+            process(mermaidContent, Collections.emptyMap())
+        } should throwException(~/no valid link.*doc\/page/)
+    }
+
     private static def process(String content, Map<String, ?>  params) {
         return PluginsTestUtils.processFenceAndGetProps(pluginParamsFactory.create("mermaid", "", params), content)
     }

znai-docs/znai/llm.txt

@@ -146,8 +146,8 @@ answer-link: znai-from-export/introduction/getting-started#command-line
 ## CLI download
 
 Download and unzip
-[znai](https://repo.maven.apache.org/maven2/org/testingisdocumenting/znai/znai-dist/1.86/znai-dist-1.86-znai.zip). Add
-it to your `PATH`.
+[znai](https://repo.maven.apache.org/maven2/org/testingisdocumenting/znai/znai-dist/1.87-SNAPSHOT/znai-dist-1.87-SNAPSHOT-znai.zip).
+Add it to your `PATH`.
 
 ## Brew
 
@@ -162,7 +162,7 @@ answer-link: znai-from-export/introduction/getting-started#maven-plugin
 <plugin>
     <groupId>org.testingisdocumenting.znai</groupId>
     <artifactId>znai-maven-plugin</artifactId>
-    <version>1.86</version>
+    <version>1.87-SNAPSHOT</version>
 </plugin>
 ```
 
@@ -5096,6 +5096,27 @@ classDiagram
     }
 ```
 
+# Visuals :: Mermaid Diagrams :: Links
+answer-link: znai-from-export/visuals/mermaid-diagrams#links
+
+Use mermaid `click` statements to add links to diagram nodes. Relative links will be resolved and validated against your
+documentation structure.
+
+```
+```mermaid
+flowchart TD
+    A[Start] --> B{Is it?}
+    B -- Yes --> C[OK]
+    B -- No ----> D[End]
+    click A "visuals/mermaid-diagrams"
+    click D href "https://mermaid-js.github.io/mermaid/#/" "Mermaid docs"
+```
+```
+
+
+Note: Relative links like `visuals/mermaid-diagrams` are validated during build time, the same way regular markdown
+links are validated.
+
 # Visuals :: Mermaid Diagrams :: Wide Mode
 answer-link: znai-from-export/visuals/mermaid-diagrams#wide-mode
 
@@ -9043,6 +9064,11 @@ export PATH=$(pwd)/dist:$PATH
 znai --version
 ```
 
+# Release Notes :: 2026 :: 1.87
+answer-link: znai-from-export/release-notes/2026#187
+
+
+
 # Release Notes :: 2026 :: 1.86
 answer-link: znai-from-export/release-notes/2026#186
 

znai-docs/znai/release-notes/1.87/add-2026-03-22-mermaid-links-intercept.md

@@ -0,0 +1 @@
+* Add: Mermaid diagrams links are automatically validated and clicking them performs fast navigation without page reloads

znai-docs/znai/release-notes/2026.md

@@ -1,3 +1,7 @@
+# 1.87
+
+:include-markdowns: 1.87
+
 # 1.86
 
 :include-markdowns: 1.86

znai-docs/znai/visuals/mermaid-diagrams.md

@@ -37,6 +37,30 @@ Use include plugin to render a Mermaid diagram from a file.
 
 :include-file: mermaid/class-diagram.mmd { autoTitle: true }
 
+# Links
+
+Use mermaid `click` statements to add links to diagram nodes. Relative links will be resolved and validated against your documentation structure.
+
+    ```mermaid
+    flowchart TD
+        A[Start] --> B{Is it?}
+        B -- Yes --> C[OK]
+        B -- No ----> D[End]
+        click A "visuals/mermaid-diagrams"
+        click D href "https://mermaid-js.github.io/mermaid/#/" "Mermaid docs"
+    ```
+
+```mermaid
+flowchart TD
+    A[Start] --> B{Is it?}
+    B -- Yes --> C[OK]
+    B -- No ----> D[End]
+    click A "introduction/getting-started"
+    click D href "https://mermaid-js.github.io/mermaid/#/" "Mermaid docs"
+```
+
+Note: Relative links like `visuals/mermaid-diagrams` are validated during build time, the same way regular markdown links are validated.
+
 # Wide Mode
 
 Use `wide: true` to use as much horizontal space as required and available.