From b96eaed6f4b2054f669cc4c3538d09f92e42f8c1 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Tue, 27 Feb 2024 12:54:56 +0530 Subject: [PATCH 01/20] Fix store link --- docs/ecosystem/integrations-community.md | 2 +- packages/mermaid/src/docs/ecosystem/integrations-community.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ecosystem/integrations-community.md b/docs/ecosystem/integrations-community.md index 0d3676431b..d2a1c56b66 100644 --- a/docs/ecosystem/integrations-community.md +++ b/docs/ecosystem/integrations-community.md @@ -222,7 +222,7 @@ Communication tools and platforms | GitHub + Mermaid | - | [🦊🔗](https://addons.mozilla.org/firefox/addon/github-mermaid/) | - | - | [🐙🔗](https://github.com/BackMarket/github-mermaid-extension) | | Asciidoctor Live Preview | [🎡🔗](https://chromewebstore.google.com/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia) | - | - | [🌀🔗](https://microsoftedge.microsoft.com/addons/detail/asciidoctorjs-live-previ/pefkelkanablhjdekgdahplkccnbdggd?hl=en-US) | - | | Diagram Tab | - | - | - | - | [🐙🔗](https://github.com/khafast/diagramtab) | -| Markdown Diagrams | [🎡🔗](https://chromewebstore.google.com/detail/markdown-diagrams/pmoglnmodacnbbofbgcagndelmgaclel/) | [🦊🔗](https://addons.mozilla.org/en-US/firefox/addon/markdown-diagrams/) | [🔴🔗](https://addons.opera.com/en/extensions/details/markdown-diagrams/) | [🌀🔗](https://microsoftedge.microsoft.com/addons/detail/markdown-diagrams/hceenoomhhdkjjijnmlclkpenkapfihe) | [🐙🔗](https://github.com/marcozaccari/markdown-diagrams-browser-extension/tree/master/doc/examples) | +| Markdown Diagrams | [🎡🔗](https://chromewebstore.google.com/detail/markdown-diagrams/pmoglnmodacnbbofbgcagndelmgaclel) | [🦊🔗](https://addons.mozilla.org/en-US/firefox/addon/markdown-diagrams/) | [🔴🔗](https://addons.opera.com/en/extensions/details/markdown-diagrams/) | [🌀🔗](https://microsoftedge.microsoft.com/addons/detail/markdown-diagrams/hceenoomhhdkjjijnmlclkpenkapfihe) | [🐙🔗](https://github.com/marcozaccari/markdown-diagrams-browser-extension/tree/master/doc/examples) | | Markdown Viewer | - | [🦊🔗](https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer-chrome/) | - | - | [🐙🔗](https://github.com/simov/markdown-viewer) | | Extensions for Mermaid | - | - | [🔴🔗](https://addons.opera.com/en/extensions/details/extensions-for-mermaid/) | - | [🐙🔗](https://github.com/Stefan-S/mermaid-extension) | | Chrome Diagrammer | [🎡🔗](https://chromewebstore.google.com/detail/chrome-diagrammer/bkpbgjmkomfoakfklcjeoegkklgjnnpk) | - | - | - | - | diff --git a/packages/mermaid/src/docs/ecosystem/integrations-community.md b/packages/mermaid/src/docs/ecosystem/integrations-community.md index 93a3a9df49..454e8170a1 100644 --- a/packages/mermaid/src/docs/ecosystem/integrations-community.md +++ b/packages/mermaid/src/docs/ecosystem/integrations-community.md @@ -217,7 +217,7 @@ Communication tools and platforms | GitHub + Mermaid | - | [🦊🔗](https://addons.mozilla.org/firefox/addon/github-mermaid/) | - | - | [🐙🔗](https://github.com/BackMarket/github-mermaid-extension) | | Asciidoctor Live Preview | [🎡🔗](https://chromewebstore.google.com/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia) | - | - | [🌀🔗](https://microsoftedge.microsoft.com/addons/detail/asciidoctorjs-live-previ/pefkelkanablhjdekgdahplkccnbdggd?hl=en-US) | - | | Diagram Tab | - | - | - | - | [🐙🔗](https://github.com/khafast/diagramtab) | -| Markdown Diagrams | [🎡🔗](https://chromewebstore.google.com/detail/markdown-diagrams/pmoglnmodacnbbofbgcagndelmgaclel/) | [🦊🔗](https://addons.mozilla.org/en-US/firefox/addon/markdown-diagrams/) | [🔴🔗](https://addons.opera.com/en/extensions/details/markdown-diagrams/) | [🌀🔗](https://microsoftedge.microsoft.com/addons/detail/markdown-diagrams/hceenoomhhdkjjijnmlclkpenkapfihe) | [🐙🔗](https://github.com/marcozaccari/markdown-diagrams-browser-extension/tree/master/doc/examples) | +| Markdown Diagrams | [🎡🔗](https://chromewebstore.google.com/detail/markdown-diagrams/pmoglnmodacnbbofbgcagndelmgaclel) | [🦊🔗](https://addons.mozilla.org/en-US/firefox/addon/markdown-diagrams/) | [🔴🔗](https://addons.opera.com/en/extensions/details/markdown-diagrams/) | [🌀🔗](https://microsoftedge.microsoft.com/addons/detail/markdown-diagrams/hceenoomhhdkjjijnmlclkpenkapfihe) | [🐙🔗](https://github.com/marcozaccari/markdown-diagrams-browser-extension/tree/master/doc/examples) | | Markdown Viewer | - | [🦊🔗](https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer-chrome/) | - | - | [🐙🔗](https://github.com/simov/markdown-viewer) | | Extensions for Mermaid | - | - | [🔴🔗](https://addons.opera.com/en/extensions/details/extensions-for-mermaid/) | - | [🐙🔗](https://github.com/Stefan-S/mermaid-extension) | | Chrome Diagrammer | [🎡🔗](https://chromewebstore.google.com/detail/chrome-diagrammer/bkpbgjmkomfoakfklcjeoegkklgjnnpk) | - | - | - | - | From 31686802b3522d68c25171480374fd12e50ecde7 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Tue, 27 Feb 2024 13:21:49 +0530 Subject: [PATCH 02/20] Bump version --- .github/lychee.toml | 5 ++++- docs/config/math.md | 2 +- packages/mermaid/package.json | 2 +- packages/mermaid/src/docs/config/math.md | 2 +- 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/lychee.toml b/.github/lychee.toml index 9c9d0558c2..c5a2f0e452 100644 --- a/.github/lychee.toml +++ b/.github/lychee.toml @@ -38,7 +38,10 @@ exclude = [ "https://discord.gg", # BundlePhobia has frequent downtime -"https://bundlephobia.com" +"https://bundlephobia.com", + +# Chrome webstore migration issue. Temporary +"https://chromewebstore.google.com" ] # Exclude all private IPs from checking. diff --git a/docs/config/math.md b/docs/config/math.md index 049c557308..fcafdad819 100644 --- a/docs/config/math.md +++ b/docs/config/math.md @@ -4,7 +4,7 @@ > > ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/math.md](../../packages/mermaid/src/docs/config/math.md). -# Math Configuration (v\+) +# Math Configuration (v10.9.0+) Mermaid supports rendering mathematical expressions through the [KaTeX](https://katex.org/) typesetter. diff --git a/packages/mermaid/package.json b/packages/mermaid/package.json index 3626671ca5..edb069d98e 100644 --- a/packages/mermaid/package.json +++ b/packages/mermaid/package.json @@ -1,6 +1,6 @@ { "name": "mermaid", - "version": "10.8.0", + "version": "10.9.0", "description": "Markdown-ish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs.", "type": "module", "module": "./dist/mermaid.core.mjs", diff --git a/packages/mermaid/src/docs/config/math.md b/packages/mermaid/src/docs/config/math.md index d72320040e..67d82cb205 100644 --- a/packages/mermaid/src/docs/config/math.md +++ b/packages/mermaid/src/docs/config/math.md @@ -1,4 +1,4 @@ -# Math Configuration (v+) +# Math Configuration (v10.9.0+) Mermaid supports rendering mathematical expressions through the [KaTeX](https://katex.org/) typesetter. From 60a484f1e4b36e65fca876f229e3f0c5d4c8b25e Mon Sep 17 00:00:00 2001 From: Aakansha Doshi Date: Tue, 27 Feb 2024 18:20:03 +0530 Subject: [PATCH 03/20] feat: add name attribute to line --- packages/mermaid/src/diagrams/sequence/svgDraw.js | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/mermaid/src/diagrams/sequence/svgDraw.js b/packages/mermaid/src/diagrams/sequence/svgDraw.js index 17842b092d..160477637e 100644 --- a/packages/mermaid/src/diagrams/sequence/svgDraw.js +++ b/packages/mermaid/src/diagrams/sequence/svgDraw.js @@ -343,10 +343,10 @@ const drawActorTypeParticipant = async function (elem, actor, conf, isFooter) { .attr('y1', centerY) .attr('x2', center) .attr('y2', 2000) - .attr('class', 'actor-line') - .attr('class', '200') + .attr('class', 'actor-line 200') .attr('stroke-width', '0.5px') - .attr('stroke', '#999'); + .attr('stroke', '#999') + .attr('name', actor.name); g = boxplusLineGroup.append('g'); actor.actorCnt = actorCnt; @@ -425,10 +425,10 @@ const drawActorTypeActor = async function (elem, actor, conf, isFooter) { .attr('y1', centerY) .attr('x2', center) .attr('y2', 2000) - .attr('class', 'actor-line') - .attr('class', '200') + .attr('class', 'actor-line 200') .attr('stroke-width', '0.5px') - .attr('stroke', '#999'); + .attr('stroke', '#999') + .attr('name', actor.name); actor.actorCnt = actorCnt; } From df026c795d971adc14058826b92cabacabcae4fc Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Wed, 28 Feb 2024 23:04:19 +0530 Subject: [PATCH 04/20] Bump @mermaid-js/mermaid-zenuml version to 0.2.0 --- packages/mermaid-zenuml/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mermaid-zenuml/package.json b/packages/mermaid-zenuml/package.json index cbe8dd9f8c..160de7d4d6 100644 --- a/packages/mermaid-zenuml/package.json +++ b/packages/mermaid-zenuml/package.json @@ -1,6 +1,6 @@ { "name": "@mermaid-js/mermaid-zenuml", - "version": "0.1.2", + "version": "0.2.0", "description": "MermaidJS plugin for ZenUML integration", "module": "dist/mermaid-zenuml.core.mjs", "types": "dist/detector.d.ts", From f9c359e70c13ed267187e0c35988385f7d75bd49 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Thu, 29 Feb 2024 08:38:03 +0530 Subject: [PATCH 05/20] v10.9.0-rc.2 --- packages/mermaid/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mermaid/package.json b/packages/mermaid/package.json index edb069d98e..ecc01f8e2c 100644 --- a/packages/mermaid/package.json +++ b/packages/mermaid/package.json @@ -1,6 +1,6 @@ { "name": "mermaid", - "version": "10.9.0", + "version": "10.9.0-rc.2", "description": "Markdown-ish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs.", "type": "module", "module": "./dist/mermaid.core.mjs", From 2caeb9db47883cfabbeef7560fa1b5256db25680 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Thu, 29 Feb 2024 08:38:47 +0530 Subject: [PATCH 06/20] zenUML 0.2.0-rc.2 --- packages/mermaid-zenuml/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mermaid-zenuml/package.json b/packages/mermaid-zenuml/package.json index 160de7d4d6..48560e09fe 100644 --- a/packages/mermaid-zenuml/package.json +++ b/packages/mermaid-zenuml/package.json @@ -1,6 +1,6 @@ { "name": "@mermaid-js/mermaid-zenuml", - "version": "0.2.0", + "version": "0.2.0-rc.2", "description": "MermaidJS plugin for ZenUML integration", "module": "dist/mermaid-zenuml.core.mjs", "types": "dist/detector.d.ts", From 38fcc2847bbe0eb1f4feb2c420fd3dde4ac71d23 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Thu, 29 Feb 2024 08:41:15 +0530 Subject: [PATCH 07/20] Add release version in docs --- docs/syntax/gantt.md | 2 +- packages/mermaid/src/docs/syntax/gantt.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/syntax/gantt.md b/docs/syntax/gantt.md index d1a13c6fa5..eeabfd3705 100644 --- a/docs/syntax/gantt.md +++ b/docs/syntax/gantt.md @@ -143,7 +143,7 @@ After processing the tags, the remaining metadata items are interpreted as follo | `until ` | End date of preceding task | Start date of previously specified task `otherTaskID` | n/a | > **Note** -> Support for keyword `until` was added in (v\+). This can be used to define a task which is running until some other specific task or milestone starts. +> Support for keyword `until` was added in (v10.9.0+). This can be used to define a task which is running until some other specific task or milestone starts. For simplicity, the table does not show the use of multiple tasks listed with the `after` keyword. Here is an example of how to use it and how it's interpreted: diff --git a/packages/mermaid/src/docs/syntax/gantt.md b/packages/mermaid/src/docs/syntax/gantt.md index a1139d3789..4fd896d3c1 100644 --- a/packages/mermaid/src/docs/syntax/gantt.md +++ b/packages/mermaid/src/docs/syntax/gantt.md @@ -92,7 +92,7 @@ After processing the tags, the remaining metadata items are interpreted as follo | `until ` | End date of preceding task | Start date of previously specified task `otherTaskID` | n/a | ```note -Support for keyword `until` was added in (v+). This can be used to define a task which is running until some other specific task or milestone starts. +Support for keyword `until` was added in (v10.9.0+). This can be used to define a task which is running until some other specific task or milestone starts. ``` For simplicity, the table does not show the use of multiple tasks listed with the `after` keyword. Here is an example of how to use it and how it's interpreted: From aef29affa374cdd9093a9568c634bcfa2002e94c Mon Sep 17 00:00:00 2001 From: Kamal Kishor Joshi Date: Sat, 2 Mar 2024 23:19:11 +0530 Subject: [PATCH 08/20] Add LLM integration section in productivity tools and add HueHive Since mermaid diagram creation is a perfact usecase for LLMs adding a section for LLM integration make sense. HueHive is a tool to create and visualize mermaid diagrams with the help of ChatGPT. Please let me know if it is fine to add this or this should be added in some other section. Thanks. PS: I am creater of HueHive diagrams tool. --- packages/mermaid/src/docs/ecosystem/integrations-community.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/mermaid/src/docs/ecosystem/integrations-community.md b/packages/mermaid/src/docs/ecosystem/integrations-community.md index 24812bb3d6..03e322016b 100644 --- a/packages/mermaid/src/docs/ecosystem/integrations-community.md +++ b/packages/mermaid/src/docs/ecosystem/integrations-community.md @@ -65,6 +65,8 @@ To add an integration to this list, see the [Integrations - create page](./integ - [Markdown for mermaid plugin](https://github.com/jamieh-mongolian/markdown-for-mermaid-plugin) - [redmine-mermaid](https://github.com/styz/redmine_mermaid) - Visual Studio Code [Polyglot Interactive Notebooks](https://github.com/dotnet/interactive#net-interactive) +- LLM integrations + - [HueHive - Create mermaid diagrams with text](https://huehive.co/tools/diagrams) ### CRM/ERP From be6b3176f4b4955d7e1e8157d104e016162580d1 Mon Sep 17 00:00:00 2001 From: Kamal Joshi Date: Sun, 3 Mar 2024 08:51:55 +0530 Subject: [PATCH 09/20] fix linting issues --- packages/mermaid/src/docs/ecosystem/integrations-community.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/mermaid/src/docs/ecosystem/integrations-community.md b/packages/mermaid/src/docs/ecosystem/integrations-community.md index 03e322016b..7491a2d02e 100644 --- a/packages/mermaid/src/docs/ecosystem/integrations-community.md +++ b/packages/mermaid/src/docs/ecosystem/integrations-community.md @@ -66,7 +66,7 @@ To add an integration to this list, see the [Integrations - create page](./integ - [redmine-mermaid](https://github.com/styz/redmine_mermaid) - Visual Studio Code [Polyglot Interactive Notebooks](https://github.com/dotnet/interactive#net-interactive) - LLM integrations - - [HueHive - Create mermaid diagrams with text](https://huehive.co/tools/diagrams) + - [HueHive - Create mermaid diagrams with text](https://huehive.co/tools/diagrams) ### CRM/ERP @@ -249,4 +249,4 @@ Communication tools and platforms - [mermaid-isomorphic](https://github.com/remcohaszing/mermaid-isomorphic) - [mermaid-server: Generate diagrams using a HTTP request](https://github.com/TomWright/mermaid-server) - + From cbe44a6cfff0734a853443c2755520d0dda72b71 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Tue, 5 Mar 2024 22:47:16 +0530 Subject: [PATCH 10/20] v10.9.0 --- packages/mermaid/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mermaid/package.json b/packages/mermaid/package.json index ecc01f8e2c..edb069d98e 100644 --- a/packages/mermaid/package.json +++ b/packages/mermaid/package.json @@ -1,6 +1,6 @@ { "name": "mermaid", - "version": "10.9.0-rc.2", + "version": "10.9.0", "description": "Markdown-ish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs.", "type": "module", "module": "./dist/mermaid.core.mjs", From da33867ad798872d9f8406532263ff5e569f1185 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Tue, 5 Mar 2024 22:52:07 +0530 Subject: [PATCH 11/20] Draft release --- .github/workflows/release-draft.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release-draft.yml b/.github/workflows/release-draft.yml index db1dd1f485..8e9c0da99e 100644 --- a/.github/workflows/release-draft.yml +++ b/.github/workflows/release-draft.yml @@ -12,7 +12,7 @@ jobs: draft-release: runs-on: ubuntu-latest permissions: - contents: write # write permission is required to create a github release + contents: write # write permission is required to create a GitHub release pull-requests: read # required to read PR titles/labels steps: - name: Draft Release From dbeb0a4720f6d185c3fd4ee5c89955fc0a15480f Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Tue, 5 Mar 2024 22:56:09 +0530 Subject: [PATCH 12/20] @mermaid-js/mermaid-zenuml v0.2.0 --- packages/mermaid-zenuml/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mermaid-zenuml/package.json b/packages/mermaid-zenuml/package.json index 48560e09fe..160de7d4d6 100644 --- a/packages/mermaid-zenuml/package.json +++ b/packages/mermaid-zenuml/package.json @@ -1,6 +1,6 @@ { "name": "@mermaid-js/mermaid-zenuml", - "version": "0.2.0-rc.2", + "version": "0.2.0", "description": "MermaidJS plugin for ZenUML integration", "module": "dist/mermaid-zenuml.core.mjs", "types": "dist/detector.d.ts", From 099a239207105a382a50ec459e43cca849b1e438 Mon Sep 17 00:00:00 2001 From: Aakansha Doshi Date: Wed, 6 Mar 2024 17:13:33 +0530 Subject: [PATCH 13/20] revert styling changes --- docs/config/theming.md | 2 +- packages/mermaid/src/docs/config/theming.md | 2 +- packages/mermaid/src/themes/theme-base.js | 2 +- packages/mermaid/src/themes/theme-dark.js | 2 +- packages/mermaid/src/themes/theme-default.js | 2 +- packages/mermaid/src/themes/theme-forest.js | 2 +- packages/mermaid/src/themes/theme-neutral.js | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/config/theming.md b/docs/config/theming.md index f8614b44b1..5abccc7e4a 100644 --- a/docs/config/theming.md +++ b/docs/config/theming.md @@ -250,7 +250,7 @@ The theming engine will only recognize hex colors and not color names. So, the v | actorBkg | mainBkg | Actor Background Color | | actorBorder | primaryBorderColor | Actor Border Color | | actorTextColor | primaryTextColor | Actor Text Color | -| actorLineColor | grey | Actor Line Color | +| actorLineColor | actorBorder | Actor Line Color | | signalColor | textColor | Signal Color | | signalTextColor | textColor | Signal Text Color | | labelBoxBkgColor | actorBkg | Label Box Background Color | diff --git a/packages/mermaid/src/docs/config/theming.md b/packages/mermaid/src/docs/config/theming.md index 590301d70d..3863202b42 100644 --- a/packages/mermaid/src/docs/config/theming.md +++ b/packages/mermaid/src/docs/config/theming.md @@ -172,7 +172,7 @@ The theming engine will only recognize hex colors and not color names. So, the v | actorBkg | mainBkg | Actor Background Color | | actorBorder | primaryBorderColor | Actor Border Color | | actorTextColor | primaryTextColor | Actor Text Color | -| actorLineColor | grey | Actor Line Color | +| actorLineColor | actorBorder | Actor Line Color | | signalColor | textColor | Signal Color | | signalTextColor | textColor | Signal Text Color | | labelBoxBkgColor | actorBkg | Label Box Background Color | diff --git a/packages/mermaid/src/themes/theme-base.js b/packages/mermaid/src/themes/theme-base.js index d1a6eae2ab..dde3b9ecff 100644 --- a/packages/mermaid/src/themes/theme-base.js +++ b/packages/mermaid/src/themes/theme-base.js @@ -70,7 +70,7 @@ class Theme { this.actorBorder = this.actorBorder || this.primaryBorderColor; this.actorBkg = this.actorBkg || this.mainBkg; this.actorTextColor = this.actorTextColor || this.primaryTextColor; - this.actorLineColor = this.actorLineColor || 'grey'; + this.actorLineColor = this.actorLineColor || this.actorBorder; this.labelBoxBkgColor = this.labelBoxBkgColor || this.actorBkg; this.signalColor = this.signalColor || this.textColor; this.signalTextColor = this.signalTextColor || this.textColor; diff --git a/packages/mermaid/src/themes/theme-dark.js b/packages/mermaid/src/themes/theme-dark.js index c566251090..ae264e9e93 100644 --- a/packages/mermaid/src/themes/theme-dark.js +++ b/packages/mermaid/src/themes/theme-dark.js @@ -109,7 +109,7 @@ class Theme { this.actorBorder = this.border1; this.actorBkg = this.mainBkg; this.actorTextColor = this.mainContrastColor; - this.actorLineColor = this.mainContrastColor; + this.actorLineColor = this.actorBorder; this.signalColor = this.mainContrastColor; this.signalTextColor = this.mainContrastColor; this.labelBoxBkgColor = this.actorBkg; diff --git a/packages/mermaid/src/themes/theme-default.js b/packages/mermaid/src/themes/theme-default.js index 6aa18fcc78..c149b43f34 100644 --- a/packages/mermaid/src/themes/theme-default.js +++ b/packages/mermaid/src/themes/theme-default.js @@ -53,7 +53,7 @@ class Theme { this.actorBorder = 'calculated'; this.actorBkg = 'calculated'; this.actorTextColor = 'black'; - this.actorLineColor = 'grey'; + this.actorLineColor = 'calculated'; this.signalColor = 'calculated'; this.signalTextColor = 'calculated'; this.labelBoxBkgColor = 'calculated'; diff --git a/packages/mermaid/src/themes/theme-forest.js b/packages/mermaid/src/themes/theme-forest.js index 0270f51ff9..8ebe78ec89 100644 --- a/packages/mermaid/src/themes/theme-forest.js +++ b/packages/mermaid/src/themes/theme-forest.js @@ -46,7 +46,7 @@ class Theme { this.actorBorder = 'calculated'; this.actorBkg = 'calculated'; this.actorTextColor = 'black'; - this.actorLineColor = 'grey'; + this.actorLineColor = 'calculated'; this.signalColor = '#333'; this.signalTextColor = '#333'; this.labelBoxBkgColor = 'calculated'; diff --git a/packages/mermaid/src/themes/theme-neutral.js b/packages/mermaid/src/themes/theme-neutral.js index 446a9189d4..032ed43c6a 100644 --- a/packages/mermaid/src/themes/theme-neutral.js +++ b/packages/mermaid/src/themes/theme-neutral.js @@ -58,7 +58,7 @@ class Theme { this.actorBorder = 'calculated'; this.actorBkg = 'calculated'; this.actorTextColor = 'calculated'; - this.actorLineColor = 'calculated'; + this.actorLineColor = this.actorBorder; this.signalColor = 'calculated'; this.signalTextColor = 'calculated'; this.labelBoxBkgColor = 'calculated'; From b156c1ab255fa9ff7b64fd6066f8c1291d5016a5 Mon Sep 17 00:00:00 2001 From: Aakansha Doshi Date: Wed, 6 Mar 2024 19:14:56 +0530 Subject: [PATCH 14/20] assign actorLineColor --- packages/mermaid/src/themes/theme-default.js | 1 + packages/mermaid/src/themes/theme-forest.js | 1 + 2 files changed, 2 insertions(+) diff --git a/packages/mermaid/src/themes/theme-default.js b/packages/mermaid/src/themes/theme-default.js index c149b43f34..d95ccf59e0 100644 --- a/packages/mermaid/src/themes/theme-default.js +++ b/packages/mermaid/src/themes/theme-default.js @@ -187,6 +187,7 @@ class Theme { this.loopTextColor = this.actorTextColor; this.noteBorderColor = this.border2; this.noteTextColor = this.actorTextColor; + this.actorLineColor = this.actorBorder; /* Gantt chart variables */ diff --git a/packages/mermaid/src/themes/theme-forest.js b/packages/mermaid/src/themes/theme-forest.js index 077e07f9ea..4bb7d24413 100644 --- a/packages/mermaid/src/themes/theme-forest.js +++ b/packages/mermaid/src/themes/theme-forest.js @@ -101,6 +101,7 @@ class Theme { this.loopTextColor = this.actorTextColor; this.noteBorderColor = this.border2; this.noteTextColor = this.actorTextColor; + this.actorLineColor = this.actorBorder; /* Each color-set will have a background, a foreground and a border color */ this.cScale0 = this.cScale0 || this.primaryColor; From 12bbbcaff034451f2d470a034dc939f5daf10866 Mon Sep 17 00:00:00 2001 From: Aakansha Doshi Date: Wed, 6 Mar 2024 19:20:56 +0530 Subject: [PATCH 15/20] Empty-Commit From 9fa681f5a809e28567679bb81970e05c2f131f41 Mon Sep 17 00:00:00 2001 From: Kamal Joshi Date: Thu, 7 Mar 2024 13:23:43 +0530 Subject: [PATCH 16/20] build docs --- docs/ecosystem/integrations-community.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/ecosystem/integrations-community.md b/docs/ecosystem/integrations-community.md index 2dc815ee26..5947a92694 100644 --- a/docs/ecosystem/integrations-community.md +++ b/docs/ecosystem/integrations-community.md @@ -70,6 +70,8 @@ To add an integration to this list, see the [Integrations - create page](./integ - [Markdown for mermaid plugin](https://github.com/jamieh-mongolian/markdown-for-mermaid-plugin) - [redmine-mermaid](https://github.com/styz/redmine_mermaid) - Visual Studio Code [Polyglot Interactive Notebooks](https://github.com/dotnet/interactive#net-interactive) +- LLM integrations + - [HueHive - Create mermaid diagrams with text](https://huehive.co/tools/diagrams) ### CRM/ERP @@ -252,4 +254,4 @@ Communication tools and platforms - [mermaid-isomorphic](https://github.com/remcohaszing/mermaid-isomorphic) - [mermaid-server: Generate diagrams using a HTTP request](https://github.com/TomWright/mermaid-server) - + From 5f84344c3c6866ab1cd9508e2359632982aa3bd6 Mon Sep 17 00:00:00 2001 From: Kamal Joshi Date: Thu, 7 Mar 2024 20:20:58 +0530 Subject: [PATCH 17/20] make LLM integrations a new headline --- docs/ecosystem/integrations-community.md | 8 ++++++-- .../mermaid/src/docs/ecosystem/integrations-community.md | 8 ++++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/ecosystem/integrations-community.md b/docs/ecosystem/integrations-community.md index 5947a92694..d3633bca37 100644 --- a/docs/ecosystem/integrations-community.md +++ b/docs/ecosystem/integrations-community.md @@ -70,8 +70,12 @@ To add an integration to this list, see the [Integrations - create page](./integ - [Markdown for mermaid plugin](https://github.com/jamieh-mongolian/markdown-for-mermaid-plugin) - [redmine-mermaid](https://github.com/styz/redmine_mermaid) - Visual Studio Code [Polyglot Interactive Notebooks](https://github.com/dotnet/interactive#net-interactive) -- LLM integrations - - [HueHive - Create mermaid diagrams with text](https://huehive.co/tools/diagrams) + +### LLM integrations + +LLM integrations to create mermaid diagrams using AI from text descriptions. + +- [HueHive - Create mermaid diagrams with text](https://huehive.co/tools/diagrams) ### CRM/ERP diff --git a/packages/mermaid/src/docs/ecosystem/integrations-community.md b/packages/mermaid/src/docs/ecosystem/integrations-community.md index c397aae9c2..4dbe49f5d7 100644 --- a/packages/mermaid/src/docs/ecosystem/integrations-community.md +++ b/packages/mermaid/src/docs/ecosystem/integrations-community.md @@ -65,8 +65,12 @@ To add an integration to this list, see the [Integrations - create page](./integ - [Markdown for mermaid plugin](https://github.com/jamieh-mongolian/markdown-for-mermaid-plugin) - [redmine-mermaid](https://github.com/styz/redmine_mermaid) - Visual Studio Code [Polyglot Interactive Notebooks](https://github.com/dotnet/interactive#net-interactive) -- LLM integrations - - [HueHive - Create mermaid diagrams with text](https://huehive.co/tools/diagrams) + +### LLM integrations + +LLM integrations to create mermaid diagrams using AI from text descriptions. + +- [HueHive - Create mermaid diagrams with text](https://huehive.co/tools/diagrams) ### CRM/ERP From 233944bf2469859d3164dbdc6d0ede5baee95050 Mon Sep 17 00:00:00 2001 From: Aakansha Doshi Date: Fri, 8 Mar 2024 11:20:25 +0530 Subject: [PATCH 18/20] use actorBorderColor for actorLineColor in theme-neutral --- packages/mermaid/src/themes/theme-neutral.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mermaid/src/themes/theme-neutral.js b/packages/mermaid/src/themes/theme-neutral.js index 032ed43c6a..4134a985b9 100644 --- a/packages/mermaid/src/themes/theme-neutral.js +++ b/packages/mermaid/src/themes/theme-neutral.js @@ -113,7 +113,7 @@ class Theme { this.actorBorder = lighten(this.border1, 23); this.actorBkg = this.mainBkg; this.actorTextColor = this.text; - this.actorLineColor = this.lineColor; + this.actorLineColor = this.actorBorder; this.signalColor = this.text; this.signalTextColor = this.text; this.labelBoxBkgColor = this.actorBkg; From 8f457815e9089ac945f26394ed53c06943493849 Mon Sep 17 00:00:00 2001 From: Jakub Mikulas Date: Fri, 8 Mar 2024 10:13:52 +0100 Subject: [PATCH 19/20] docs(integrations): update link to Mermaid app for Slack Signed-off-by: Jakub Mikulas --- docs/ecosystem/integrations-community.md | 2 +- packages/mermaid/src/docs/ecosystem/integrations-community.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ecosystem/integrations-community.md b/docs/ecosystem/integrations-community.md index 2dc815ee26..de57468231 100644 --- a/docs/ecosystem/integrations-community.md +++ b/docs/ecosystem/integrations-community.md @@ -118,7 +118,7 @@ Communication tools and platforms - [phpBB](https://phpbb.com) - [phpbb-ext-mermaid](https://github.com/AlfredoRamos/phpbb-ext-mermaid) - [Slack](https://slack.com) - - [Mermaid Preview](https://github.com/JackuB/mermaid-for-slack) + - [Mermaid Preview](https://mermaid-preview.com) ### Wikis diff --git a/packages/mermaid/src/docs/ecosystem/integrations-community.md b/packages/mermaid/src/docs/ecosystem/integrations-community.md index e2d6866120..861493aa37 100644 --- a/packages/mermaid/src/docs/ecosystem/integrations-community.md +++ b/packages/mermaid/src/docs/ecosystem/integrations-community.md @@ -113,7 +113,7 @@ Communication tools and platforms - [phpBB](https://phpbb.com) - [phpbb-ext-mermaid](https://github.com/AlfredoRamos/phpbb-ext-mermaid) - [Slack](https://slack.com) - - [Mermaid Preview](https://github.com/JackuB/mermaid-for-slack) + - [Mermaid Preview](https://mermaid-preview.com) ### Wikis From c0497d3413246008a36fd57c6471b458809f005c Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Fri, 8 Mar 2024 23:09:16 +0530 Subject: [PATCH 20/20] Update new diagram doc to reflect focus on Langium Mark JISON as deprecated. --- docs/community/new-diagram-jison.md | 222 ++++++++++++++++++ docs/community/new-diagram.md | 122 +--------- .../src/docs/community/new-diagram-jison.md | 220 +++++++++++++++++ .../mermaid/src/docs/community/new-diagram.md | 122 +--------- 4 files changed, 458 insertions(+), 228 deletions(-) create mode 100644 docs/community/new-diagram-jison.md create mode 100644 packages/mermaid/src/docs/community/new-diagram-jison.md diff --git a/docs/community/new-diagram-jison.md b/docs/community/new-diagram-jison.md new file mode 100644 index 0000000000..40164fe8c8 --- /dev/null +++ b/docs/community/new-diagram-jison.md @@ -0,0 +1,222 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/new-diagram-jison.md](../../packages/mermaid/src/docs/community/new-diagram-jison.md). + +# Adding a New Diagram/Chart (Deprecated) 📊 + +> **Warning** +> JISON grammars are deprecated in mermaid. Please use Langium instead. See [New Diagram](./new-diagram.md) for more information. +> +> **New diagrams with JISON grammars will not be accepted.** + +### Step 1: Grammar & Parsing + +#### Grammar + +This would be to define a JISON grammar for the new diagram type. That should start with a way to identify that the text in the mermaid tag is a diagram of that type. Create a new folder under diagrams for your new diagram type and a parser folder in it. This leads us to step 2. + +For instance: + +- the flowchart starts with the keyword _graph_ +- the sequence diagram starts with the keyword _sequenceDiagram_ + +#### Store data found during parsing + +There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call an object provided to the parser by the user of the parser. This object can be called during parsing for storing data. + +```jison +statement + : 'participant' actor { $$='actor'; } + | signal { $$='signal'; } + | note_statement { $$='note'; } + | 'title' message { yy.setTitle($2); } + ; +``` + +In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered. + +> **Note** +> Make sure that the `parseError` function for the parser is defined and calling `mermaid.parseError`. This way a common way of detecting parse errors is provided for the end-user. + +For more info look at the example diagram type: + +The `yy` object has the following function: + +```javascript +exports.parseError = function (err, hash) { + mermaid.parseError(err, hash); +}; +``` + +when parsing the `yy` object is initialized as per below: + +```javascript +const parser = exampleParser.parser; +parser.yy = db; +``` + +### Step 2: Rendering + +Write a renderer that given the data found during parsing renders the diagram. To look at an example look at sequenceRenderer.js rather than the flowchart renderer as this is a more generic example. + +Place the renderer in the diagram folder. + +### Step 3: Detection of the new diagram type + +The second thing to do is to add the capability to detect the new diagram to type to the detectType in `diagram-api/detectType.ts`. The detection should return a key for the new diagram type. +[This key will be used to as the aria roledescription](#aria-roledescription), so it should be a word that clearly describes the diagram type. +For example, if your new diagram uses a UML deployment diagram, a good key would be "UMLDeploymentDiagram" because assistive technologies such as a screen reader +would voice that as "U-M-L Deployment diagram." Another good key would be "deploymentDiagram" because that would be voiced as "Deployment Diagram." A bad key would be "deployment" because that would not sufficiently describe the diagram. + +Note that the diagram type key does not have to be the same as the diagram keyword chosen for the [grammar](#grammar), but it is helpful if they are the same. + +### Step 4: The final piece - triggering the rendering + +At this point when mermaid is trying to render the diagram, it will detect it as being of the new type but there will be no match when trying to render the diagram. To fix this add a new case in the switch statement in main.js:init this should match the diagram type returned from step #2. The code in this new case statement should call the renderer for the diagram type with the data found by the parser as an argument. + +## Usage of the parser as a separate module + +### Setup + +```javascript +const graph = require('./graphDb'); +const flow = require('./parser/flow'); +flow.parser.yy = graph; +``` + +### Parsing + +```javascript +flow.parser.parse(text); +``` + +### Data extraction + +```javascript +graph.getDirection(); +graph.getVertices(); +graph.getEdges(); +``` + +The parser is also exposed in the mermaid api by calling: + +```javascript +const parser = mermaid.getParser(); +``` + +Note that the parse needs a graph object to store the data as per: + +```javascript +flow.parser.yy = graph; +``` + +Look at `graphDb.js` for more details on that object. + +## Layout + +If you are using a dagre based layout, please use flowchart-v2 as a template and by doing that you will be using dagre-wrapper instead of dagreD3 which we are migrating away from. + +### Common parts of a diagram + +There are a few features that are common between the different types of diagrams. We try to standardize the diagrams that work as similar as possible for the end user. The commonalities are: + +- Directives, a way of modifying the diagram configuration from within the diagram code. +- Accessibility, a way for an author to provide additional information like titles and descriptions to people accessing a text with diagrams using a screen reader. +- Themes, there is a common way to modify the styling of diagrams in Mermaid. +- Comments should follow mermaid standards + +Here are some pointers on how to handle these different areas. + +## Accessibility + +Mermaid automatically adds the following accessibility information for the diagram SVG HTML element: + +- aria-roledescription +- accessible title +- accessible description + +### aria-roledescription + +The aria-roledescription is automatically set to [the diagram type](#step-3--detection-of-the-new-diagram-type) and inserted into the SVG element. + +See [the definition of aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) in [the Accessible Rich Internet Applications W3 standard.](https://www.w3.org/WAI/standards-guidelines/aria/) + +### accessible title and description + +The syntax for accessible titles and descriptions is described in [the Accessibility documentation section.](../config/accessibility.md) + +As a design goal, the jison syntax should be similar between the diagrams. + +```jison + +* lexical grammar */ +%lex +%x acc_title +%x acc_descr +%x acc_descr_multiline + +%% +accTitle\s*":"\s* { this.begin("acc_title");return 'acc_title'; } +(?!\n|;|#)*[^\n]* { this.popState(); return "acc_title_value"; } +accDescr\s*":"\s* { this.begin("acc_descr");return 'acc_descr'; } +(?!\n|;|#)*[^\n]* { this.popState(); return "acc_descr_value"; } +accDescr\s*"{"\s* { this.begin("acc_descr_multiline");} +[\}] { this.popState(); } +[^\}]* return "acc_descr_multiline_value"; + +statement + : acc_title acc_title_value { $$=$2.trim();yy.setTitle($$); } + | acc_descr acc_descr_value { $$=$2.trim();yy.setAccDescription($$); } + | acc_descr_multiline_value { $$=$1.trim();yy.setAccDescription($$); } + +``` + +The functions for setting title and description are provided by a common module. This is the import from flowDb.js: + + import { + setAccTitle, + getAccTitle, + getAccDescription, + setAccDescription, + clear as commonClear, + } from '../../commonDb'; + +The accessibility title and description are inserted into the SVG element in the `render` function in mermaidAPI. + +## Theming + +Mermaid supports themes and has an integrated theming engine. You can read more about how the themes can be used [in the docs](../config/theming.md). + +When adding themes to a diagram it comes down to a few important locations in the code. + +The entry point for the styling engine is in **src/styles.js**. The getStyles function will be called by Mermaid when the styles are being applied to the diagram. + +This function will in turn call a function _your diagram should provide_ returning the css for the new diagram. The diagram specific, also which is commonly also called getStyles and located in the folder for your diagram under src/diagrams and should be named styles.js. The getStyles function will be called with the theme options as an argument like in the following example: + +```js +const getStyles = (options) => + ` + .line { + stroke-width: 1; + stroke: ${options.lineColor}; + stroke-dasharray: 2; + } + // ... + `; +``` + +Note that you need to provide your function to the main getStyles by adding it into the themes object in **src/styles.js** like in the xyzDiagram in the provided example: + +```js +const themes = { + flowchart, + 'flowchart-v2': flowchart, + sequence, + xyzDiagram, + //... +}; +``` + +The actual options and values for the colors are defined in **src/theme/theme-\[xyz].js**. If you provide the options your diagram needs in the existing theme files then the theming will work smoothly without hiccups. diff --git a/docs/community/new-diagram.md b/docs/community/new-diagram.md index e3febb8f58..46d7b467bb 100644 --- a/docs/community/new-diagram.md +++ b/docs/community/new-diagram.md @@ -6,51 +6,17 @@ # Adding a New Diagram/Chart 📊 -### Step 1: Grammar & Parsing - -#### Grammar - -This would be to define a JISON grammar for the new diagram type. That should start with a way to identify that the text in the mermaid tag is a diagram of that type. Create a new folder under diagrams for your new diagram type and a parser folder in it. This leads us to step 2. - -For instance: - -- the flowchart starts with the keyword _graph_ -- the sequence diagram starts with the keyword _sequenceDiagram_ - -#### Store data found during parsing +### Examples -There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call an object provided to the parser by the user of the parser. This object can be called during parsing for storing data. +Please refer to the following PRs on how to use Langium to add a new diagram grammar. -```jison -statement - : 'participant' actor { $$='actor'; } - | signal { $$='signal'; } - | note_statement { $$='note'; } - | 'title' message { yy.setTitle($2); } - ; -``` - -In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered. - -> **Note** -> Make sure that the `parseError` function for the parser is defined and calling `mermaid.parseError`. This way a common way of detecting parse errors is provided for the end-user. +- +- -For more info look at the example diagram type: - -The `yy` object has the following function: - -```javascript -exports.parseError = function (err, hash) { - mermaid.parseError(err, hash); -}; -``` - -when parsing the `yy` object is initialized as per below: +> **Warning** +> The below steps are a work in progress and will be updated soon. -```javascript -const parser = exampleParser.parser; -parser.yy = db; -``` +### Step 1: Grammar & Parsing ### Step 2: Rendering @@ -67,52 +33,6 @@ would voice that as "U-M-L Deployment diagram." Another good key would be "deplo Note that the diagram type key does not have to be the same as the diagram keyword chosen for the [grammar](#grammar), but it is helpful if they are the same. -### Step 4: The final piece - triggering the rendering - -At this point when mermaid is trying to render the diagram, it will detect it as being of the new type but there will be no match when trying to render the diagram. To fix this add a new case in the switch statement in main.js:init this should match the diagram type returned from step #2. The code in this new case statement should call the renderer for the diagram type with the data found by the parser as an argument. - -## Usage of the parser as a separate module - -### Setup - -```javascript -const graph = require('./graphDb'); -const flow = require('./parser/flow'); -flow.parser.yy = graph; -``` - -### Parsing - -```javascript -flow.parser.parse(text); -``` - -### Data extraction - -```javascript -graph.getDirection(); -graph.getVertices(); -graph.getEdges(); -``` - -The parser is also exposed in the mermaid api by calling: - -```javascript -const parser = mermaid.getParser(); -``` - -Note that the parse needs a graph object to store the data as per: - -```javascript -flow.parser.yy = graph; -``` - -Look at `graphDb.js` for more details on that object. - -## Layout - -If you are using a dagre based layout, please use flowchart-v2 as a template and by doing that you will be using dagre-wrapper instead of dagreD3 which we are migrating away from. - ### Common parts of a diagram There are a few features that are common between the different types of diagrams. We try to standardize the diagrams that work as similar as possible for the end user. The commonalities are: @@ -142,33 +62,7 @@ See [the definition of aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/ The syntax for accessible titles and descriptions is described in [the Accessibility documentation section.](../config/accessibility.md) -As a design goal, the jison syntax should be similar between the diagrams. - -```jison - -* lexical grammar */ -%lex -%x acc_title -%x acc_descr -%x acc_descr_multiline - -%% -accTitle\s*":"\s* { this.begin("acc_title");return 'acc_title'; } -(?!\n|;|#)*[^\n]* { this.popState(); return "acc_title_value"; } -accDescr\s*":"\s* { this.begin("acc_descr");return 'acc_descr'; } -(?!\n|;|#)*[^\n]* { this.popState(); return "acc_descr_value"; } -accDescr\s*"{"\s* { this.begin("acc_descr_multiline");} -[\}] { this.popState(); } -[^\}]* return "acc_descr_multiline_value"; - -statement - : acc_title acc_title_value { $$=$2.trim();yy.setTitle($$); } - | acc_descr acc_descr_value { $$=$2.trim();yy.setAccDescription($$); } - | acc_descr_multiline_value { $$=$1.trim();yy.setAccDescription($$); } - -``` - -The functions for setting title and description are provided by a common module. This is the import from flowDb.js: +The functions for setting title and description are provided by a common module. This is the import in flowDb.js: import { setAccTitle, diff --git a/packages/mermaid/src/docs/community/new-diagram-jison.md b/packages/mermaid/src/docs/community/new-diagram-jison.md new file mode 100644 index 0000000000..4a9020ba84 --- /dev/null +++ b/packages/mermaid/src/docs/community/new-diagram-jison.md @@ -0,0 +1,220 @@ +# Adding a New Diagram/Chart (Deprecated) 📊 + +```warning +JISON grammars are deprecated in mermaid. Please use Langium instead. See [New Diagram](./new-diagram.md) for more information. + +**New diagrams with JISON grammars will not be accepted.** +``` + +### Step 1: Grammar & Parsing + +#### Grammar + +This would be to define a JISON grammar for the new diagram type. That should start with a way to identify that the text in the mermaid tag is a diagram of that type. Create a new folder under diagrams for your new diagram type and a parser folder in it. This leads us to step 2. + +For instance: + +- the flowchart starts with the keyword _graph_ +- the sequence diagram starts with the keyword _sequenceDiagram_ + +#### Store data found during parsing + +There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call an object provided to the parser by the user of the parser. This object can be called during parsing for storing data. + +```jison +statement + : 'participant' actor { $$='actor'; } + | signal { $$='signal'; } + | note_statement { $$='note'; } + | 'title' message { yy.setTitle($2); } + ; +``` + +In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered. + +```note +Make sure that the `parseError` function for the parser is defined and calling `mermaid.parseError`. This way a common way of detecting parse errors is provided for the end-user. +``` + +For more info look at the example diagram type: + +The `yy` object has the following function: + +```javascript +exports.parseError = function (err, hash) { + mermaid.parseError(err, hash); +}; +``` + +when parsing the `yy` object is initialized as per below: + +```javascript +const parser = exampleParser.parser; +parser.yy = db; +``` + +### Step 2: Rendering + +Write a renderer that given the data found during parsing renders the diagram. To look at an example look at sequenceRenderer.js rather than the flowchart renderer as this is a more generic example. + +Place the renderer in the diagram folder. + +### Step 3: Detection of the new diagram type + +The second thing to do is to add the capability to detect the new diagram to type to the detectType in `diagram-api/detectType.ts`. The detection should return a key for the new diagram type. +[This key will be used to as the aria roledescription](#aria-roledescription), so it should be a word that clearly describes the diagram type. +For example, if your new diagram uses a UML deployment diagram, a good key would be "UMLDeploymentDiagram" because assistive technologies such as a screen reader +would voice that as "U-M-L Deployment diagram." Another good key would be "deploymentDiagram" because that would be voiced as "Deployment Diagram." A bad key would be "deployment" because that would not sufficiently describe the diagram. + +Note that the diagram type key does not have to be the same as the diagram keyword chosen for the [grammar](#grammar), but it is helpful if they are the same. + +### Step 4: The final piece - triggering the rendering + +At this point when mermaid is trying to render the diagram, it will detect it as being of the new type but there will be no match when trying to render the diagram. To fix this add a new case in the switch statement in main.js:init this should match the diagram type returned from step #2. The code in this new case statement should call the renderer for the diagram type with the data found by the parser as an argument. + +## Usage of the parser as a separate module + +### Setup + +```javascript +const graph = require('./graphDb'); +const flow = require('./parser/flow'); +flow.parser.yy = graph; +``` + +### Parsing + +```javascript +flow.parser.parse(text); +``` + +### Data extraction + +```javascript +graph.getDirection(); +graph.getVertices(); +graph.getEdges(); +``` + +The parser is also exposed in the mermaid api by calling: + +```javascript +const parser = mermaid.getParser(); +``` + +Note that the parse needs a graph object to store the data as per: + +```javascript +flow.parser.yy = graph; +``` + +Look at `graphDb.js` for more details on that object. + +## Layout + +If you are using a dagre based layout, please use flowchart-v2 as a template and by doing that you will be using dagre-wrapper instead of dagreD3 which we are migrating away from. + +### Common parts of a diagram + +There are a few features that are common between the different types of diagrams. We try to standardize the diagrams that work as similar as possible for the end user. The commonalities are: + +- Directives, a way of modifying the diagram configuration from within the diagram code. +- Accessibility, a way for an author to provide additional information like titles and descriptions to people accessing a text with diagrams using a screen reader. +- Themes, there is a common way to modify the styling of diagrams in Mermaid. +- Comments should follow mermaid standards + +Here are some pointers on how to handle these different areas. + +## Accessibility + +Mermaid automatically adds the following accessibility information for the diagram SVG HTML element: + +- aria-roledescription +- accessible title +- accessible description + +### aria-roledescription + +The aria-roledescription is automatically set to [the diagram type](#step-3--detection-of-the-new-diagram-type) and inserted into the SVG element. + +See [the definition of aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) in [the Accessible Rich Internet Applications W3 standard.](https://www.w3.org/WAI/standards-guidelines/aria/) + +### accessible title and description + +The syntax for accessible titles and descriptions is described in [the Accessibility documentation section.](../config/accessibility.md) + +As a design goal, the jison syntax should be similar between the diagrams. + +```jison + +* lexical grammar */ +%lex +%x acc_title +%x acc_descr +%x acc_descr_multiline + +%% +accTitle\s*":"\s* { this.begin("acc_title");return 'acc_title'; } +(?!\n|;|#)*[^\n]* { this.popState(); return "acc_title_value"; } +accDescr\s*":"\s* { this.begin("acc_descr");return 'acc_descr'; } +(?!\n|;|#)*[^\n]* { this.popState(); return "acc_descr_value"; } +accDescr\s*"{"\s* { this.begin("acc_descr_multiline");} +[\}] { this.popState(); } +[^\}]* return "acc_descr_multiline_value"; + +statement + : acc_title acc_title_value { $$=$2.trim();yy.setTitle($$); } + | acc_descr acc_descr_value { $$=$2.trim();yy.setAccDescription($$); } + | acc_descr_multiline_value { $$=$1.trim();yy.setAccDescription($$); } + +``` + +The functions for setting title and description are provided by a common module. This is the import from flowDb.js: + +``` +import { + setAccTitle, + getAccTitle, + getAccDescription, + setAccDescription, + clear as commonClear, +} from '../../commonDb'; +``` + +The accessibility title and description are inserted into the SVG element in the `render` function in mermaidAPI. + +## Theming + +Mermaid supports themes and has an integrated theming engine. You can read more about how the themes can be used [in the docs](../config/theming.md). + +When adding themes to a diagram it comes down to a few important locations in the code. + +The entry point for the styling engine is in **src/styles.js**. The getStyles function will be called by Mermaid when the styles are being applied to the diagram. + +This function will in turn call a function _your diagram should provide_ returning the css for the new diagram. The diagram specific, also which is commonly also called getStyles and located in the folder for your diagram under src/diagrams and should be named styles.js. The getStyles function will be called with the theme options as an argument like in the following example: + +```js +const getStyles = (options) => + ` + .line { + stroke-width: 1; + stroke: ${options.lineColor}; + stroke-dasharray: 2; + } + // ... + `; +``` + +Note that you need to provide your function to the main getStyles by adding it into the themes object in **src/styles.js** like in the xyzDiagram in the provided example: + +```js +const themes = { + flowchart, + 'flowchart-v2': flowchart, + sequence, + xyzDiagram, + //... +}; +``` + +The actual options and values for the colors are defined in **src/theme/theme-[xyz].js**. If you provide the options your diagram needs in the existing theme files then the theming will work smoothly without hiccups. diff --git a/packages/mermaid/src/docs/community/new-diagram.md b/packages/mermaid/src/docs/community/new-diagram.md index bc43475bfc..16504ca322 100644 --- a/packages/mermaid/src/docs/community/new-diagram.md +++ b/packages/mermaid/src/docs/community/new-diagram.md @@ -1,51 +1,17 @@ # Adding a New Diagram/Chart 📊 -### Step 1: Grammar & Parsing - -#### Grammar - -This would be to define a JISON grammar for the new diagram type. That should start with a way to identify that the text in the mermaid tag is a diagram of that type. Create a new folder under diagrams for your new diagram type and a parser folder in it. This leads us to step 2. - -For instance: - -- the flowchart starts with the keyword _graph_ -- the sequence diagram starts with the keyword _sequenceDiagram_ - -#### Store data found during parsing - -There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call an object provided to the parser by the user of the parser. This object can be called during parsing for storing data. - -```jison -statement - : 'participant' actor { $$='actor'; } - | signal { $$='signal'; } - | note_statement { $$='note'; } - | 'title' message { yy.setTitle($2); } - ; -``` - -In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered. - -```note -Make sure that the `parseError` function for the parser is defined and calling `mermaid.parseError`. This way a common way of detecting parse errors is provided for the end-user. -``` +### Examples -For more info look at the example diagram type: +Please refer to the following PRs on how to use Langium to add a new diagram grammar. -The `yy` object has the following function: +- https://github.com/mermaid-js/mermaid/pull/4839 +- https://github.com/mermaid-js/mermaid/pull/4751 -```javascript -exports.parseError = function (err, hash) { - mermaid.parseError(err, hash); -}; +```warning +The below steps are a work in progress and will be updated soon. ``` -when parsing the `yy` object is initialized as per below: - -```javascript -const parser = exampleParser.parser; -parser.yy = db; -``` +### Step 1: Grammar & Parsing ### Step 2: Rendering @@ -62,52 +28,6 @@ would voice that as "U-M-L Deployment diagram." Another good key would be "deplo Note that the diagram type key does not have to be the same as the diagram keyword chosen for the [grammar](#grammar), but it is helpful if they are the same. -### Step 4: The final piece - triggering the rendering - -At this point when mermaid is trying to render the diagram, it will detect it as being of the new type but there will be no match when trying to render the diagram. To fix this add a new case in the switch statement in main.js:init this should match the diagram type returned from step #2. The code in this new case statement should call the renderer for the diagram type with the data found by the parser as an argument. - -## Usage of the parser as a separate module - -### Setup - -```javascript -const graph = require('./graphDb'); -const flow = require('./parser/flow'); -flow.parser.yy = graph; -``` - -### Parsing - -```javascript -flow.parser.parse(text); -``` - -### Data extraction - -```javascript -graph.getDirection(); -graph.getVertices(); -graph.getEdges(); -``` - -The parser is also exposed in the mermaid api by calling: - -```javascript -const parser = mermaid.getParser(); -``` - -Note that the parse needs a graph object to store the data as per: - -```javascript -flow.parser.yy = graph; -``` - -Look at `graphDb.js` for more details on that object. - -## Layout - -If you are using a dagre based layout, please use flowchart-v2 as a template and by doing that you will be using dagre-wrapper instead of dagreD3 which we are migrating away from. - ### Common parts of a diagram There are a few features that are common between the different types of diagrams. We try to standardize the diagrams that work as similar as possible for the end user. The commonalities are: @@ -137,33 +57,7 @@ See [the definition of aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/ The syntax for accessible titles and descriptions is described in [the Accessibility documentation section.](../config/accessibility.md) -As a design goal, the jison syntax should be similar between the diagrams. - -```jison - -* lexical grammar */ -%lex -%x acc_title -%x acc_descr -%x acc_descr_multiline - -%% -accTitle\s*":"\s* { this.begin("acc_title");return 'acc_title'; } -(?!\n|;|#)*[^\n]* { this.popState(); return "acc_title_value"; } -accDescr\s*":"\s* { this.begin("acc_descr");return 'acc_descr'; } -(?!\n|;|#)*[^\n]* { this.popState(); return "acc_descr_value"; } -accDescr\s*"{"\s* { this.begin("acc_descr_multiline");} -[\}] { this.popState(); } -[^\}]* return "acc_descr_multiline_value"; - -statement - : acc_title acc_title_value { $$=$2.trim();yy.setTitle($$); } - | acc_descr acc_descr_value { $$=$2.trim();yy.setAccDescription($$); } - | acc_descr_multiline_value { $$=$1.trim();yy.setAccDescription($$); } - -``` - -The functions for setting title and description are provided by a common module. This is the import from flowDb.js: +The functions for setting title and description are provided by a common module. This is the import in flowDb.js: ``` import {