This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git

commit 972327127edaec71ca15487d51e7d3665f3fa453
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 19:57:14 2026 +0000

    Add a Mermaid diagrams page for Doxia
---
 content/markdown/doxia/mermaid-diagrams.md | 99 ++++++++++++++++++++++++++++++
 content/site.xml                           |  6 +-
 2 files changed, 103 insertions(+), 2 deletions(-)

diff --git a/content/markdown/doxia/mermaid-diagrams.md 
b/content/markdown/doxia/mermaid-diagrams.md
new file mode 100644
index 00000000..0b8cefe4
--- /dev/null
+++ b/content/markdown/doxia/mermaid-diagrams.md
@@ -0,0 +1,99 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you 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.
+-->
+
+# Mermaid Diagrams
+
+Doxia Sitetools can optionally embed the necessary JavaScript to render 
[Mermaid](https://mermaid.ai/open-source/) diagrams client-side (supported 
since Doxia Sitetools 
[2.1.0](https://github.com/apache/maven-doxia-sitetools/issues/611), which 
Maven Site Plugin 3.22.0 uses).
+
+<!-- MACRO{toc|fromDepth=2} -->
+
+## Setup
+
+In order to enable this feature one has to [add element `mermaid` to the site 
descriptor](/doxia/doxia-sitetools/doxia-site-model/site.html#mermaid).
+Make sure the site descriptor references namespace 2.1.0 or newer.
+
+### Reference from external server
+
+Although an empty element is enough, usually one wants to reference a specific 
Mermaid JS version from an external URL instead of embedding that into each 
site by yourself and reference it from there.
+
+```xml
+<site xmlns="http://maven.apache.org/SITE/2.1.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; ...>
+  ...
+  <mermaid>
+    <externalJsUrl 
integrity="sha384-1CMXl090wj8Dd6YfnzSQUOgWbE6suWCaenYG7pox5AX7apTpY3PmJMeS2oPql4Gk">https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js</externalJsUrl>
+  </mermaid>
+  
+
+</site>
+```
+
+It is strongly recommended to also set the [`integrity` 
attribute](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity)
 in order to ensure the external source delivers exactly the script you expect. 
+One can calculate the integrity for a specific Mermaid version with the online 
tool provided at <https://srihash.org/>.
+The default external source for Mermaid is 
[jsDelivr](https://www.jsdelivr.com/package/npm/mermaid).
+
+Using the [ECMAScript Module (ESM)](https://tc39.es/ecma262/#sec-modules) URL 
is not yet supported.
+
+### Embed in generated site
+
+To just embed the hardcoded version of Mermaid into your generated site 
([11.13.0 for Doxia Site Tools 
2.1.0](https://github.com/apache/maven-doxia-sitetools/tree/master/doxia-site-renderer/src/main/resources/js))
 just leave out the `externalJsUrl` child element.
+
+```xml
+<site xmlns="http://maven.apache.org/SITE/2.1.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; ...>
+  ...
+  <mermaid>
+   ...
+  </mermaid>
+</site>
+```
+
+That way the JS is automatically copied to your site during the rendering and 
referenced accordingly in your HTML.
+
+*This should only be necessary if your [site's Content Security Policy 
(CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) prevents 
including JS from external sources (like for example the global [Apache 
CSP](https://infra.apache.org/tools/csp.html))*.
+
+
+## Usage
+
+In order to write Mermaid diagrams, one can just embed them in Doxia sources. 
For example to embed something in Markdown (md) write
+
+
+````markdown
+This is my diagram:
+
+```mermaid
+  graph TD;
+      A-->B;
+      A-->C;
+      B-->D;
+      C-->D;
+```
+````
+
+This renders as
+
+```mermaid
+  graph TD;
+      A-->B;
+      A-->C;
+      B-->D;
+      C-->D;
+```
+
+## Configuration
+
+One can further adjust the Mermaid configuration used for rendering with the 
[`config` element in the site 
descriptor](/doxia/doxia-sitetools/doxia-site-model/site.html#mermaid). Its 
format is described in 
[MermaidConfig](https://mermaid.ai/open-source/config/setup/mermaid/interfaces/MermaidConfig.html).
diff --git a/content/site.xml b/content/site.xml
index 5d43daa9..3f49078e 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -20,10 +20,11 @@ under the License.
 -->
 
 
-<site xmlns="http://maven.apache.org/SITE/2.0.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
-      xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 
https://maven.apache.org/xsd/site-2.0.0.xsd";
+<site xmlns="http://maven.apache.org/SITE/2.1.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+      xsi:schemaLocation="http://maven.apache.org/SITE/2.1.0 
https://maven.apache.org/xsd/site-2.1.0.xsd";
       name="Maven">
   <version position="none"/>
+  <mermaid/>
 
   <body>
     <links>
@@ -70,6 +71,7 @@ under the License.
         <item name="Migrating APT to Markdown" 
href="/doxia/migrating-apt-to-markdown.html"/>
         <item name="Doxia Modules Guide" href="/doxia/modules/index.html"/>
         <item name="Doxia Macros Guide" href="/doxia/macros/index.html"/>
+        <item name="Mermaid Diagrams" href="/doxia/mermaid-diagrams.html"/>
         <item name="Issues &amp; Gotchas" href="/doxia/issues/index.html"/>
         <item name="External Resources" href="/doxia/resources.html"/>
         <item name="Developer Docs" href="/doxia/developers/index.html" 
collapse="true">

Reply via email to