From 3926594c6a6d5741f31081aaaaac3189ccdaac1b Mon Sep 17 00:00:00 2001 From: Steph <35910788+huynhicode@users.noreply.github.com> Date: Thu, 7 Mar 2024 13:02:16 -0800 Subject: [PATCH 01/22] add latest blog posts --- docs/news/blog.md | 12 ++++++++++++ packages/mermaid/src/docs/news/blog.md | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/docs/news/blog.md b/docs/news/blog.md index b0ebf5244..b40cac939 100644 --- a/docs/news/blog.md +++ b/docs/news/blog.md @@ -6,6 +6,18 @@ # Blog +## [Mermaid Chart GPT Is Now Available In the GPT Store!](https://www.mermaidchart.com/blog/posts/mermaid-chart-gpt-is-now-available-in-the-gpt-store/) + +7 March 2024 · 3 mins + +Mermaid Chart GPT is Now Available In the GPT Store! + +## [How to Make a Flowchart with Mermaid Chart](https://www.mermaidchart.com/blog/posts/how-to-make-flowcharts-with-mermaid-chart/) + +30 January 2024 · 6 mins + +Learn how to make a flowchart with Mermaid Chart, the leading text-to-diagram platform for both developers and non-developers. + ## [How one data scientist uses Mermaid Chart to quickly and easily build flowcharts](https://www.mermaidchart.com/blog/posts/customer-spotlight-ari-tal/) 23 January 2024 · 4 mins diff --git a/packages/mermaid/src/docs/news/blog.md b/packages/mermaid/src/docs/news/blog.md index c986e1e58..fd51b2354 100644 --- a/packages/mermaid/src/docs/news/blog.md +++ b/packages/mermaid/src/docs/news/blog.md @@ -1,5 +1,17 @@ # Blog +## [Mermaid Chart GPT Is Now Available In the GPT Store!](https://www.mermaidchart.com/blog/posts/mermaid-chart-gpt-is-now-available-in-the-gpt-store/) + +7 March 2024 · 3 mins + +Mermaid Chart GPT is Now Available In the GPT Store! + +## [How to Make a Flowchart with Mermaid Chart](https://www.mermaidchart.com/blog/posts/how-to-make-flowcharts-with-mermaid-chart/) + +30 January 2024 · 6 mins + +Learn how to make a flowchart with Mermaid Chart, the leading text-to-diagram platform for both developers and non-developers. + ## [How one data scientist uses Mermaid Chart to quickly and easily build flowcharts](https://www.mermaidchart.com/blog/posts/customer-spotlight-ari-tal/) 23 January 2024 · 4 mins From 8f457815e9089ac945f26394ed53c06943493849 Mon Sep 17 00:00:00 2001 From: Jakub Mikulas Date: Fri, 8 Mar 2024 10:13:52 +0100 Subject: [PATCH 02/22] 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 2dc815ee2..de5746823 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 e2d686612..861493aa3 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 03/22] 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 | 128 +--------- .../src/docs/community/new-diagram-jison.md | 220 +++++++++++++++++ .../mermaid/src/docs/community/new-diagram.md | 130 +--------- 4 files changed, 465 insertions(+), 235 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 000000000..40164fe8c --- /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 e3febb8f5..46d7b467b 100644 --- a/docs/community/new-diagram.md +++ b/docs/community/new-diagram.md @@ -6,52 +6,18 @@ # Adding a New Diagram/Chart 📊 +### Examples + +Please refer to the following PRs on how to use Langium to add a new diagram grammar. + +- +- + +> **Warning** +> The below steps are a work in progress and will be updated soon. + ### 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. @@ -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 000000000..4a9020ba8 --- /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 bc43475bf..16504ca32 100644 --- a/packages/mermaid/src/docs/community/new-diagram.md +++ b/packages/mermaid/src/docs/community/new-diagram.md @@ -1,52 +1,18 @@ # Adding a New Diagram/Chart 📊 +### Examples + +Please refer to the following PRs on how to use Langium to add a new diagram grammar. + +- https://github.com/mermaid-js/mermaid/pull/4839 +- https://github.com/mermaid-js/mermaid/pull/4751 + +```warning +The below steps are a work in progress and will be updated soon. +``` + ### 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. @@ -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 { From 244b161032ce3ee997cfdace4ee152d472e2e82f Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Mon, 11 Mar 2024 14:56:18 +0530 Subject: [PATCH 04/22] Add langium --- .cspell/libraries.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.cspell/libraries.txt b/.cspell/libraries.txt index d1ab97662..9d2926186 100644 --- a/.cspell/libraries.txt +++ b/.cspell/libraries.txt @@ -36,6 +36,7 @@ jsfiddle jsonschema katex khroma +langium mathml matplotlib mdbook From 32ca0b97fc0c08bf1f13b215b624cacc8aaf1eca Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Mon, 11 Mar 2024 14:07:41 +0530 Subject: [PATCH 05/22] feat: Make the examples interactive in the documentation site. Ctrl/Cmd + Enter and a run button is added. The feature was first implemented in https://github.com/mermaid-js/mermaid/pull/5330. This is a simplified version without introducing additional dependencies. Co-authored-by: Anton --- .../docs/.vitepress/mermaid-markdown-all.ts | 15 +---- .../src/docs/.vitepress/theme/Mermaid.vue | 64 +++++++++++++++++-- 2 files changed, 60 insertions(+), 19 deletions(-) diff --git a/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts b/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts index 30f044d98..643ce395e 100644 --- a/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts +++ b/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts @@ -18,20 +18,7 @@ const MermaidExample = async (md: MarkdownRenderer) => { 'Missing MarkdownIt highlight function (should be automatically created by vitepress' ); } - - // doing ```mermaid-example {line-numbers=5 highlight=14-17} is not supported - const langAttrs = ''; - return ` -
Code:
-
- - mermaid - ${ - // html is pre-escaped by the highlight function - // (it also adds `v-pre` to ignore Vue template syntax) - md.options.highlight(token.content, 'mermaid', langAttrs) - } -
`; + return ''; } else if (token.info.trim() === 'mermaid') { const key = index; return ` diff --git a/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue b/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue index 5012d3067..ee99bc884 100644 --- a/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue +++ b/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue @@ -1,4 +1,14 @@ @@ -18,15 +28,29 @@ const props = defineProps({ }); const svg = ref(''); +const code = ref(decodeURIComponent(props.graph)); +const ctrlSymbol = ref(navigator.platform.includes('Mac') ? '⌘' : 'Ctrl'); +const editableContent = ref(null); + let mut = null; +const updateCode = (event) => { + code.value = event.target.innerText; +}; + onMounted(async () => { mut = new MutationObserver(() => renderChart()); mut.observe(document.documentElement, { attributes: true }); + + // Set the initial value of the contenteditable element + // We cannot bind using `{{ code }}` because it will rerender the whole component + // when the value changes, shifting the cursor when enter is used + editableContent.value.textContent = code.value; + await renderChart(); //refresh images on first render - const hasImages = //.exec(decodeURIComponent(props.graph))?.length > 0; + const hasImages = //.exec(code.value)?.length > 0; if (hasImages) setTimeout(() => { let imgElements = document.getElementsByTagName('img'); @@ -51,16 +75,14 @@ onMounted(async () => { onUnmounted(() => mut.disconnect()); const renderChart = async () => { - console.log('rendering chart' + props.id + props.graph); + console.log('rendering chart' + props.id + code.value); const hasDarkClass = document.documentElement.classList.contains('dark'); const mermaidConfig = { securityLevel: 'loose', startOnLoad: false, theme: hasDarkClass ? 'dark' : 'default', }; - - console.log({ mermaidConfig }); - let svgCode = await render(props.id, decodeURIComponent(props.graph), mermaidConfig); + let svgCode = await render(props.id, code.value, mermaidConfig); // This is a hack to force v-html to re-render, otherwise the diagram disappears // when **switching themes** or **reloading the page**. // The cause is that the diagram is deleted during rendering (out of Vue's knowledge). @@ -70,3 +92,35 @@ const renderChart = async () => { svg.value = `${svgCode} ${salt}`; }; + + From 6422175ef24eb4435967e7bac063c09123e0ced6 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Mon, 11 Mar 2024 14:52:08 +0530 Subject: [PATCH 06/22] Change run symbol --- packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue b/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue index ee99bc884..59a5bbba9 100644 --- a/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue +++ b/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue @@ -6,7 +6,7 @@
{{ ctrlSymbol }} + Enter| - +
From 08a7f662ea305c19efb950b893933f6b0f0350f9 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Mon, 11 Mar 2024 17:03:26 +0530 Subject: [PATCH 07/22] Address review comments Support ctrl+enter Support mermaid-nocode Use `contenteditable="plaintext-only"` Co-authored-by: Alois Klink --- packages/mermaid/scripts/docs.mts | 5 +-- .../docs/.vitepress/mermaid-markdown-all.ts | 32 ++++++------------- .../src/docs/.vitepress/theme/Mermaid.vue | 32 ++++++++++++------- 3 files changed, 32 insertions(+), 37 deletions(-) diff --git a/packages/mermaid/scripts/docs.mts b/packages/mermaid/scripts/docs.mts index 42e299c54..31d2a7c8f 100644 --- a/packages/mermaid/scripts/docs.mts +++ b/packages/mermaid/scripts/docs.mts @@ -252,11 +252,12 @@ export function transformMarkdownAst({ node.lang = MERMAID_KEYWORD; return [node]; } else if (MERMAID_EXAMPLE_KEYWORDS.includes(node.lang)) { - // Return 2 nodes: + // If Vitepress, return only the original node with the language now set to 'mermaid-example' (will be rendered using custom renderer) + // Else Return 2 nodes: // 1. the original node with the language now set to 'mermaid-example' (will be rendered as code), and // 2. a copy of the original node with the language set to 'mermaid' (will be rendered as a diagram) node.lang = MERMAID_CODE_ONLY_KEYWORD; - return [node, Object.assign({}, node, { lang: MERMAID_KEYWORD })]; + return vitepress ? [node] : [node, Object.assign({}, node, { lang: MERMAID_KEYWORD })]; } // Transform these blocks into block quotes. diff --git a/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts b/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts index 643ce395e..64a069b4c 100644 --- a/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts +++ b/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts @@ -9,22 +9,15 @@ const MermaidExample = async (md: MarkdownRenderer) => { md.renderer.rules.fence = (tokens, index, options, env, slf) => { const token = tokens[index]; - - if (token.info.trim() === 'mermaid-example') { - if (!md.options.highlight) { - // this function is always created by vitepress, but we need to check it - // anyway to make TypeScript happy - throw new Error( - 'Missing MarkdownIt highlight function (should be automatically created by vitepress' - ); - } - return ''; - } else if (token.info.trim() === 'mermaid') { + const language = token.info.trim(); + if (language.startsWith('mermaid')) { const key = index; return ` `; - } - if (token.info.trim() === 'warning') { + } else if (language === 'warning') { return `

WARNING

${token.content}}

`; - } - - if (token.info.trim() === 'note') { + } else if (language === 'note') { return `

NOTE

${token.content}}

`; - } - - if (token.info.trim() === 'regexp') { + } else if (language === 'regexp') { // shiki doesn't yet support regexp code blocks, but the javascript // one still makes RegExes look good token.info = 'javascript'; // use trimEnd to move trailing `\n` outside if the JavaScript regex `/` block token.content = `/${token.content.trimEnd()}/\n`; return defaultRenderer(tokens, index, options, env, slf); - } - - if (token.info.trim() === 'jison') { + } else if (language === 'jison') { return `
jison diff --git a/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue b/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue index 59a5bbba9..a4fb9bf04 100644 --- a/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue +++ b/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue @@ -1,12 +1,14 @@