5.5 KB124 lines
Blame
1> **Warning**
2>
3> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
4>
5> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/new-diagram.md](../../packages/mermaid/src/docs/community/new-diagram.md).
6
7# Adding a New Diagram/Chart 📊
8
9### Examples
10
11Please refer to the following PRs on how to use Langium to add a new diagram grammar.
12
13- <https://github.com/mermaid-js/mermaid/pull/4839>
14- <https://github.com/mermaid-js/mermaid/pull/4751>
15
16> **Warning**
17> The below steps are a work in progress and will be updated soon.
18
19### Step 1: Grammar & Parsing
20
21### Step 2: Rendering
22
23Write 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.
24
25Place the renderer in the diagram folder.
26
27### Step 3: Detection of the new diagram type
28
29The 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.
30[This key will be used to as the aria roledescription](#aria-roledescription), so it should be a word that clearly describes the diagram type.
31For example, if your new diagram uses a UML deployment diagram, a good key would be "UMLDeploymentDiagram" because assistive technologies such as a screen reader
32would 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.
33
34Note 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.
35
36### Common parts of a diagram
37
38There 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:
39
40- Directives, a way of modifying the diagram configuration from within the diagram code.
41- 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.
42- Themes, there is a common way to modify the styling of diagrams in Mermaid.
43- Comments should follow mermaid standards
44
45Here are some pointers on how to handle these different areas.
46
47## Accessibility
48
49Mermaid automatically adds the following accessibility information for the diagram SVG HTML element:
50
51- aria-roledescription
52- accessible title
53- accessible description
54
55### aria-roledescription
56
57The aria-roledescription is automatically set to [the diagram type](#step-3--detection-of-the-new-diagram-type) and inserted into the SVG element.
58
59See [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/)
60
61### accessible title and description
62
63The syntax for accessible titles and descriptions is described in [the Accessibility documentation section.](../config/accessibility.md)
64
65The functions for setting title and description are provided by a common module. This is the import in flowDb.js:
66
67```
68import {
69 setAccTitle,
70 getAccTitle,
71 getAccDescription,
72 setAccDescription,
73 clear as commonClear,
74} from '../../commonDb';
75```
76
77The accessibility title and description are inserted into the SVG element in the `render` function in mermaidAPI.
78
79## Theming
80
81Mermaid 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).
82
83When adding themes to a diagram it comes down to a few important locations in the code.
84
85The 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.
86
87This 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:
88
89```js
90const getStyles = (options) =>
91 `
92 .line {
93 stroke-width: 1;
94 stroke: ${options.lineColor};
95 stroke-dasharray: 2;
96 }
97 // ...
98 `;
99```
100
101Note 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:
102
103```js
104const themes = {
105 flowchart,
106 'flowchart-v2': flowchart,
107 sequence,
108 xyzDiagram,
109 //...
110};
111```
112
113The 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.
114
115## Examples
116
117The `@mermaid-js/examples` package contains a collection of examples that are used by tools like mermaid.live to help users get started with the new diagram.
118
119You can duplicate an existing diagram example file, eg: `packages/examples/src/examples/flowchart.ts`, and modify it with details specific to your diagram.
120
121Then you can import the example in the `packages/examples/src/index.ts` file and add it to the `examples` array.
122
123Each diagram should have at least one example, and that should be marked as default. It is good to add more examples to showcase different features of the diagram.
124