Merge branch 'develop' into feature/3250/add_vertline_to_gantt_plot

2025-08-15 06:19:24 +02:00 · 2025-04-17 12:21:17 -04:00
parent 62b4228df4 a3fed10d55
commit e49911e748
15 changed files with 535 additions and 343 deletions
--- a/packages/mermaid/src/docs/config/8.6.0_docs.md
+++ b/packages/mermaid/src/docs/config/8.6.0_docs.md
@@ -75,7 +75,7 @@ When deployed within code, init is called before the graph/diagram description.

 **for example**:

-```mermaid
+```mermaid-example
 %%{init: {"theme": "default", "logLevel": 1 }}%%
 graph LR
  a-->b
--- a/packages/mermaid/src/docs/config/directives.md
+++ b/packages/mermaid/src/docs/config/directives.md
@@ -88,7 +88,7 @@ Here the directive declaration will set the `logLevel` to `debug` and the `theme

 Note: You can use 'init' or 'initialize' as both are acceptable as init directives. Also note that `%%init%%` and `%%initialize%%` directives will be grouped together after they are parsed.

-```mermaid
+```mermaid-example
 %%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
 %%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%
 ...
--- a/packages/mermaid/src/docs/config/math.md
+++ b/packages/mermaid/src/docs/config/math.md
@@ -10,7 +10,7 @@ Note that at the moment, the only supported diagrams are below:

 ### Flowcharts

-```mermaid
+```mermaid-example
 graph LR
      A["$$x^2$$"] -->|"$$\sqrt{x+3}$$"| B("$$\frac{1}{2}$$")
      A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\pi r^2$$")
@@ -20,7 +20,7 @@ Note that at the moment, the only supported diagrams are below:

 ### Sequence

-```mermaid
+```mermaid-example
 sequenceDiagram
    autonumber
    participant 1 as $$\alpha$$
--- a/packages/mermaid/src/docs/config/theming.md
+++ b/packages/mermaid/src/docs/config/theming.md
@@ -41,12 +41,6 @@ Example of `init` directive setting the `theme` to `forest`:
    a --> b
 ```

-```mermaid
-%%{init: {'theme':'forest'}}%%
-  graph TD
-    a --> b
-```
-
 > **Reminder**: the only theme that can be customized is the `base` theme. The following section covers how to use `themeVariables` for customizations.

 ## Customizing Themes with `themeVariables`
@@ -91,36 +85,6 @@ Example of modifying `themeVariables` using the `init` directive:
          end
 ```

-```mermaid
-%%{
-  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}
-          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
-```
-
 ## 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.
--- a/packages/mermaid/src/docs/intro/getting-started.md
+++ b/packages/mermaid/src/docs/intro/getting-started.md
@@ -41,7 +41,7 @@ In the `Code` panel, write or edit Mermaid code, and instantly `Preview` the ren

 Here is an example of Mermaid code and its rendered result:

-```mermaid
+```mermaid-example
 graph TD
    A[Enter Chart Definition] --> B(Preview)
    B --> C{decide}
--- a/packages/mermaid/src/docs/intro/syntax-reference.md
+++ b/packages/mermaid/src/docs/intro/syntax-reference.md
@@ -83,7 +83,7 @@ Mermaid offers a variety of styles or “looks” for your diagrams, allowing yo

 You can select a look by adding the look parameter in the metadata section of your Mermaid diagram code. Here’s an example:

-```mermaid
+```mermaid-example
 ---
 config:
  look: handDrawn
@@ -108,7 +108,7 @@ In addition to customizing the look of your diagrams, Mermaid Chart now allows y

 You can specify the layout algorithm directly in the metadata section of your Mermaid diagram code. Here’s an example:

-```mermaid
+```mermaid-example
 ---
 config:
  layout: elk
--- a/packages/mermaid/src/docs/syntax/block.md
+++ b/packages/mermaid/src/docs/syntax/block.md
@@ -7,7 +7,7 @@ outline: 'deep' # shows all h3 headings in outline in Vitepress

 ## Introduction to Block Diagrams

-```mermaid
+```mermaid-example
 block-beta
 columns 1
  db(("DB"))
--- a/packages/mermaid/src/docs/syntax/classDiagram.md
+++ b/packages/mermaid/src/docs/syntax/classDiagram.md
@@ -248,7 +248,7 @@ classE o-- classF : aggregation

 Relations can logically represent an N:M association:

-```mermaid
+```mermaid-example
 classDiagram
    Animal <|--|> Zebra
 ```
--- a/packages/mermaid/src/docs/syntax/examples.md
+++ b/packages/mermaid/src/docs/syntax/examples.md
@@ -141,7 +141,7 @@ sequenceDiagram

 ## A commit flow diagram.

-```mermaid
+```mermaid-example
 gitGraph:
    commit "Ashish"
    branch newbranch
--- a/packages/mermaid/src/docs/syntax/gantt.md
+++ b/packages/mermaid/src/docs/syntax/gantt.md
@@ -273,7 +273,7 @@ gantt

 The compact mode allows you to display multiple tasks in the same row. Compact mode can be enabled for a gantt chart by setting the display mode of the graph via preceding YAML settings.

-```mermaid
+```mermaid-example
 ---
 displayMode: compact
 ---
--- a/packages/mermaid/src/docs/syntax/gitgraph.md
+++ b/packages/mermaid/src/docs/syntax/gitgraph.md
@@ -290,7 +290,13 @@ Sometimes you may want to hide the branch names and lines from the diagram. You
 Usage example:

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': false}} }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: false
+---
      gitGraph
        commit
        branch hotfix
@@ -346,7 +352,13 @@ You can change the layout of the commit labels by using the `rotateCommitLabel`
 Usage example: Rotated commit labels

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}} }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    rotateCommitLabel: true
+---
 gitGraph
  commit id: "feat(api): ..."
  commit id: "a"
@@ -367,7 +379,13 @@ gitGraph
 Usage example: Horizontal commit labels

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': false}} }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    rotateCommitLabel: false
+---
 gitGraph
  commit id: "feat(api): ..."
  commit id: "a"
@@ -392,7 +410,14 @@ Sometimes you may want to hide the commit labels from the diagram. You can do th
 Usage example:

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': false,'showCommitLabel': false}} }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: false
+    showCommitLabel: false
+---
      gitGraph
        commit
        branch hotfix
@@ -444,7 +469,15 @@ Sometimes you may want to customize the name of the main/default branch. You can
 Usage example:

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'MetroLine1'}} }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: true
+    showCommitLabel: true
+    mainBranchName: 'MetroLine1'
+---
      gitGraph
        commit id:"NewYork"
        commit id:"Dallas"
@@ -486,7 +519,14 @@ To fully control the order of all the branches, you must define `order` for all
 Usage example:

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true}} }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: true
+    showCommitLabel: true
+---
      gitGraph
      commit
      branch test1 order: 3
@@ -500,7 +540,15 @@ Look at the diagram, all the branches are following the order defined.
 Usage example:

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchOrder': 2}} }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: true
+    showCommitLabel: true
+    mainBranchOrder: 2
+---
      gitGraph
      commit
      branch test1 order: 3
@@ -652,7 +700,11 @@ Let's put them to use, and see how our sample diagram looks in different themes:
 ### Base Theme

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+---
      gitGraph
        commit
        branch hotfix
@@ -700,7 +752,11 @@ Let's put them to use, and see how our sample diagram looks in different themes:
 ### Forest Theme

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'forest'
+---
      gitGraph
        commit
        branch hotfix
@@ -748,7 +804,11 @@ Let's put them to use, and see how our sample diagram looks in different themes:
 ### Default Theme

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'default' } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+---
      gitGraph
        commit type:HIGHLIGHT
        branch hotfix
@@ -796,7 +856,11 @@ Let's put them to use, and see how our sample diagram looks in different themes:
 ### Dark Theme

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'dark'
+---
      gitGraph
        commit
        branch hotfix
@@ -844,7 +908,11 @@ Let's put them to use, and see how our sample diagram looks in different themes:
 ### Neutral Theme

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'neutral' } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'neutral'
+---
      gitGraph
        commit
        branch hotfix
@@ -898,7 +966,11 @@ For understanding let us take a sample diagram with theme `default`, the default
 See how the default theme is used to set the colors for the branches:

 ```mermaid-example
-%%{init: { 'logLevel': 'debug', 'theme': 'default' } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+---
       gitGraph
       commit
       branch develop
@@ -929,16 +1001,20 @@ Example:
 Now let's override the default values for the `git0` to `git3` variables:

 ```mermaid-example
-    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
-              'git0': '#ff0000',
-              'git1': '#00ff00',
-              'git2': '#0000ff',
-              'git3': '#ff00ff',
-              'git4': '#00ffff',
-              'git5': '#ffff00',
-              'git6': '#ff00ff',
-              'git7': '#00ffff'
-       } } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+  themeVariables:
+      'git0': '#ff0000'
+      'git1': '#00ff00'
+      'git2': '#0000ff'
+      'git3': '#ff00ff'
+      'git4': '#00ffff'
+      'git5': '#ffff00'
+      'git6': '#ff00ff'
+      'git7': '#00ffff'
+---
       gitGraph
       commit
       branch develop
@@ -965,18 +1041,22 @@ Lets see how the default theme is used to set the colors for the branch labels:
 Now let's override the default values for the `gitBranchLabel0` to `gitBranchLabel2` variables:

 ```mermaid-example
-    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
-        'gitBranchLabel0': '#ffffff',
-        'gitBranchLabel1': '#ffffff',
-        'gitBranchLabel2': '#ffffff',
-        'gitBranchLabel3': '#ffffff',
-        'gitBranchLabel4': '#ffffff',
-        'gitBranchLabel5': '#ffffff',
-        'gitBranchLabel6': '#ffffff',
-        'gitBranchLabel7': '#ffffff',
-        'gitBranchLabel8': '#ffffff',
-        'gitBranchLabel9': '#ffffff'
-  } } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+  themeVariables:
+    'gitBranchLabel0': '#ffffff'
+    'gitBranchLabel1': '#ffffff'
+    'gitBranchLabel2': '#ffffff'
+    'gitBranchLabel3': '#ffffff'
+    'gitBranchLabel4': '#ffffff'
+    'gitBranchLabel5': '#ffffff'
+    'gitBranchLabel6': '#ffffff'
+    'gitBranchLabel7': '#ffffff'
+    'gitBranchLabel8': '#ffffff'
+    'gitBranchLabel9': '#ffffff'
+---
  gitGraph
    checkout main
    branch branch1
@@ -1002,10 +1082,14 @@ Example:
 Now let's override the default values for the `commitLabelColor` to `commitLabelBackground` variables:

 ```mermaid-example
-    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
-              'commitLabelColor': '#ff0000',
-              'commitLabelBackground': '#00ff00'
-       } } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+  themeVariables:
+    commitLabelColor: '#ff0000'
+    commitLabelBackground: '#00ff00'
+---
       gitGraph
       commit
       branch develop
@@ -1031,11 +1115,15 @@ Example:
 Now let's override the default values for the `commitLabelFontSize` variable:

 ```mermaid-example
-    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
-              'commitLabelColor': '#ff0000',
-              'commitLabelBackground': '#00ff00',
-              'commitLabelFontSize': '16px'
-       } } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+  themeVariables:
+    commitLabelColor: '#ff0000'
+    commitLabelBackground: '#00ff00'
+    commitLabelFontSize: '16px'
+---
       gitGraph
       commit
       branch develop
@@ -1061,11 +1149,15 @@ Example:
 Now let's override the default values for the `tagLabelFontSize` variable:

 ```mermaid-example
-    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
-              'commitLabelColor': '#ff0000',
-              'commitLabelBackground': '#00ff00',
-              'tagLabelFontSize': '16px'
-       } } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+  themeVariables:
+    commitLabelColor: '#ff0000'
+    commitLabelBackground: '#00ff00'
+    tagLabelFontSize: '16px'
+---
       gitGraph
       commit
       branch develop
@@ -1090,11 +1182,15 @@ Example:
 Now let's override the default values for the `tagLabelColor`, `tagLabelBackground` and to `tagLabelBorder` variables:

 ```mermaid-example
-    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
-              'tagLabelColor': '#ff0000',
-              'tagLabelBackground': '#00ff00',
-              'tagLabelBorder': '#0000ff'
-       } } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+  themeVariables:
+    tagLabelColor: '#ff0000'
+    tagLabelBackground: '#00ff00'
+    tagLabelBorder: '#0000ff'
+---
       gitGraph
       commit
       branch develop
@@ -1121,9 +1217,13 @@ Example:
 Now let's override the default values for the `git0` to `git3` variables:

 ```mermaid-example
-    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
-              'gitInv0': '#ff0000'
-       } } }%%
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+  themeVariables:
+    'gitInv0': '#ff0000'
+---
       gitGraph
       commit
       branch develop
--- a/packages/mermaid/src/docs/syntax/sequenceDiagram.md
+++ b/packages/mermaid/src/docs/syntax/sequenceDiagram.md
@@ -442,7 +442,7 @@ sequenceDiagram

 Comments can be entered within a sequence diagram, which will be ignored by the parser. Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax

-```mermaid
+```mermaid-example
 sequenceDiagram
    Alice->>John: Hello John, how are you?
    %% this is a comment