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