marcel/mermaid
1
0
Fork 0
mirror of https://github.com/mermaid-js/mermaid.git synced 2025-09-06 00:56:42 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'develop' into layout-v3-continued

Browse Source
This commit is contained in:
Knut Sveidqvist
2023-01-11 18:03:09 +01:00
parent 0e3dadc53c 1fca5131c3
commit 094b97de12
135 changed files with 3660 additions and 2642 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/community/newDiagram.md
View File

@@ -14,8 +14,8 @@ This would be to define a jison grammar for the new diagram type. That should st
For instance:
- the flowchart starts with the keyword graph.
- the sequence diagram starts with the keyword sequenceDiagram
- the flowchart starts with the keyword _graph_
- the sequence diagram starts with the keyword _sequenceDiagram_
#### Store data found during parsing
@@ -60,7 +60,12 @@ 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 new diagram to type to the detectType in utils.js. The detection should return a key for 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 utils.js. 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 use 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
@@ -168,17 +173,23 @@ It is probably a good idea to keep the handling similar to this in your new diag
## Accessibility
The syntax for adding title and description looks like this:
Mermaid automatically adds the following accessibility information for the diagram SVG HTML element:
accTitle: The title
accDescr: The description
- aria-roledescription
- accessible title
- accessible description
accDescr {
Syntax for a description text
written on multiple lines.
}
### aria-roledescription
In a similar way to the directives the jison syntax are quite similar between the diagrams.
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 documenation section.](../config/accessibility.md)
In a similar way to the directives, the jison syntax are quite similar between the diagrams.
```jison
@@ -214,18 +225,7 @@ The functions for setting title and description are provided by a common module.
clear as commonClear,
} from '../../commonDb';
For rendering the accessibility tags you have again an existing function you can use.
**In the renderer:**
```js
import addSVGAccessibilityFields from '../../accessibility';
/* ... */
// Adds title and description to the flow chart
addSVGAccessibilityFields(parser.yy, svg, id);
```
The accessibility title and description are inserted into the SVG element in the `render` function in mermaidAPI.
## Theming

412
docs/config/accessibility.md
View File

@@ -10,118 +10,172 @@
Now with Mermaid library in much wider use, we have started to work towards more accessible features, based on the feedback from the community.
To begin with, we have added a new feature to Mermaid library, which is to support accessibility options, **Accessibility Title** and **Accessibility Description**.
Adding accessibility means that the rich information communicated by visual diagrams can be made available to those using assistive technologies (and of course to search engines).
[Read more about Accessible Rich Internet Applications and the W3 standards.](https://www.w3.org/WAI/standards-guidelines/aria/)
This support for accessibility options is available for all the diagrams/chart types. Also, we have tired to keep the same format for the accessibility options, so that it is easy to understand and maintain.
Mermaid will automatically insert the [aria-roledescription](#aria-roledescription) and, if provided in the diagram text by the diagram author, the [accessible title and description.](#accessible-title-and-description)
## Defining Accessibility Options
### aria-roledescription
### Single line accessibility values
The [aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) for the SVG HTML element is set to the diagram type key. (Note this may be slightly different than the keyword used for the diagram in the diagram text.)
The diagram authors can now add the accessibility options in the diagram definition, using the `accTitle` and `accDescr` keywords, where each keyword is followed by `:` and the string value for title and description like:
For example: The diagram type key for a state diagram is "stateDiagram". Here (a part of) the HTML of the SVG tag that shows the automatically inserted aria-roledscription set to "stateDiagram". _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
- `accTitle: "Your Accessibility Title"` or
- `accDescr: "Your Accessibility Description"`
```html
<svg
aria-roledescription="stateDiagram"
class="statediagram"
xmlns="http://www.w3.org/2000/svg"
width="100%"
id="mermaid-1668720491568"
></svg>
```
**When these two options are defined, they will add a corresponding `<title>` and `<desc>` tag in the SVG.**
### Accessible Title and Description
Let us take a look at the following example with a flowchart diagram:
Support for accessible titles and descriptions is available for all diagrams/chart types. We have tried to keep the same keywords and format for all diagrams so that it is easy to understand and maintain.
The accessible title and description will add `<title>` and `<desc>` elements within the SVG element and the [aria-labelledby](https://www.w3.org/TR/wai-aria/#aria-labelledby) and [aria-describedby](https://www.w3.org/TR/wai-aria/#aria-describedby) attributes in the SVG tag.
Here is HTML that is generated, showing that the SVG element is labelled by the accessible title (id = `chart-title-mermaid-1668725057758`)
and described by the accessible description (id = `chart-desc-mermaid-1668725057758` );
and the accessible title element (text = "This is the accessible title")
and the accessible description element (text = "This is an accessible description").
_(Note that some of the SVG attributes and the SVG contents are omitted for clarity.)_
```html
<svg
aria-labelledby="chart-title-mermaid-1668725057758"
aria-describedby="chart-desc-mermaid-1668725057758"
xmlns="http://www.w3.org/2000/svg"
width="100%"
id="mermaid-1668725057758"
>
<title id="chart-title-mermaid-1668725057758">This is the accessible title</title>
<desc id="chart-desc-mermaid-1668725057758">This is an accessible description</desc>
</svg>
```
Details for the syntax follow.
#### accessible title
The **accessible title** is specified with the **accTitle** _keyword_, followed by a colon (`:`), and the string value for the title.
The string value ends at the end of the line. (It can only be a single line.)
Ex: `accTitle: This is a single line title`
See [the accTitle and accDescr usage examples](#acctitle-and-accdescr-usage-examples) for how this can be used in a diagram and the resulting HTML generated.
#### accessible description
An accessible description can be 1 line long (a single line) or many lines long.
The **single line accessible description** is specified with the **accDescr** _keyword_, followed by a colon (`:`), followed by the string value for the description.
Ex: `accDescr: This is a single line description.`
A **multiple line accessible description** _does not have a colon (`:`) after the accDescr keyword_ and is surrounded by curly brackets (`{}`).
Ex:
```markdown
accDescr {
This is a multiple line accessible description.
It does not have a colon and is surrounded by curly brackets.
}
```
See [the accTitle and accDescr usage examples](#acctitle-and-accdescr-usage-examples) for how this can be used in a diagram and the resulting HTML generated.
#### accTitle and accDescr Usage Examples
- Flowchart with the accessible title "Big Decisions" and the single-line accessible description "Bob's Burgers process for making big decisions"
```mermaid-example
graph LR
accTitle: Big decisions
accDescr: Flow chart of the decision making process
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
graph LR
accTitle: Big Decisions
accDescr: Bob's Burgers process for making big decisions
A[Identify Big Descision] --> B{Make Big Decision}
B --> D[Be done]
```
```mermaid
graph LR
accTitle: Big decisions
accDescr: Flow chart of the decision making process
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
graph LR
accTitle: Big Decisions
accDescr: Bob's Burgers process for making big decisions
A[Identify Big Descision] --> B{Make Big Decision}
B --> D[Be done]
```
See in the code snippet above, the `accTitle` and `accDescr` are defined in the diagram definition. They result in the following tags in SVG code:
Here is the HTML generated for the SVG element: _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
![Accessibility options rendered inside SVG](img/accessibility-div-example.png)
```html
<svg
aria-labelledby="chart-title-mermaid_382ee221"
aria-describedby="chart-desc-mermaid_382ee221"
aria-roledescription="flowchart-v2"
xmlns="http://www.w3.org/2000/svg"
width="100%"
id="mermaid_382ee221"
>
<title id="chart-title-mermaid_382ee221">Big decisions</title>
<desc id="chart-desc-mermaid_382ee221">Bob's Burgers process for making big decisions</desc>
</svg>
```
### Multi-line Accessibility title/description
You can also define the accessibility options in a multi-line format, where the keyword is followed by opening curly bracket `{` and then multiple lines, followed by a closing `}`.
`accTitle: My single line title value` (**_single line format_**)
vs
`accDescr: { My multi-line description of the diagram }` (**_multi-line format_**)
Let us look at it in the following example, with same flowchart:
- Flowchart with the accessible title "Bob's Burger's Making Big Decisions" and the multiple line accessible description "The official Bob's Burgers corporate processes that are used
for making very, very big decisions.
This is actually a very simple flow: identify the big decision and then make the big decision."
```mermaid-example
graph LR
accTitle: Big decisions
graph LR
accTitle: Bob's Burger's Making Big Decisions
accDescr {
My multi-line description
of the diagram
}
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
The official Bob's Burgers corporate processes that are used
for making very, very big decisions.
This is actually a very simple flow: identify the big decision and then make the big decision.
}
A[Identify Big Descision] --> B{Make Big Decision}
B --> D[Be done]
```
```mermaid
graph LR
accTitle: Big decisions
graph LR
accTitle: Bob's Burger's Making Big Decisions
accDescr {
My multi-line description
of the diagram
}
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
The official Bob's Burgers corporate processes that are used
for making very, very big decisions.
This is actually a very simple flow: identify the big decision and then make the big decision.
}
A[Identify Big Descision] --> B{Make Big Decision}
B --> D[Be done]
```
See in the code snippet above, the `accTitle` and `accDescr` are defined in the diagram definition. They result in the following tags in SVG code:
Here is the HTML generated for the SVG element: _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
![Accessibility options rendered inside SVG](img/accessibility-div-example-2.png)
### Sample Code Snippet for other diagram types
#### Sequence Diagram
```mermaid-example
sequenceDiagram
accTitle: My Sequence Diagram
accDescr: My Sequence Diagram Description
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
```html
<svg
aria-labelledby="chart-title-mermaid_382ee221"
aria-describedby="chart-desc-mermaid_382ee221"
aria-roledescription="flowchart-v2"
xmlns="http://www.w3.org/2000/svg"
width="100%"
id="mermaid_382ee221"
>
<title id="chart-title-mermaid_382ee221">Big decisions</title>
<desc id="chart-desc-mermaid_382ee221">
The official Bob's Burgers corporate processes that are used for making very, very big
decisions. This is actually a very simple flow: identify the big decision and then make the big
decision.
</desc>
</svg>
```
```mermaid
sequenceDiagram
accTitle: My Sequence Diagram
accDescr: My Sequence Diagram Description
#### Sample Code Snippets for other diagram types
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
```
#### Class Diagram
##### Class Diagram
```mermaid-example
classDiagram
@@ -139,27 +193,7 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
Vehicle <|-- Car
```
#### State Diagram
```mermaid-example
stateDiagram
accTitle: My State Diagram
accDescr: My State Diagram Description
s1 --> s2
```
```mermaid
stateDiagram
accTitle: My State Diagram
accDescr: My State Diagram Description
s1 --> s2
```
#### Entity Relationship Diagram
##### Entity Relationship Diagram
```mermaid-example
erDiagram
@@ -183,41 +217,7 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
```
#### User Journey Diagram
```mermaid-example
journey
accTitle: My User Journey Diagram
accDescr: My User Journey Diagram Description
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 5: Me
```
```mermaid
journey
accTitle: My User Journey Diagram
accDescr: My User Journey Diagram Description
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 5: Me
```
#### Gantt Chart
##### Gantt Chart
```mermaid-example
gantt
@@ -251,7 +251,45 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
```
#### Pie Chart
##### Gitgraph
```mermaid-example
gitGraph
accTitle: My Gitgraph Accessibility Title
accDescr: My Gitgraph Accessibility Description
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
commit
```
```mermaid
gitGraph
accTitle: My Gitgraph Accessibility Title
accDescr: My Gitgraph Accessibility Description
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
commit
```
##### Pie Chart
```mermaid-example
pie
@@ -279,7 +317,7 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
```
#### Requirement Diagram
##### Requirement Diagram
```mermaid-example
requirementDiagram
@@ -321,40 +359,78 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
```
#### Gitgraph
##### Sequence Diagram
```mermaid-example
gitGraph
accTitle: My Gitgraph Accessibility Title
accDescr: My Gitgraph Accessibility Description
sequenceDiagram
accTitle: My Sequence Diagram
accDescr: My Sequence Diagram Description
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
commit
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
```
```mermaid
sequenceDiagram
accTitle: My Sequence Diagram
accDescr: My Sequence Diagram Description
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
```
##### State Diagram
```mermaid-example
stateDiagram
accTitle: My State Diagram
accDescr: My State Diagram Description
s1 --> s2
```
```mermaid
gitGraph
accTitle: My Gitgraph Accessibility Title
accDescr: My Gitgraph Accessibility Description
stateDiagram
accTitle: My State Diagram
accDescr: My State Diagram Description
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
commit
s1 --> s2
```
##### User Journey Diagram
```mermaid-example
journey
accTitle: My User Journey Diagram
accDescr: My User Journey Diagram Description
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 5: Me
```
```mermaid
journey
accTitle: My User Journey Diagram
accDescr: My User Journey Diagram Description
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 5: Me
```

3
docs/config/directives.md
View File

@@ -32,7 +32,8 @@ Mermaid basically supports two types of configuration options to be overridden b
**NOTE:** These options listed here are not all the configuration options. To get hold of all the configuration options, please refer to the [defaultConfig.ts](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/defaultConfig.ts) in the source code.
Soon we plan to publish a complete list of top-level configurations & all the diagram specific configurations, with their possible values in the docs
> **Note**
> We plan to publish a complete list of top-level configurations & all the diagram specific configurations, with their possible values in the docs soon.
## Declaring directives

20
docs/config/n00b-advanced.md
View File

@@ -10,17 +10,21 @@
A more condensed html code can be achieved by embedding the mermaid code in its own .js file, which is referenced like so:
stuff stuff
</div>
</body>
</html>
```html
...
</div>
</body>
</html>
```
The actual mermaid file could for example look like this:
mermaid content...
---
```javascript
mermaid content ...
```
## mermaid configuration options
...
```markdown
(coming soon)
```

43
docs/config/setup/modules/mermaidAPI.md
View File

@@ -12,6 +12,16 @@
Renames and re-exports [mermaidAPI](mermaidAPI.md#mermaidapi)
## Type Aliases
### D3Element
Ƭ **D3Element**: `any`
#### Defined in
[mermaidAPI.ts:72](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L72)
## Variables
### mermaidAPI
@@ -80,7 +90,7 @@ mermaid.initialize(config);
#### Defined in
[mermaidAPI.ts:939](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L939)
[mermaidAPI.ts:961](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L961)
## Functions
@@ -111,7 +121,7 @@ Return the last node appended
#### Defined in
[mermaidAPI.ts:284](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L284)
[mermaidAPI.ts:285](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L285)
---
@@ -137,7 +147,7 @@ the cleaned up svgCode
#### Defined in
[mermaidAPI.ts:235](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L235)
[mermaidAPI.ts:236](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L236)
---
@@ -163,7 +173,7 @@ the string with all the user styles
#### Defined in
[mermaidAPI.ts:164](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L164)
[mermaidAPI.ts:165](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L165)
---
@@ -186,7 +196,7 @@ the string with all the user styles
#### Defined in
[mermaidAPI.ts:212](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L212)
[mermaidAPI.ts:213](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L213)
---
@@ -213,7 +223,7 @@ with an enclosing block that has each of the cssClasses followed by !important;
#### Defined in
[mermaidAPI.ts:148](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L148)
[mermaidAPI.ts:149](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L149)
---
@@ -233,7 +243,7 @@ with an enclosing block that has each of the cssClasses followed by !important;
#### Defined in
[mermaidAPI.ts:128](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L128)
[mermaidAPI.ts:129](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L129)
---
@@ -253,7 +263,7 @@ with an enclosing block that has each of the cssClasses followed by !important;
#### Defined in
[mermaidAPI.ts:99](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L99)
[mermaidAPI.ts:100](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L100)
---
@@ -279,25 +289,24 @@ Put the svgCode into an iFrame. Return the iFrame code
#### Defined in
[mermaidAPI.ts:263](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L263)
[mermaidAPI.ts:264](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L264)
---
### removeExistingElements
▸ **removeExistingElements**(`doc`, `isSandboxed`, `id`, `divSelector`, `iFrameSelector`): `void`
▸ **removeExistingElements**(`doc`, `id`, `divId`, `iFrameId`): `void`
Remove any existing elements from the given document
#### Parameters
| Name | Type | Description |
| :--------------- | :--------- | :---------------------------------------------- |
| `doc` | `Document` | the document to removed elements from |
| `isSandboxed` | `boolean` | whether or not we are in sandboxed mode |
| `id` | `string` | id for any existing SVG element |
| `divSelector` | `string` | selector for any existing enclosing div element |
| `iFrameSelector` | `string` | selector for any existing iFrame element |
| Name | Type | Description |
| :--------- | :--------- | :------------------------------------ |
| `doc` | `Document` | the document to removed elements from |
| `id` | `string` | id for any existing SVG element |
| `divId` | `string` | - |
| `iFrameId` | `string` | - |
#### Returns

818
docs/config/theming.md
View File

@@ -6,31 +6,27 @@
# Theme Configuration
With Version 8.7.0 Mermaid comes out with a system for dynamic and integrated configuration of themes. The intent is to increase the customizability and ease of styling for mermaid diagrams.
Dynamic and integrated theme configuration was introduced in Mermaid version 8.7.0.
The theme can be altered by changing the root level variable `theme` variable in the configuration. To change it for the whole site you must use the `initialize` call. To do it for just for a single diagram you can use the `%%init%%` directive
Themes can now be customized at the site-wide level, or on individual Mermaid diagrams. For site-wide theme customization, the `initialize` call is used. For diagram specific customization, the `init` directive is used.
Themes follow and build upon the Levels of Configuration, and employ `directives` to modify and create custom configurations, as they were introduced in Version [8.6.0](./8.6.0_docs.md).
## Available Themes
## Deployable Themes
1. [**default**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-default.js) - This is the default theme for all diagrams.
The following are a list of **Deployable themes**, sample `%%init%%` directives and `initialize` calls.
2. [**neutral**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-neutral.js) - This theme is great for black and white documents that will be printed.
1. **base**- Designed to be modified, as the name implies it is supposed to be used as the base for making custom themes.
3. [**dark**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-dark.js) - This theme goes well with dark-colored elements or dark-mode.
2. **forest**- A theme full of light greens that is easy on the eyes.
4. [**forest**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-forest.js) - This theme contains shades of green.
3. **dark**- A theme that would go well with other dark-colored elements.
5. [**base**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-base.js) - This is the only theme that can be modified. Use this theme as the base for customizations.
4. **default**- The default theme for all diagrams.
## Site-wide Theme
5. **neutral**- The theme to be used for black and white printing.
To customize themes site-wide, call the `initialize` method on the `mermaidAPI`.
## Site-wide Themes
Site-wide themes are declared via `initialize` by site owners.
Example of `Initialize` call setting `theme` to `base`:
Example of `initialize` call setting `theme` to `base`:
```javascript
mermaidAPI.initialize({
@@ -39,28 +35,64 @@ mermaidAPI.initialize({
});
```
**Notes**: Only site owners can use the `mermaidAPI.initialize` call, to set values. Site-Users will have to use `%%init%%` to modify or create the theme for their diagrams.
## Diagram-specific Themes
## Themes at the Local or Current Level
To customize the theme of an individual diagram, use the `init` directive.
When Generating a diagram using on a webpage that supports mermaid. It is also possible to override site-wide theme settings locally, for a specific diagram, using directives, as long as it is not prohibited by the `secure` array.
Example of `init` directive setting the `theme` to `forest`:
```mermaid-example
%%{init: {'theme':'base'}}%%
%%{init: {'theme':'forest'}}%%
graph TD
a --> b
```
```mermaid
%%{init: {'theme':'base'}}%%
%%{init: {'theme':'forest'}}%%
graph TD
a --> b
```
Here is an example of how `%%init%%` can set the theme to 'base', this assumes that `themeVariables` are set to default:
```mermaid-example
%%{init: {'theme':'forest'}}%%
graph TD
a --> b
```
```mermaid
%%{init: {'theme':'forest'}}%%
graph TD
a --> b
```
> **Reminder**: the only theme that can be customed is the `base` theme. The following section covers how to use `themeVariables` for customizations.
## Customizing Themes with `themeVariables`
To make a custom theme, modify `themeVariables` via `init`.
You will need to use the [base](#available-themes) theme as it is the only modifiable theme.
| Parameter | Description | Type | Properties |
| -------------- | ------------------------------------ | ------ | --------------------------------------------------------------------------------------------------- |
| themeVariables | Modifiable with the `init` directive | Object | `primaryColor`, `primaryTextColor`, `lineColor` ([see full list](#theme-variables-reference-table)) |
Example of modifying `themeVariables` using the `init` directive:
```mermaid-example
%%{init: {'theme':'base'}}%%
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#BB2528',
'primaryTextColor': '#fff',
'primaryBorderColor': '#7C0000',
'lineColor': '#F8B229',
'secondaryColor': '#006100',
'tertiaryColor': '#fff'
}
}
}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
@@ -78,7 +110,19 @@ Here is an example of how `%%init%%` can set the theme to 'base', this assumes t
```
```mermaid
%%{init: {'theme':'base'}}%%
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#BB2528',
'primaryTextColor': '#fff',
'primaryBorderColor': '#7C0000',
'lineColor': '#F8B229',
'secondaryColor': '#006100',
'tertiaryColor': '#fff'
}
}
}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
@@ -95,20 +139,20 @@ Here is an example of how `%%init%%` can set the theme to 'base', this assumes t
end
```
# List of Themes
# Customizing Themes with `themeVariables`
The easiest way to make a custom theme is to start with the base theme, and just modify theme variables through `themeVariables`, via `%%init%%`.
| Parameter | Description | Type | Required | Objects contained |
| -------------- | ------------------------------------------------------------------ | ----- | -------- | ---------------------------------- |
| themeVariables | Array containing objects, modifiable with the `%%init%%` directive | Array | Required | primaryColor, lineColor, textColor |
**Here is an example of overriding `primaryColor` through `themeVariables` and giving everything a different look, using `%%init%%`.**
```mermaid-example
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ff0000'}}}%%
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#BB2528',
'primaryTextColor': '#fff',
'primaryBorderColor': '#7C0000',
'lineColor': '#F8B229',
'secondaryColor': '#006100',
'tertiaryColor': '#fff'
}
}
}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
@@ -126,7 +170,19 @@ The easiest way to make a custom theme is to start with the base theme, and just
```
```mermaid
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ff0000'}}}%%
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#BB2528',
'primaryTextColor': '#fff',
'primaryBorderColor': '#7C0000',
'lineColor': '#F8B229',
'secondaryColor': '#006100',
'tertiaryColor': '#fff'
}
}
}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
@@ -143,601 +199,93 @@ The easiest way to make a custom theme is to start with the base theme, and just
end
```
**Notes:**
Leaving it empty will set all variable values to default.
## Color and Color Calculation:
Color definitions have certain interactions in mermaid, this is in order to ensure visibility for diagrams. Mermaid will adjust some variables automatically, when colors are changed in order to compensate and maintain readability.
**The Default Value Column** to the right of the Variable column will denote the Variable paired/associated with the Variable on the left and the nature of this pairing or association. If it for instance says primaryColor it means that it gets primaryColor as default value. If it says "based on primaryColor" it means that it is calculated/ derived from primaryColor. This calculation can be primary color inversion, a change of hue, darkening or lightening by 10%, etc.
You can create your own themes, by changing any of the given variables below. If you are using a dark background, set dark mode to true to adjust the colors. It is possible to override the calculations using the variable names below, with `%%init%%` if you wish to style it differently.
## Theme Variables Reference Table
> **Note**
> Variables that are unique to some diagrams can be affected by changes in Theme Variables
| Variable | Default/Base/Factor value | Calc | Description |
| -------------------- | ------------------------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------- |
| darkMode | false | | Boolean Value that dictates how to calculate colors. "true" will activate darkmode. |
| background | #f4f4f4 | | Used to calculate color for items that should either be background colored or contrasting to the background. |
| fontFamily | "trebuchet ms", verdana, arial | | |
| fontSize | 16px | | Font Size, in pixels |
| primaryColor | #fff4dd | | Color to be used as background in nodes, other colors will be derived from this |
| primaryBorderColor | based on primaryColor | \* | Color to be used as border in nodes using primaryColor |
| primaryTextColor | based on darkMode #ddd/#333 | \* | Color to be used as text color in nodes using primaryColor |
| secondaryColor | based on primaryColor | \* | |
| secondaryBorderColor | based on secondaryColor | \* | Color to be used as border in nodes using secondaryColor |
| secondaryTextColor | based on secondaryColor | \* | Color to be used as text color in nodes using secondaryColor |
| tertiaryColor | based on primaryColor | \* | |
| tertiaryBorderColor | based on tertiaryColor | \* | Color to be used as border in nodes using tertiaryColor |
| tertiaryTextColor | based on tertiaryColor | \* | Color to be used as text color in nodes using tertiaryColor |
| noteBkgColor | #fff5ad | | Color used as background in notes |
| noteTextColor | #333 | | Text color in note rectangles. |
| noteBorderColor | based on noteBkgColor | \* | Border color in note rectangles. |
| lineColor | based on background | \* | |
| textColor | based on primaryTextColor | \* | Text in diagram over the background for instance text on labels and on signals in sequence diagram or the title in gantt diagram |
| mainBkg | based on primaryColor | \* | Background in flowchart objects like rects/circles, class diagram classes, sequence diagram etc |
| errorBkgColor | tertiaryColor | \* | Color for syntax error message |
| errorTextColor | tertiaryTextColor | \* | Color for syntax error message |
# What follows are Variables, specific to different diagrams and charts.
## Some Theme Variables serve as, or affect the Default Values for Specific Diagram Variables, unless changed using `%%init%%` .
## Flowchart
| Variable | Default/ Associated Value | Calc | Description |
| ------------------- | ------------------------- | ---- | ---------------------------- |
| nodeBorder | primaryBorderColor | \* | Node Border Color |
| clusterBkg | tertiaryColor | \* | Background in subgraphs |
| clusterBorder | tertiaryBorderColor | \* | Cluster Border Color |
| defaultLinkColor | lineColor | \* | Link Color |
| titleColor | tertiaryTextColor | \* | Title Color |
| edgeLabelBackground | based on secondaryColor | \* | |
| nodeTextColor | primaryTextColor | \* | Color for text inside Nodes. |
# sequence diagram
| name | Default value | Calc | Description |
| --------------------- | ----------------------- | ---- | --------------------------- |
| actorBorder | primaryBorderColor | \* | Actor Border Color |
| actorBkg | mainBkg | \* | Actor Background Color |
| actorTextColor | primaryTextColor | \* | Actor Text Color |
| actorLineColor | grey | \* | Actor Line Color |
| signalColor | textColor | \* | Signal Color |
| signalTextColor | textColor | \* | Signal Text Color |
| labelBoxBkgColor | actorBkg | \* | Label Box Background Color |
| labelBoxBorderColor | actorBorder | \* | Label Box Border Color |
| labelTextColor | actorTextColor | \* | Label Text Color |
| loopTextColor | actorTextColor | \* | Loop ext Color |
| activationBorderColor | based on secondaryColor | \* | Activation Border Color |
| activationBkgColor | secondaryColor | \* | Activation Background Color |
| sequenceNumberColor | based on lineColor | \* | Sequence Number Color |
# state colors
| name | Default value | Calc | Description |
| ------------- | ---------------- | ---- | -------------------------------------------- |
| labelColor | primaryTextColor | \* | |
| altBackground | tertiaryColor | \* | Used for background in deep composite states |
# class colors
| name | Default value | Calc | Description |
| --------- | ------------- | ---- | ------------------------------- |
| classText | textColor | \* | Color of Text in class diagrams |
# User journey colors
| name | Default value | Calc | Description |
| --------- | ----------------------- | ---- | --------------------------------------- |
| fillType0 | primaryColor | \* | Fill for 1st section in journey diagram |
| fillType1 | secondaryColor | \* | Fill for 2nd section in journey diagram |
| fillType2 | based on primaryColor | \* | Fill for 3rd section in journey diagram |
| fillType3 | based on secondaryColor | \* | Fill for 4th section in journey diagram |
| fillType4 | based on primaryColor | \* | Fill for 5th section in journey diagram |
| fillType5 | based on secondaryColor | \* | Fill for 6th section in journey diagram |
| fillType6 | based on primaryColor | \* | Fill for 7th section in journey diagram |
| fillType7 | based on secondaryColor | \* | Fill for 8th section in journey diagram |
\*\*Notes: Values are meant to create an alternating look.
# Here is an example of overriding `primaryColor` and giving everything a different look, using `%%init%%`.
```mermaid-example
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ff0000'}}}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[/Another/]
C ==>|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
```
```mermaid
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ff0000'}}}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[/Another/]
C ==>|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
```
\*\*This got a bit too dark and bit too colorful. With some easy steps this can be fixed:
- Make the primary color a little lighter
- set the tertiary color to a reddish shade as well
- make the edge label background differ from the subgraph by setting the edgeLabelBackground
```mermaid-example
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ffcccc', 'edgeLabelBackground':'#ffffee', 'tertiaryColor': '#fff0f0'}}}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[/Another/]
C ==>|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
```
```mermaid
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ffcccc', 'edgeLabelBackground':'#ffffee', 'tertiaryColor': '#fff0f0'}}}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[/Another/]
C ==>|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
```
The Theming Engine does not admit color codes and will only accept proper color values. Color Names is not supported so for instance, the color value 'red' will not work, but '#ff0000' will work.
# Common theming activities
## How to change the color of the arrows
# Examples:
When adjusting a theme it might be helpful to look at how your preferred theme goes with the diagrams, to evaluate whether everything is visible and looks good.
In the following examples, the directive `init` is used, with the `theme` being declared as `base`. For more information on using directives, read the documentation for [Version 8.6.0](/8.6.0_docs.md)
### Flowchart
```mermaid-example
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[/Another/]
C ==>|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
```
```mermaid
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[/Another/]
C ==>|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
```
### Flowchart (beta)
```mermaid-example
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
flowchart TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[Another]
C ==>|One| D[Laptop]
C x--x|Two| E[iPhone]
C o--o|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
```
```mermaid
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
flowchart TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[Another]
C ==>|One| D[Laptop]
C x--x|Two| E[iPhone]
C o--o|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
```
### Sequence diagram
```mermaid-example
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
sequenceDiagram
autonumber
par Action 1
Alice->>John: Hello John, how are you?
and Action 2
Alice->>Bob: Hello Bob, how are you?
end
Alice->>+John: Hello John, how are you?
Alice->>+John: John, can you hear me?
John-->>-Alice: Hi Alice, I can hear you!
Note right of John: John is perceptive
John-->>-Alice: I feel great!
loop Every minute
John-->Alice: Great!
end
```
```mermaid
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
sequenceDiagram
autonumber
par Action 1
Alice->>John: Hello John, how are you?
and Action 2
Alice->>Bob: Hello Bob, how are you?
end
Alice->>+John: Hello John, how are you?
Alice->>+John: John, can you hear me?
John-->>-Alice: Hi Alice, I can hear you!
Note right of John: John is perceptive
John-->>-Alice: I feel great!
loop Every minute
John-->Alice: Great!
end
```
### Class diagram
```mermaid-example
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
classDiagram
Animal "1" <|-- Duck
Animal <|-- Fish
Animal <--o Zebra
Animal : +int age
Animal : +String gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+String beakColor
+swim()
+quack()
}
class Fish{
-int sizeInFeet
-canEat()
}
class Zebra{
+bool is_wild
+run()
}
```
```mermaid
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
classDiagram
Animal "1" <|-- Duck
Animal <|-- Fish
Animal <--o Zebra
Animal : +int age
Animal : +String gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+String beakColor
+swim()
+quack()
}
class Fish{
-int sizeInFeet
-canEat()
}
class Zebra{
+bool is_wild
+run()
}
```
### Gantt
```mermaid-example
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
excludes :excludes the named dates/days from being included in a charted task..
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
Future task2 : des4, after des3, 5d
section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser and jison :crit, done, after des1, 2d
Create tests for parser :crit, active, 3d
Future task in critical line :crit, 5d
Create tests for renderer :2d
Add to mermaid :1d
section Documentation
Describe gantt syntax :active, a1, after des1, 3d
Add gantt diagram to demo page :after a1 , 20h
Add another diagram to demo page :doc1, after a1 , 48h
section Last section
Describe gantt syntax :after doc1, 3d
Add gantt diagram to demo page :20h
Add another diagram to demo page :48h
```
```mermaid
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
excludes :excludes the named dates/days from being included in a charted task..
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
Future task2 : des4, after des3, 5d
section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser and jison :crit, done, after des1, 2d
Create tests for parser :crit, active, 3d
Future task in critical line :crit, 5d
Create tests for renderer :2d
Add to mermaid :1d
section Documentation
Describe gantt syntax :active, a1, after des1, 3d
Add gantt diagram to demo page :after a1 , 20h
Add another diagram to demo page :doc1, after a1 , 48h
section Last section
Describe gantt syntax :after doc1, 3d
Add gantt diagram to demo page :20h
Add another diagram to demo page :48h
```
### State diagram
```mermaid-example
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
stateDiagram
[*] --> Active
state Active {
[*] --> NumLockOff
NumLockOff --> NumLockOn : EvNumLockPressed
NumLockOn --> NumLockOff : EvNumLockPressed
--
[*] --> CapsLockOff
CapsLockOff --> CapsLockOn : EvCapsLockPressed
CapsLockOn --> CapsLockOff : EvCapsLockPressed
--
[*] --> ScrollLockOff
ScrollLockOff --> ScrollLockOn : EvCapsLockPressed
ScrollLockOn --> ScrollLockOff : EvCapsLockPressed
}
state SomethingElse {
A --> B
B --> A
}
Active --> SomethingElse
note right of SomethingElse : This is the note to the right.
SomethingElse --> [*]
```
```mermaid
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
stateDiagram
[*] --> Active
state Active {
[*] --> NumLockOff
NumLockOff --> NumLockOn : EvNumLockPressed
NumLockOn --> NumLockOff : EvNumLockPressed
--
[*] --> CapsLockOff
CapsLockOff --> CapsLockOn : EvCapsLockPressed
CapsLockOn --> CapsLockOff : EvCapsLockPressed
--
[*] --> ScrollLockOff
ScrollLockOff --> ScrollLockOn : EvCapsLockPressed
ScrollLockOn --> ScrollLockOff : EvCapsLockPressed
}
state SomethingElse {
A --> B
B --> A
}
Active --> SomethingElse
note right of SomethingElse : This is the note to the right.
SomethingElse --> [*]
```
### State diagram (beta)
```mermaid-example
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
stateDiagram-v2
[*] --> Active
state Active {
[*] --> NumLockOff
NumLockOff --> NumLockOn : EvNumLockPressed
NumLockOn --> NumLockOff : EvNumLockPressed
--
[*] --> CapsLockOff
CapsLockOff --> CapsLockOn : EvCapsLockPressed
CapsLockOn --> CapsLockOff : EvCapsLockPressed
--
[*] --> ScrollLockOff
ScrollLockOff --> ScrollLockOn : EvCapsLockPressed
ScrollLockOn --> ScrollLockOff : EvCapsLockPressed
}
state SomethingElse {
A --> B
B --> A
}
Active --> SomethingElse2
note right of SomethingElse2 : This is the note to the right.
SomethingElse2 --> [*]
```
```mermaid
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
stateDiagram-v2
[*] --> Active
state Active {
[*] --> NumLockOff
NumLockOff --> NumLockOn : EvNumLockPressed
NumLockOn --> NumLockOff : EvNumLockPressed
--
[*] --> CapsLockOff
CapsLockOff --> CapsLockOn : EvCapsLockPressed
CapsLockOn --> CapsLockOff : EvCapsLockPressed
--
[*] --> ScrollLockOff
ScrollLockOff --> ScrollLockOn : EvCapsLockPressed
ScrollLockOn --> ScrollLockOff : EvCapsLockPressed
}
state SomethingElse {
A --> B
B --> A
}
Active --> SomethingElse2
note right of SomethingElse2 : This is the note to the right.
SomethingElse2 --> [*]
```
### Entity Relations diagram
```mermaid-example
erDiagram
CUSTOMER }|..|{ DELIVERY-ADDRESS : has
CUSTOMER ||--o{ ORDER : places
CUSTOMER ||--o{ INVOICE : "liable for"
DELIVERY-ADDRESS ||--o{ ORDER : receives
INVOICE ||--|{ ORDER : covers
ORDER ||--|{ ORDER-ITEM : includes
PRODUCT-CATEGORY ||--|{ PRODUCT : contains
PRODUCT ||--o{ ORDER-ITEM : "ordered in"
```
```mermaid
erDiagram
CUSTOMER }|..|{ DELIVERY-ADDRESS : has
CUSTOMER ||--o{ ORDER : places
CUSTOMER ||--o{ INVOICE : "liable for"
DELIVERY-ADDRESS ||--o{ ORDER : receives
INVOICE ||--|{ ORDER : covers
ORDER ||--|{ ORDER-ITEM : includes
PRODUCT-CATEGORY ||--|{ PRODUCT : contains
PRODUCT ||--o{ ORDER-ITEM : "ordered in"
```
### User journey diagram
```mermaid-example
journey
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 5: Me
```
```mermaid
journey
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 5: Me
```
## Color and Color Calculation
To ensure diagram readability, the default value of certain variables is calculated or derived from other variables. For example, `primaryBorderColor` is derived from the `primaryColor` variable. So if the `primaryColor` variable is customized, Mermaid will adjust `primaryBorderColor` automatically. Adjustments can mean a color inversion, a hue change, a darkening/lightening by 10%, etc.
The theming engine will only recognize hex colors and not color names. So, the value `#ff0000` will work, but `red` will not.
## Theme Variables
| Variable | Default value | Description |
| -------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| darkMode | false | Affects how derived colors are calculated. Set value to `true` for dark mode. |
| background | #f4f4f4 | Used to calculate color for items that should either be background colored or contrasting to the background |
| fontFamily | trebuchet ms, verdana, arial | |
| fontSize | 16px | Font size in pixels |
| primaryColor | #fff4dd | Color to be used as background in nodes, other colors will be derived from this |
| primaryBorderColor | calculated from primaryColor | Color to be used as border in nodes using `primaryColor` |
| primaryBorderColor | calculated from primaryColor | Color to be used as border in nodes using `primaryColor` |
| primaryTextColor | calculated from darkMode #ddd/#333 | Color to be used as text color in nodes using `primaryColor` |
| secondaryColor | calculated from primaryColor | |
| primaryBorderColor | calculated from primaryColor | Color to be used as border in nodes using `primaryColor` |
| secondaryBorderColor | calculated from secondaryColor | Color to be used as border in nodes using `secondaryColor` |
| primaryBorderColor | calculated from primaryColor | Color to be used as border in nodes using `primaryColor` |
| secondaryTextColor | calculated from secondaryColor | Color to be used as text color in nodes using `secondaryColor` |
| tertiaryColor | calculated from primaryColor | |
| tertiaryBorderColor | calculated from tertiaryColor | Color to be used as border in nodes using `tertiaryColor` |
| tertiaryTextColor | calculated from tertiaryColor | Color to be used as text color in nodes using `tertiaryColor` |
| noteBkgColor | #fff5ad | Color used as background in notes |
| noteTextColor | #333 | Text color in note rectangles |
| noteBorderColor | calculated from noteBkgColor | Border color in note rectangles |
| lineColor | calculated from background | |
| textColor | calculated from primaryTextColor | Text in diagram over the background for instance text on labels and on signals in sequence diagram or the title in Gantt diagram |
| mainBkg | calculated from primaryColor | Background in flowchart objects like rects/circles, class diagram classes, sequence diagram etc |
| errorBkgColor | tertiaryColor | Color for syntax error message |
| errorTextColor | tertiaryTextColor | Color for syntax error message |
## Flowchart Variables
| Variable | Default value | Description |
| ------------------- | ------------------------------ | --------------------------- |
| nodeBorder | primaryBorderColor | Node Border Color |
| clusterBkg | tertiaryColor | Background in subgraphs |
| clusterBorder | tertiaryBorderColor | Cluster Border Color |
| defaultLinkColor | lineColor | Link Color |
| titleColor | tertiaryTextColor | Title Color |
| edgeLabelBackground | calculated from secondaryColor | |
| nodeTextColor | primaryTextColor | Color for text inside Nodes |
## Sequence Diagram Variables
| Variable | Default value | Description |
| --------------------- | ------------------------------ | --------------------------- |
| actorBkg | mainBkg | Actor Background Color |
| actorBorder | primaryBorderColor | Actor Border Color |
| actorTextColor | primaryTextColor | Actor Text Color |
| actorLineColor | grey | Actor Line Color |
| signalColor | textColor | Signal Color |
| signalTextColor | textColor | Signal Text Color |
| labelBoxBkgColor | actorBkg | Label Box Background Color |
| labelBoxBorderColor | actorBorder | Label Box Border Color |
| labelTextColor | actorTextColor | Label Text Color |
| loopTextColor | actorTextColor | Loop Text Color |
| activationBorderColor | calculated from secondaryColor | Activation Border Color |
| activationBkgColor | secondaryColor | Activation Background Color |
| sequenceNumberColor | calculated from lineColor | Sequence Number Color |
## State Colors
| Variable | Default value | Description |
| ------------- | ---------------- | -------------------------------------------- |
| labelColor | primaryTextColor | |
| altBackground | tertiaryColor | Used for background in deep composite states |
## Class Colors
| Variable | Default value | Description |
| --------- | ------------- | ------------------------------- |
| classText | textColor | Color of Text in class diagrams |
## User Journey Colors
| Variable | Default value | Description |
| --------- | ------------------------------ | --------------------------------------- |
| fillType0 | primaryColor | Fill for 1st section in journey diagram |
| fillType1 | secondaryColor | Fill for 2nd section in journey diagram |
| fillType2 | calculated from primaryColor | Fill for 3rd section in journey diagram |
| fillType3 | calculated from secondaryColor | Fill for 4th section in journey diagram |
| fillType4 | calculated from primaryColor | Fill for 5th section in journey diagram |
| fillType5 | calculated from secondaryColor | Fill for 6th section in journey diagram |
| fillType6 | calculated from primaryColor | Fill for 7th section in journey diagram |
| fillType7 | calculated from secondaryColor | Fill for 8th section in journey diagram |

23
docs/config/usage.md
View File

@@ -22,24 +22,21 @@ For the majority of users, Using the [Live Editor](https://mermaid.live/) would
We have compiled some Video [Tutorials](./Tutorials.md) on how to use the mermaid Live Editor.
**Installing and Hosting Mermaid on a Webpage**
### Installing and Hosting Mermaid on a Webpage
**Using the npm package**
**Using the npm package:**
1. You will need to install node v16, which would have npm.
1. You will need to install `node v16`, which would have npm.
2. download yarn using npm.
2. Download `yarn` using npm.
3. enter the following command:
yarn add mermaid
3. Enter the following command: `yarn add mermaid`.
4. At this point, you can add mermaid as a dev dependency using this command:
yarn add --dev mermaid
4. At this point, you can add mermaid as a dev dependency using this command: `yarn add --dev mermaid`.
5. Alternatively, you can also deploy mermaid using the script tag in an HTML file with mermaid diagram descriptions.
as is shown in the example below
5. Alternatively, you can also deploy mermaid using the script tag in an HTML file with mermaid diagram descriptions as is shown in the example below.
**Hosting mermaid on a web page.**
**Hosting mermaid on a web page:**
> Note:This topic explored in greater depth in the [User Guide for Beginners](../intro/n00b-gettingStarted.md)
@@ -62,7 +59,7 @@ Example:
```html
<script type="module">
import mermaid from 'https://unpkg.com/mermaid@9/dist/mermaid.esm.min.mjs';
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
```
@@ -85,7 +82,7 @@ Example:
B-->D(fa:fa-spinner);
</pre>
<script type="module">
import mermaid from 'https://unpkg.com/mermaid@9/dist/mermaid.esm.min.mjs';
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</body>

2
docs/intro/index.md
View File

@@ -267,7 +267,7 @@ To Deploy Mermaid:
```html
<script type="module">
import mermaid from 'https://unpkg.com/mermaid@9/dist/mermaid.esm.min.mjs';
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
```

8
docs/intro/n00b-gettingStarted.md
View File

@@ -128,7 +128,7 @@ b. The importing of mermaid library through the `mermaid.esm.js` or `mermaid.esm
```html
<body>
<script type="module">
import mermaid from 'https://unpkg.com/mermaid@9/dist/mermaid.esm.min.mjs';
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</body>
@@ -143,6 +143,10 @@ Rendering in Mermaid is initialized by `mermaid.initialize()` call. You can plac
| ----------- | --------------------------------- | ------- | ----------- |
| startOnLoad | Toggle for Rendering upon loading | Boolean | true, false |
### Adding external diagrams to mermaid
Please refer to the [Mindmap](../syntax/mindmap.md?id=integrating-with-your-librarywebsite) section for more information.
### Working Examples
**Here is a full working example of the mermaidAPI being called through the CDN:**
@@ -168,7 +172,7 @@ Rendering in Mermaid is initialized by `mermaid.initialize()` call. You can plac
</pre>
<script type="module">
import mermaid from 'https://unpkg.com/mermaid@9/dist/mermaid.esm.min.mjs';
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</body>

9
docs/misc/integrations.md
View File

@@ -21,6 +21,7 @@ They also serve as proof of concept, for the variety of things that can be built
- [Azure Devops](https://docs.microsoft.com/en-us/azure/devops/project/wiki/wiki-markdown-guidance?view=azure-devops#add-mermaid-diagrams-to-a-wiki-page) (**Native support**)
- [Tuleap](https://docs.tuleap.org/user-guide/writing-in-tuleap.html#graphs) (**Native support**)
- [Joplin](https://joplinapp.org) (**Native support**)
- [Swimm](https://swimm.io) (**Native support**)
- [Notion](https://notion.so) (**Native support**)
- [Observable](https://observablehq.com/@observablehq/mermaid) (**Native support**)
- [Obsidian](https://help.obsidian.md/How+to/Format+your+notes#Diagram) (**Native support**)
@@ -109,10 +110,10 @@ They also serve as proof of concept, for the variety of things that can be built
- [md-it-mermaid](https://github.com/iamcco/md-it-mermaid)
- [markdown-it-mermaid-fence-new](https://github.com/Revomatico/markdown-it-mermaid-fence-new)
- [markdown-it-mermaid-less](https://github.com/searKing/markdown-it-mermaid-less)
- [Atom](https://atom.io)
- [Markdown Preview Enhanced](https://atom.io/packages/markdown-preview-enhanced)
- [Atom Mermaid](https://atom.io/packages/atom-mermaid)
- [Language Mermaid Syntax Highlighter](https://atom.io/packages/language-mermaid)
- Atom _(Atom has been [archived.](https://github.blog/2022-06-08-sunsetting-atom/))_
- [Markdown Preview Enhanced](https://github.com/shd101wyy/markdown-preview-enhanced)
- [Atom Mermaid](https://github.com/y-takey/atom-mermaid)
- [Language Mermaid Syntax Highlighter](https://github.com/ytisf/language-mermaid)
- [Sublime Text 3](https://sublimetext.com)
- [Mermaid Package](https://packagecontrol.io/packages/Mermaid)
- [Astah](https://astah.net)

13
docs/syntax/classDiagram.md
View File

@@ -7,7 +7,8 @@
# Class diagrams
> "In software engineering, a class diagram in the Unified Modeling Language (UML) is a type of static structure diagram that describes the structure of a system by showing the system's classes, their attributes, operations (or methods), and the relationships among objects."
> Wikipedia
>
> \-Wikipedia
The class diagram is the main building block of object-oriented modeling. It is used for general conceptual modeling of the structure of the application, and for detailed modeling to translate the models into programming code. Class diagrams can also be used for data modeling. The classes in a class diagram represent both the main elements, interactions in the application, and the classes to be programmed.
@@ -205,7 +206,7 @@ class BankAccount{
#### Generic Types
Members can be defined using generic types, such as `List<int>`, for fields, parameters, and return types by enclosing the type within `~` (**tilde**). Note: **nested** type declarations such as `List<List<int>>` are not currently supported.
Members can be defined using generic types, such as `List<int>`, for fields, parameters, and return types by enclosing the type within `~` (**tilde**). **Nested** type declarations such as `List<List<int>>` are supported.
Generics can be represented as part of a class definition and also in the parameters or the return value of a method/function:
@@ -221,6 +222,7 @@ class Square~Shape~{
Square : -List~string~ messages
Square : +setMessages(List~string~ messages)
Square : +getMessages() List~string~
Square : +getDistanceMatrix() List~List~int~~
```
```mermaid
@@ -235,12 +237,9 @@ class Square~Shape~{
Square : -List~string~ messages
Square : +setMessages(List~string~ messages)
Square : +getMessages() List~string~
Square : +getDistanceMatrix() List~List~int~~
```
#### Return Type
Optionally you can end the method/function definition with the data type that will be returned.
#### Visibility
To describe the visibility (or encapsulation) of an attribute or method/function that is a part of a class (i.e. a class member), optional notation may be placed before that members' name:
@@ -270,7 +269,7 @@ There are eight different types of relations defined for classes under UML which
| Type | Description |
| ------- | ------------- |
| `<\|--` | Inheritance |
| `\*--` | Composition |
| `*--` | Composition |
| `o--` | Aggregation |
| `-->` | Association |
| `--` | Link (Solid) |

50
docs/syntax/entityRelationshipDiagram.md
View File

@@ -162,7 +162,7 @@ erDiagram
### Attributes
Attributes can be defined for entities by specifying the entity name followed by a block containing multiple `type name` pairs, where a block is delimited by an opening `{` and a closing `}`. For example:
Attributes can be defined for entities by specifying the entity name followed by a block containing multiple `type name` pairs, where a block is delimited by an opening `{` and a closing `}`. The attributes are rendered inside the entity boxes. For example:
```mermaid-example
erDiagram
@@ -196,59 +196,26 @@ erDiagram
}
```
The attributes are rendered inside the entity boxes:
```mermaid-example
erDiagram
CAR ||--o{ NAMED-DRIVER : allows
CAR {
string registrationNumber
string make
string model
}
PERSON ||--o{ NAMED-DRIVER : is
PERSON {
string firstName
string lastName
int age
}
```
```mermaid
erDiagram
CAR ||--o{ NAMED-DRIVER : allows
CAR {
string registrationNumber
string make
string model
}
PERSON ||--o{ NAMED-DRIVER : is
PERSON {
string firstName
string lastName
int age
}
```
The `type` and `name` values must begin with an alphabetic character and may contain digits, hyphens or underscores. Other than that, there are no restrictions, and there is no implicit set of valid data types.
The `type` and `name` values must begin with an alphabetic character and may contain digits, hyphens, underscores, parentheses and square brackets. Other than that, there are no restrictions, and there is no implicit set of valid data types.
#### Attribute Keys and Comments
Attributes may also have a `key` or comment defined. Keys can be "PK" or "FK", for Primary Key or Foreign Key. And a `comment` is defined by double quotes at the end of an attribute. Comments themselves cannot have double-quote characters in them.
Attributes may also have a `key` or comment defined. Keys can be "PK", "FK" or "UK", for Primary Key, Foreign Key or Unique Key. And a `comment` is defined by double quotes at the end of an attribute. Comments themselves cannot have double-quote characters in them.
```mermaid-example
erDiagram
CAR ||--o{ NAMED-DRIVER : allows
CAR {
string allowedDriver FK "The license of the allowed driver"
string registrationNumber
string registrationNumber UK
string make
string model
string[] parts
}
PERSON ||--o{ NAMED-DRIVER : is
PERSON {
string driversLicense PK "The license #"
string firstName
string(99) firstName "Only 99 characters are allowed"
string lastName
int age
}
@@ -260,14 +227,15 @@ erDiagram
CAR ||--o{ NAMED-DRIVER : allows
CAR {
string allowedDriver FK "The license of the allowed driver"
string registrationNumber
string registrationNumber UK
string make
string model
string[] parts
}
PERSON ||--o{ NAMED-DRIVER : is
PERSON {
string driversLicense PK "The license #"
string firstName
string(99) firstName "Only 99 characters are allowed"
string lastName
int age
}

107
docs/syntax/gantt.md
View File

@@ -172,30 +172,33 @@ Final milestone : milestone, m2, 18:14, 2min
The default input date format is `YYYY-MM-DD`. You can define your custom `dateFormat`.
dateFormat YYYY-MM-DD
```markdown
dateFormat YYYY-MM-DD
```
The following formatting options are supported:
Input Example Description:
YYYY 2014 4 digit year
YY 14 2 digit year
Q 1..4 Quarter of year. Sets month to first month in quarter.
M MM 1..12 Month number
MMM MMMM January..Dec Month name in locale set by moment.locale()
D DD 1..31 Day of month
Do 1st..31st Day of month with ordinal
DDD DDDD 1..365 Day of year
X 1410715640.579 Unix timestamp
x 1410715640579 Unix ms timestamp
H HH 0..23 24 hour time
h hh 1..12 12 hour time used with a A.
a A am pm Post or ante meridiem
m mm 0..59 Minutes
s ss 0..59 Seconds
S 0..9 Tenths of a second
SS 0..99 Hundreds of a second
SSS 0..999 Thousandths of a second
Z ZZ +12:00 Offset from UTC as +-HH:mm, +-HHmm, or Z
| Input | Example | Description |
| ---------- | -------------- | ------------------------------------------------------ |
| `YYYY` | 2014 | 4 digit year |
| `YY` | 14 | 2 digit year |
| `Q` | 1..4 | Quarter of year. Sets month to first month in quarter. |
| `M MM` | 1..12 | Month number |
| `MMM MMMM` | January..Dec | Month name in locale set by `moment.locale()` |
| `D DD` | 1..31 | Day of month |
| `Do` | 1st..31st | Day of month with ordinal |
| `DDD DDDD` | 1..365 | Day of year |
| `X` | 1410715640.579 | Unix timestamp |
| `x` | 1410715640579 | Unix ms timestamp |
| `H HH` | 0..23 | 24 hour time |
| `h hh` | 1..12 | 12 hour time used with `a A`. |
| `a A` | am pm | Post or ante meridiem |
| `m mm` | 0..59 | Minutes |
| `s ss` | 0..59 | Seconds |
| `S` | 0..9 | Tenths of a second |
| `SS` | 0..99 | Hundreds of a second |
| `SSS` | 0..999 | Thousandths of a second |
| `Z ZZ` | +12:00 | Offset from UTC as +-HH:mm, +-HHmm, or Z |
More info in: https://momentjs.com/docs/#/parsing/string-format/
@@ -203,34 +206,38 @@ More info in: https://momentjs.com/docs/#/parsing/string-format/
The default output date format is `YYYY-MM-DD`. You can define your custom `axisFormat`, like `2020-Q1` for the first quarter of the year 2020.
axisFormat %Y-%m-%d
```markdown
axisFormat %Y-%m-%d
```
The following formatting strings are supported:
%a - abbreviated weekday name.
%A - full weekday name.
%b - abbreviated month name.
%B - full month name.
%c - date and time, as "%a %b %e %H:%M:%S %Y".
%d - zero-padded day of the month as a decimal number [01,31].
%e - space-padded day of the month as a decimal number [ 1,31]; equivalent to %_d.
%H - hour (24-hour clock) as a decimal number [00,23].
%I - hour (12-hour clock) as a decimal number [01,12].
%j - day of the year as a decimal number [001,366].
%m - month as a decimal number [01,12].
%M - minute as a decimal number [00,59].
%L - milliseconds as a decimal number [000, 999].
%p - either AM or PM.
%S - second as a decimal number [00,61].
%U - week number of the year (Sunday as the first day of the week) as a decimal number [00,53].
%w - weekday as a decimal number [0(Sunday),6].
%W - week number of the year (Monday as the first day of the week) as a decimal number [00,53].
%x - date, as "%m/%d/%Y".
%X - time, as "%H:%M:%S".
%y - year without century as a decimal number [00,99].
%Y - year with century as a decimal number.
%Z - time zone offset, such as "-0700".
%% - a literal "%" character.
| Format | Definition |
| ------ | ------------------------------------------------------------------------------------------ |
| %a | abbreviated weekday name |
| %A | full weekday name |
| %b | abbreviated month name |
| %B | full month name |
| %c | date and time, as "%a %b %e %H:%M:%S %Y" |
| %d | zero-padded day of the month as a decimal number \[01,31] |
| %e | space-padded day of the month as a decimal number \[ 1,31]; equivalent to %\_d |
| %H | hour (24-hour clock) as a decimal number \[00,23] |
| %I | hour (12-hour clock) as a decimal number \[01,12] |
| %j | day of the year as a decimal number \[001,366] |
| %m | month as a decimal number \[01,12] |
| %M | minute as a decimal number \[00,59] |
| %L | milliseconds as a decimal number \[000, 999] |
| %p | either AM or PM |
| %S | second as a decimal number \[00,61] |
| %U | week number of the year (Sunday as the first day of the week) as a decimal number \[00,53] |
| %w | weekday as a decimal number \[0(Sunday),6] |
| %W | week number of the year (Monday as the first day of the week) as a decimal number \[00,53] |
| %x | date, as "%m/%d/%Y" |
| %X | time, as "%H:%M:%S" |
| %y | year without century as a decimal number \[00,99] |
| %Y | year with century as a decimal number |
| %Z | time zone offset, such as "-0700" |
| %% | a literal "%" character |
More info in: <https://github.com/d3/d3-time-format/tree/v4.0.0#locale_format>
@@ -238,11 +245,15 @@ More info in: <https://github.com/d3/d3-time-format/tree/v4.0.0#locale_format>
The default output ticks are auto. You can custom your `tickInterval`, like `1day` or `1week`.
tickInterval 1day
```markdown
tickInterval 1day
```
The pattern is:
/^([1-9][0-9]*)(minute|hour|day|week|month)$/
```javascript
/^([1-9][0-9]*)(minute|hour|day|week|month)$/;
```
More info in: <https://github.com/d3/d3-time#interval_every>

16
docs/syntax/mindmap.md
View File

@@ -180,7 +180,7 @@ More shapes will be added, beginning with the shapes available in flowcharts.
# Icons and classes
## icons
## Icons
As with flowcharts you can add icons to your nodes but with an updated syntax. The styling for the font based icons are added during the integration so that they are available for the web page. _This is not something a diagram author can do but has to be done with the site administrator or the integrator_. Once the icon fonts are in place you add them to the mind map nodes using the `::icon()` syntax. You place the classes for the icon within the parenthesis like in the following example where icons for material design and fontawesome 4 are displayed. The intention is that this approach should be used for all diagrams supporting icons. **Experimental feature:** This wider scope is also the reason Mindmaps are experimental as this syntax and approach could change.
@@ -253,3 +253,17 @@ Root
B
C
```
## Integrating with your library/website.
Mindmap uses the experimental lazy loading & async rendering features which could change in the future.
```html
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.esm.min.mjs';
import mindmap from 'https://cdn.jsdelivr.net/npm/@mermaid-js/mermaid-mindmap@9/dist/mermaid-mindmap.esm.min.mjs';
await mermaid.registerExternalDiagrams([mindmap]);
</script>
```
You can also refer the implementation in the live editor [here](https://github.com/mermaid-js/mermaid-live-editor/blob/fcf53c98c25604c90a218104268c339be53035a6/src/lib/util/mermaid.ts) to see how the async loading is done.

14
docs/syntax/sequenceDiagram.md
View File

@@ -198,6 +198,20 @@ sequenceDiagram
Note over Alice,John: A typical interaction
```
It is also possible to add a line break (applies to text input in general):
```mermaid-example
sequenceDiagram
Alice->John: Hello John, how are you?
Note over Alice,John: A typical interaction<br/>But now in two lines
```
```mermaid
sequenceDiagram
Alice->John: Hello John, how are you?
Note over Alice,John: A typical interaction<br/>But now in two lines
```
## Loops
It is possible to express loops in a sequence diagram. This is done by the notation