mirror of
https://github.com/mermaid-js/mermaid.git
synced 2025-11-04 04:44:08 +01:00
114 lines
4.9 KiB
Markdown
114 lines
4.9 KiB
Markdown
> **Warning**
|
|
>
|
|
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
|
>
|
|
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/new-diagram.md](../../packages/mermaid/src/docs/community/new-diagram.md).
|
|
|
|
# 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
|
|
|
|
### 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.
|
|
|
|
### 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)
|
|
|
|
The functions for setting title and description are provided by a common module. This is the import in 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.
|