You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2026/04/13 15:35:57 UTC
(maven-doxia-sitetools) branch feature/documentation-mermaid created (now c0aed1b)
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a change to branch feature/documentation-mermaid
in repository https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git
at c0aed1b Document Mermaid Diagram Support
This branch includes the following new commits:
new c0aed1b Document Mermaid Diagram Support
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(maven-doxia-sitetools) 01/01: Document Mermaid Diagram Support
Posted by kw...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch feature/documentation-mermaid
in repository https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git
commit c0aed1b5f8ba2fa8dc3305a1545ba3dd714ea204
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Apr 13 17:35:49 2026 +0200
Document Mermaid Diagram Support
WIP
Requires newer m-site-p
---
.../src/site/markdown/mermaid-diagrams.md | 103 +++++++++++++++++++++
doxia-site-renderer/src/site/site.xml | 6 +-
src/site/site.xml | 13 +--
3 files changed, 114 insertions(+), 8 deletions(-)
diff --git a/doxia-site-renderer/src/site/markdown/mermaid-diagrams.md b/doxia-site-renderer/src/site/markdown/mermaid-diagrams.md
new file mode 100644
index 0000000..6ef99e0
--- /dev/null
+++ b/doxia-site-renderer/src/site/markdown/mermaid-diagrams.md
@@ -0,0 +1,103 @@
+---
+title: Mermaid Diagrams
+---
+
+<!-- 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.-->
+
+<!-- MACRO{toc} -->
+
+# Mermaid Diagrams
+
+Doxia Sitetools can optionally embed the necessary Javascript to render [Mermaid](https://mermaid.ai/open-source/) diagrams client-side (supported since [2.1.0](https://github.com/apache/maven-doxia-sitetools/issues/611).
+
+# Setup
+
+In order to enable this feature one has to [add element `mermaid` to the Site Descriptor](../doxia-site-model/site.html#mermaid).
+Make sure the site descriptor references namespace 2.1.0 or newer.
+
+## Reference from external CDN
+
+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/mermaid@11.14.0/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 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-site-model/site.html#mermaid). Its format is described in [MermaidConfig](https://mermaid.ai/open-source/config/setup/mermaid/interfaces/MermaidConfig.html).
\ No newline at end of file
diff --git a/doxia-site-renderer/src/site/site.xml b/doxia-site-renderer/src/site/site.xml
index 92f941a..6e2fb68 100644
--- a/doxia-site-renderer/src/site/site.xml
+++ b/doxia-site-renderer/src/site/site.xml
@@ -22,10 +22,12 @@
-->
-<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="Site Renderer">
+ <!-- TODO: requires doxia-sitetools 2.1.0 referenced in m-site-p -->
+ <mermaid></mermaid>
<body>
<menu ref="parent"/>
diff --git a/src/site/site.xml b/src/site/site.xml
index 09c9f14..cda2062 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -21,8 +21,8 @@
*/
-->
-<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="Doxia Sitetools">
<bannerRight href="https://maven.apache.org/doxia/">
@@ -46,10 +46,11 @@
</menu>
<menu name="Documentation" inherit="bottom">
- <item name="Site Descriptor 2.x" href="doxia-site-model/site.html "/>
- <item name="Deprecated Site Descriptor 1.x" href="doxia-site-model/decoration.html "/>
- <item name="Convert to Site Descriptor 2.x" href="doxia-site-model/convert-to-sitedescriptor-2.x.html "/>
- <item name="Skin Descriptor" href="doxia-skin-model/skin.html "/>
+ <item name="Site Descriptor 2.x" href="doxia-site-model/site.html"/>
+ <item name="Deprecated Site Descriptor 1.x" href="doxia-site-model/decoration.html"/>
+ <item name="Convert to Site Descriptor 2.x" href="doxia-site-model/convert-to-sitedescriptor-2.x.html"/>
+ <item name="Skin Descriptor" href="doxia-skin-model/skin.html"/>
+ <item name="Mermaid Diagrams" href="doxia-site-renderer/mermaid-diagrams.html"/>
</menu>
<menu ref="modules"/>