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 & 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">
