Merge branch 'develop' into 3358-blocks-diagram

docs/syntax/block-old.md

@@ -0,0 +1,526 @@
+> **Warning**
+>
+> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
+>
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/block-old.md](../../packages/mermaid/src/docs/syntax/block-old.md).
+
+# Block Diagrams - Basic Syntax
+
+Block diagrams are a fundamental tool in technical and engineering documentation, offering a straightforward way to represent complex systems and processes.
+
+A block diagram, at its core, is a graphical representation of a system that uses blocks to depict different components or functions and arrows to show the relationship or flow between them. This form of diagram is invaluable in simplifying the understanding of large-scale systems, breaking them down into individual, easily digestible components.
+
+With block diagrams you can create clear, concise, and visually appealing representations of systems. This is particularly beneficial for technical teams and stakeholders who need to document, analyze, or communicate complex processes without getting entangled in the intricacies of detailed schematics. Whether it's for software architecture, network systems, or process management, Mermaid's block diagrams offer an accessible and efficient way to visualize and convey crucial information.
+
+> **Warning**
+> If you are using the word "end" in a Flowchart block, capitalize the entire word or any of the letters (e.g., "End" or "END"), or apply this [workaround](https://github.com/mermaid-js/mermaid/issues/1444#issuecomment-639528897). Typing "end" in all lowercase letters will break the Flowchart.
+
+### A block (default)
+
+```mermaid-example
+---
+title: Block
+---
+block-beta
+    id
+```
+
+```mermaid
+---
+title: Block
+---
+block-beta
+    id
+```
+
+> **Note**
+> The id is what is displayed in the box.
+
+### A block with text
+
+It is also possible to set text in the box that differs from the id. If this is done several times, it is the last text
+found for the block that will be used. Also if you define edges for the block later on, you can omit text definitions. The
+one previously defined will be used when rendering the box.
+
+```mermaid-example
+---
+title: Node with text
+---
+block-beta
+    id1[This is the text in the box]
+```
+
+```mermaid
+---
+title: Node with text
+---
+block-beta
+    id1[This is the text in the box]
+```
+
+#### Unicode text
+
+Use `"` to enclose the unicode text.
+
+```mermaid-example
+block-beta
+    id["This ❤ Unicode"]
+```
+
+```mermaid
+block-beta
+    id["This ❤ Unicode"]
+```
+
+#### Markdown formatting
+
+Use double quotes and backticks "\` text \`" to enclose the markdown text.
+
+```mermaid-example
+%%{init: {"flowchart": {"htmlLabels": false}} }%%
+block-beta
+    markdown["`This **is** _Markdown_`"]
+    newLines["`Line1
+    Line 2
+    Line 3`"]
+    markdown --> newLines
+```
+
+```mermaid
+%%{init: {"flowchart": {"htmlLabels": false}} }%%
+block-beta
+    markdown["`This **is** _Markdown_`"]
+    newLines["`Line1
+    Line 2
+    Line 3`"]
+    markdown --> newLines
+```
+
+## Block shapes
+
+### A block with round edges
+
+```mermaid-example
+block-beta
+    id1(This is the text in the box)
+```
+
+```mermaid
+block-beta
+    id1(This is the text in the box)
+```
+
+### A stadium-shaped block
+
+```mermaid-example
+block-beta
+    id1([This is the text in the box])
+```
+
+```mermaid
+block-beta
+    id1([This is the text in the box])
+```
+
+### A block in a subroutine shape
+
+```mermaid-example
+block-beta
+    id1[[This is the text in the box]]
+```
+
+```mermaid
+block-beta
+    id1[[This is the text in the box]]
+```
+
+### A block in a cylindrical shape
+
+```mermaid-example
+block-beta
+    id1[(Database)]
+```
+
+```mermaid
+block-beta
+    id1[(Database)]
+```
+
+### A block in the form of a circle
+
+```mermaid-example
+block-beta
+    id1((This is the text in the circle))
+```
+
+```mermaid
+block-beta
+    id1((This is the text in the circle))
+```
+
+### A block in an asymmetric shape
+
+```mermaid-example
+block-beta
+    id1>This is the text in the box]
+```
+
+```mermaid
+block-beta
+    id1>This is the text in the box]
+```
+
+### A block (rhombus)
+
+```mermaid-example
+block-beta
+    id1{This is the text in the box}
+```
+
+```mermaid
+block-beta
+    id1{This is the text in the box}
+```
+
+### A hexagon block
+
+```mermaid-example
+block-beta
+    id1{{This is the text in the box}}
+```
+
+```mermaid
+block-beta
+    id1{{This is the text in the box}}
+```
+
+### Parallelogram
+
+```mermaid-example
+flowchart TD
+    id1[/This is the text in the box/]
+```
+
+```mermaid
+flowchart TD
+    id1[/This is the text in the box/]
+```
+
+### Parallelogram alt
+
+```mermaid-example
+flowchart TD
+    id1[\This is the text in the box\]
+```
+
+```mermaid
+flowchart TD
+    id1[\This is the text in the box\]
+```
+
+### Trapezoid
+
+```mermaid-example
+flowchart TD
+    A[/Christmas\]
+```
+
+```mermaid
+flowchart TD
+    A[/Christmas\]
+```
+
+### Trapezoid alt
+
+```mermaid-example
+flowchart TD
+    B[\Go shopping/]
+```
+
+```mermaid
+flowchart TD
+    B[\Go shopping/]
+```
+
+### Double circle
+
+```mermaid-example
+flowchart TD
+    id1(((This is the text in the circle)))
+```
+
+```mermaid
+flowchart TD
+    id1(((This is the text in the circle)))
+```
+
+## Links between blocks
+
+Blocks can be connected with links/edges. It is possible to have different types of links or attach a text string to a link.
+
+### A link with arrow head
+
+```mermaid-example
+block-beta
+    A-->B
+```
+
+```mermaid
+block-beta
+    A-->B
+```
+
+### An open link
+
+```mermaid-example
+block-beta
+    A --- B
+```
+
+```mermaid
+block-beta
+    A --- B
+```
+
+### Text on links
+
+```mermaid-example
+block-beta
+    A-- This is the text! ---B
+```
+
+```mermaid
+block-beta
+    A-- This is the text! ---B
+```
+
+or
+
+```mermaid-example
+block-beta
+    A---|This is the text|B
+```
+
+```mermaid
+block-beta
+    A---|This is the text|B
+```
+
+### A link with arrow head and text
+
+```mermaid-example
+block-beta
+    A-->|text|B
+```
+
+```mermaid
+block-beta
+    A-->|text|B
+```
+
+or
+
+```mermaid-example
+block-beta
+    A-- text -->B
+```
+
+```mermaid
+block-beta
+    A-- text -->B
+```
+
+### Dotted link
+
+```mermaid-example
+block-beta
+   A-.->B;
+```
+
+```mermaid
+block-beta
+   A-.->B;
+```
+
+### Dotted link with text
+
+```mermaid-example
+block-beta
+   A-. text .-> B
+```
+
+```mermaid
+block-beta
+   A-. text .-> B
+```
+
+### Thick link
+
+```mermaid-example
+block-beta
+   A ==> B
+```
+
+```mermaid
+block-beta
+   A ==> B
+```
+
+### Thick link with text
+
+```mermaid-example
+block-beta
+   A == text ==> B
+```
+
+```mermaid
+block-beta
+   A == text ==> B
+```
+
+### Different types of links
+
+There are new types of arrows supported as per below:
+
+```mermaid-example
+block-beta
+    A --o B
+    B --x C
+```
+
+```mermaid
+block-beta
+    A --o B
+    B --x C
+```
+
+### Multi directional arrows
+
+There is the possibility to use multidirectional arrows.
+
+```mermaid-example
+block-beta
+    A o--o B
+    B <--> C
+    C x--x D
+```
+
+```mermaid
+block-beta
+    A o--o B
+    B <--> C
+    C x--x D
+```
+
+## Special characters that break syntax
+
+It is possible to put text within quotes in order to render more troublesome characters. As in the example below:
+
+```mermaid-example
+block-beta
+    id1["This is the (text) in the box"]
+```
+
+```mermaid
+block-beta
+    id1["This is the (text) in the box"]
+```
+
+### Entity codes to escape characters
+
+It is possible to escape characters using the syntax exemplified here.
+
+```mermaid-example
+    block-beta
+        A["A double quote:#quot;"] -->B["A dec char:#9829;"]
+```
+
+```mermaid
+    block-beta
+        A["A double quote:#quot;"] -->B["A dec char:#9829;"]
+```
+
+Numbers given are base 10, so `#` can be encoded as `#35;`. It is also supported to use HTML character names.
+
+## Blocks in blocks
+
+    block-beta
+        block definition
+    end
+
+An example below:
+
+```mermaid-example
+block-beta
+    block
+        A["square"]
+        B("rounded")
+    end
+    C(("circle"))
+```
+
+```mermaid
+block-beta
+    block
+        A["square"]
+        B("rounded")
+    end
+    C(("circle"))
+```
+
+### Comments
+
+Comments can be entered within a flow 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 flow syntax
+
+```mermaid-example
+block-beta
+%% this is a comment A -- text --> B{block}
+   A -- text --> B -- text2 --> C
+```
+
+```mermaid
+block-beta
+%% this is a comment A -- text --> B{block}
+   A -- text --> B -- text2 --> C
+```
+
+## Styling and classes
+
+### Styling a block
+
+It is possible to apply specific styles such as a thicker border or a different background color to a block.
+
+```mermaid-example
+block-beta
+    id1(Start)-->id2(Stop)
+    style id1 fill:#f9f,stroke:#333,stroke-width:4px
+    style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+```mermaid
+block-beta
+    id1(Start)-->id2(Stop)
+    style id1 fill:#f9f,stroke:#333,stroke-width:4px
+    style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+#### Classes
+
+More convenient than defining the style every time is to define a class of styles and attach this class to the blocks that
+should have a different look.
+
+A class definition looks like the example below:
+
+        classDef className fill:#f9f,stroke:#333,stroke-width:4px;
+
+Also, it is possible to define style to multiple classes in one statement:
+
+        classDef firstClassName,secondClassName font-size:12pt;
+
+Attachment of a class to a block is done as per below:
+
+        class blockId1 className;
+
+It is also possible to attach a class to a list of blocks in one statement:
+
+        class blockId1,blockId2 className;

docs/syntax/block.md

@@ -0,0 +1,710 @@
+> **Warning**
+>
+> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
+>
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/block.md](../../packages/mermaid/src/docs/syntax/block.md).
+
+# Block Diagrams Documentation
+
+## 1. Introduction to Block Diagrams
+
+### Definition and Purpose
+
+Block diagrams are an intuitive and efficient way to represent complex systems, processes, or architectures visually. They are composed of blocks and connectors, where blocks represent the fundamental components or functions, and connectors show the relationship or flow between these components. This method of diagramming is essential in various fields such as engineering, software development, and process management.
+
+The primary purpose of block diagrams is to provide a high-level view of a system, allowing for easy understanding and analysis without delving into the intricate details of each component. This makes them particularly useful for simplifying complex systems and for explaining the overall structure and interaction of components within a system.
+
+### General Use Cases
+
+Block diagrams have a wide range of applications across various industries and disciplines. Some of the key use cases include:
+
+- **Software Architecture**: In software development, block diagrams can be used to illustrate the architecture of a software application. This includes showing how different modules or services interact, data flow, and high-level component interaction.
+
+- **Network Diagrams**: Block diagrams are ideal for representing network architectures in IT and telecommunications. They can depict how different network devices and services are interconnected, including routers, switches, firewalls, and the flow of data across the network.
+
+- **Process Flowcharts**: In business and manufacturing, block diagrams can be employed to create process flowcharts. These flowcharts represent various stages of a business or manufacturing process, helping to visualize the sequence of steps, decision points, and the flow of control.
+
+- **Electrical Systems**: Engineers use block diagrams to represent electrical systems and circuitry. They can illustrate the high-level structure of an electrical system, the interaction between different electrical components, and the flow of electrical currents.
+
+- **Educational Purposes**: Block diagrams are also extensively used in educational materials to explain complex concepts and systems in a simplified manner. They help in breaking down and visualizing scientific theories, engineering principles, and technological systems.
+
+These examples demonstrate the versatility of block diagrams in providing clear and concise representations of complex systems. Their simplicity and clarity make them a valuable tool for professionals across various fields to communicate complex ideas effectively.
+
+In the following sections, we will delve into the specifics of creating and manipulating block diagrams using Mermaid, covering everything from basic syntax to advanced configurations and styling.
+
+Creating block diagrams with Mermaid is straightforward and accessible. This section introduces the basic syntax and structure needed to start building simple diagrams. Understanding these foundational concepts is key to efficiently utilizing Mermaid for more complex diagramming tasks.
+
+### Simple Block Diagrams
+
+#### Basic Structure
+
+At its core, a block diagram consists of blocks representing different entities or components. In Mermaid, these blocks are easily created using simple text labels. The most basic form of a block diagram can be a series of blocks without any connectors.
+
+**Example - Simple Block Diagram**:
+To create a simple block diagram with three blocks labeled 'a', 'b', and 'c', the syntax is as follows:
+
+```mermaid-example
+block-beta
+  a b c
+```
+
+```mermaid
+block-beta
+  a b c
+```
+
+This example will produce a horizontal sequence of three blocks. Each block is automatically spaced and aligned for optimal readability.
+
+### Diagrams with Multiple Columns
+
+#### Column Usage
+
+While simple block diagrams are linear and straightforward, more complex systems may require a structured layout. Mermaid allows for the organization of blocks into multiple columns, facilitating the creation of more intricate and detailed diagrams.
+
+**Example - Multi-Column Diagram:**
+In scenarios where you need to distribute blocks across multiple columns, you can specify the number of columns and arrange the blocks accordingly. Here's how to create a block diagram with three columns and four blocks, where the fourth block appears in a second row:
+
+```mermaid-example
+block-beta
+  columns 3
+  a b c d
+```
+
+```mermaid
+block-beta
+  columns 3
+  a b c d
+```
+
+This syntax instructs Mermaid to arrange the blocks 'a', 'b', 'c', and 'd' across three columns, wrapping to the next row as needed. This feature is particularly useful for representing layered or multi-tiered systems, such as network layers or hierarchical structures.
+
+These basic building blocks of Mermaid's block diagrams provide a foundation for more complex diagramming. The simplicity of the syntax allows for quick creation and iteration of diagrams, making it an efficient tool for visualizing ideas and concepts. In the next section, we'll explore advanced block configuration options, including setting block widths and creating composite blocks.
+
+## 3. Advanced Block Configuration
+
+Building upon the basics, this section delves into more advanced features of block diagramming in Mermaid. These features allow for greater flexibility and complexity in diagram design, accommodating a wider range of use cases and scenarios.
+
+### Setting Block Width
+
+#### Spanning Multiple Columns
+
+In more complex diagrams, you may need blocks that span multiple columns to emphasize certain components or to represent larger entities. Mermaid allows for the adjustment of block widths to cover multiple columns, enhancing the diagram's readability and structure.
+
+**Example - Block Spanning Multiple Columns**:
+To create a block diagram where one block spans across two columns, you can specify the desired width for each block:
+
+```mermaid-example
+block-beta
+  columns 3
+  a["A wide one"] b:2 c:2 d
+```
+
+```mermaid
+block-beta
+  columns 3
+  a["A wide one"] b:2 c:2 d
+```
+
+In this example, the block labeled "A wide one" spans two columns, while blocks 'b', 'c', and 'd' are allocated their own columns. This flexibility in block sizing is crucial for accurately representing systems with components of varying significance or size.
+
+### Creating Composite Blocks
+
+#### Nested Blocks
+
+Composite blocks, or blocks within blocks, are an advanced feature in Mermaid's block diagram syntax. They allow for the representation of nested or hierarchical systems, where one component encompasses several subcomponents.
+
+**Example - Composite Blocks:**
+Creating a composite block involves defining a parent block and then nesting other blocks within it. Here's how to define a composite block with nested elements:
+
+```mermaid-example
+block-beta
+    block
+      D
+    end
+    A["A: I am a wide one"]
+```
+
+```mermaid
+block-beta
+    block
+      D
+    end
+    A["A: I am a wide one"]
+```
+
+In this syntax, 'D' is a nested block within a larger parent block. This feature is particularly useful for depicting complex structures, such as a server with multiple services or a department within a larger organizational framework.
+
+### Column Width Dynamics
+
+#### Adjusting Widths
+
+Mermaid also allows for dynamic adjustment of column widths based on the content of the blocks. The width of the columns is determined by the widest block in the column, ensuring that the diagram remains balanced and readable.
+
+**Example - Dynamic Column Widths:**
+In diagrams with varying block sizes, Mermaid automatically adjusts the column widths to fit the largest block in each column. Here's an example:
+
+```mermaid-example
+block-beta
+columns 3
+a:3
+block:e:3
+f
+end
+g
+```
+
+```mermaid
+block-beta
+columns 3
+a:3
+block:e:3
+f
+end
+g
+```
+
+This example demonstrates how Mermaid dynamically adjusts the width of the columns to accommodate the widest block, in this case, 'a' and the composite block 'e'. This dynamic adjustment is essential for creating visually balanced and easy-to-understand diagrams.
+
+With these advanced configuration options, Mermaid's block diagrams can be tailored to represent a wide array of complex systems and structures. The flexibility offered by these features enables users to create diagrams that are both informative and visually appealing. In the following sections, we will explore further capabilities, including different block shapes and linking options.
+
+## 4. Block Varieties and Shapes
+
+Mermaid's block diagrams are not limited to standard rectangular shapes. A variety of block shapes are available, allowing for a more nuanced and tailored representation of different types of information or entities. This section outlines the different block shapes you can use in Mermaid and their specific applications.
+
+### Standard and Special Block Shapes
+
+Mermaid supports a range of block shapes to suit different diagramming needs, from basic geometric shapes to more specialized forms.
+
+#### Example - Round Edged Block
+
+To create a block with round edges, which can be used to represent a softer or more flexible component:
+
+```mermaid-example
+block-beta
+    id1(This is the text in the box)
+```
+
+```mermaid
+block-beta
+    id1(This is the text in the box)
+```
+
+#### Example - Stadium-Shaped Block
+
+A stadium-shaped block, resembling an elongated circle, can be used for components that are process-oriented:
+
+```mermaid-example
+block-beta
+    id1([This is the text in the box])
+```
+
+```mermaid
+block-beta
+    id1([This is the text in the box])
+```
+
+#### Example - Subroutine Shape
+
+For representing subroutines or contained processes, a block with double vertical lines is useful:
+
+```mermaid-example
+block-beta
+    id1[[This is the text in the box]]
+```
+
+```mermaid
+block-beta
+    id1[[This is the text in the box]]
+```
+
+#### Example - Cylindrical Shape
+
+The cylindrical shape is ideal for representing databases or storage components:
+
+```mermaid-example
+block-beta
+    id1[(Database)]
+```
+
+```mermaid
+block-beta
+    id1[(Database)]
+```
+
+#### Example - Circle Shape
+
+A circle can be used for centralized or pivotal components:
+
+```mermaid-example
+block-beta
+    id1((This is the text in the circle))
+```
+
+```mermaid
+block-beta
+    id1((This is the text in the circle))
+```
+
+#### Example - Asymmetric, Rhombus, and Hexagon Shapes
+
+For decision points, use a rhombus, and for unique or specialized processes, asymmetric and hexagon shapes can be utilized:
+
+**Asymmetric**
+
+```mermaid-example
+block-beta
+  id1>This is the text in the box]
+```
+
+```mermaid
+block-beta
+  id1>This is the text in the box]
+```
+
+**Rhombus**
+
+```mermaid-example
+block-beta
+    id1{This is the text in the box}
+```
+
+```mermaid
+block-beta
+    id1{This is the text in the box}
+```
+
+**Hexagon**
+
+```mermaid-example
+block-beta
+    id1{{This is the text in the box}}
+```
+
+```mermaid
+block-beta
+    id1{{This is the text in the box}}
+```
+
+#### Example - Parallelogram and Trapezoid Shapes
+
+Parallelogram and trapezoid shapes are perfect for inputs/outputs and transitional processes:
+
+```mermaid-example
+flowchart TD
+  id1[/This is the text in the box/]
+  id2[\This is the text in the box\]
+  A[/Christmas\]
+  B[\Go shopping/]
+```
+
+```mermaid
+flowchart TD
+  id1[/This is the text in the box/]
+  id2[\This is the text in the box\]
+  A[/Christmas\]
+  B[\Go shopping/]
+```
+
+#### Example - Double Circle
+
+For highlighting critical or high-priority components, a double circle can be effective:
+
+```mermaid-example
+flowchart TD
+    id1(((This is the text in the circle)))
+```
+
+```mermaid
+flowchart TD
+    id1(((This is the text in the circle)))
+```
+
+### Block Arrows and Space Blocks
+
+Mermaid also offers unique shapes like block arrows and space blocks for directional flow and spacing.
+
+#### Example - Block Arrows
+
+Block arrows can visually indicate direction or flow within a process:
+
+```mermaid-example
+block-beta
+  blockArrowId<["Label"]>(right)
+  blockArrowId2<["Label"]>(left)
+  blockArrowId3<["Label"]>(up)
+  blockArrowId4<["Label"]>(down)
+  blockArrowId5<["Label"]>(x)
+  blockArrowId6<["Label"]>(y)
+  blockArrowId6<["Label"]>(x, down)
+```
+
+```mermaid
+block-beta
+  blockArrowId<["Label"]>(right)
+  blockArrowId2<["Label"]>(left)
+  blockArrowId3<["Label"]>(up)
+  blockArrowId4<["Label"]>(down)
+  blockArrowId5<["Label"]>(x)
+  blockArrowId6<["Label"]>(y)
+  blockArrowId6<["Label"]>(x, down)
+```
+
+#### Example - Space Blocks
+
+Space blocks can be used to create intentional empty spaces in the diagram, which is useful for layout and readability:
+
+```mermaid-example
+block-beta
+  space:3
+  ida idb idc
+```
+
+```mermaid
+block-beta
+  space:3
+  ida idb idc
+```
+
+Note that you can set how many columns the spece block occupied using the number notaion `space:num` where num is a number indicating the num columns width. You can alsio use `space` which defaults to one column.
+
+The variety of shapes and special blocks in Mermaid enhances the expressive power of block diagrams, allowing for more accurate and context-specific representations. These options give users the flexibility to create diagrams that are both informative and visually appealing. In the next sections, we will explore the ways to connect these blocks and customize their appearance.
+
+### Standard and Special Block Shapes
+
+Discuss the various shapes available for blocks, including standard shapes and special forms like block arrows and space blocks.
+
+## 5. Connecting Blocks with Edges
+
+One of the key features of block diagrams in Mermaid is the ability to connect blocks using various types of edges or links. This section explores the different ways blocks can be interconnected to represent relationships and flows between components.
+
+### Basic Linking and Arrow Types
+
+The most fundamental aspect of connecting blocks is the use of arrows or links. These connectors depict the relationships or the flow of information between the blocks. Mermaid offers a range of arrow types to suit different diagramming needs.
+
+**Example - Basic Links**
+
+A simple link with an arrow can be created to show direction or flow from one block to another:
+
+```mermaid-example
+block-beta
+  A-->B
+```
+
+```mermaid
+block-beta
+  A-->B
+```
+
+This example illustrates a direct connection from block 'A' to block 'B', using a straightforward arrow.
+
+**Example - Open Link:**
+For connections that are less direct or to represent a different type of relationship, an open link (without an arrowhead) can be used:
+
+```mermaid-example
+block-beta
+  A --- B
+```
+
+```mermaid
+block-beta
+  A --- B
+```
+
+This syntax creates a line connecting 'A' and 'B', implying a relationship or connection without indicating a specific direction.
+
+### Text on Links
+
+In addition to connecting blocks, it's often necessary to describe or label the relationship. Mermaid allows for the inclusion of text on links, providing context to the connections.
+
+Example - Text with Links
+To add text to a link, the syntax includes the text within the link definition:
+
+```mermaid-example
+block-beta
+  A-- This is the text! ---B
+```
+
+```mermaid
+block-beta
+  A-- This is the text! ---B
+```
+
+This example show how to add descriptive text to the links, enhancing the information conveyed by the diagram.
+
+### Advanced Link Types
+
+Mermaid also supports various advanced link types, such as dotted lines, thick links, and different arrowheads, to represent different kinds of relationships or interactions.
+
+**Example - Dotted and Thick Links**
+A dotted link can be used to represent a weaker or less formal relationship:
+
+```mermaid-example
+block-beta
+  A-.->B
+```
+
+```mermaid
+block-beta
+  A-.->B
+```
+
+For a more pronounced connection, a thick link can be used:
+
+```mermaid-example
+block-beta
+  A==>B
+```
+
+```mermaid
+block-beta
+  A==>B
+```
+
+Example - Edges and Styles:
+
+```mermaid-example
+block-beta
+columns 1
+  db(("DB"))
+  blockArrowId6<["&nbsp;&nbsp;&nbsp;"]>(down)
+  block:ID
+    A
+    B["A wide one in the middle"]
+    C
+  end
+  space
+  D
+  ID --> D
+  C --> D
+  style B fill:#f9F,stroke:#333,stroke-width:4px
+```
+
+```mermaid
+block-beta
+columns 1
+  db(("DB"))
+  blockArrowId6<["&nbsp;&nbsp;&nbsp;"]>(down)
+  block:ID
+    A
+    B["A wide one in the middle"]
+    C
+  end
+  space
+  D
+  ID --> D
+  C --> D
+  style B fill:#f9F,stroke:#333,stroke-width:4px
+```
+
+## 6. Styling and Customization
+
+Beyond the structure and layout of block diagrams, Mermaid offers extensive styling options. These customization features allow for the creation of more visually distinctive and informative diagrams. This section covers how to apply individual styles to blocks and how to use classes for consistent styling across multiple elements.
+
+### Individual Block Styling
+
+Mermaid enables detailed styling of individual blocks, allowing you to apply various CSS properties such as color, stroke, and border thickness. This feature is especially useful for highlighting specific parts of a diagram or for adhering to certain visual themes.
+
+#### Example - Styling a Single Block
+
+To apply custom styles to a block, you can use the `style` keyword followed by the block identifier and the desired CSS properties:
+
+```mermaid-example
+block-beta
+  id1(Start)-->id2(Stop)
+  style id1 fill:#f9f,stroke:#333,stroke-width:4px
+  style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+```mermaid
+block-beta
+  id1(Start)-->id2(Stop)
+  style id1 fill:#f9f,stroke:#333,stroke-width:4px
+  style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+In this example, a class named 'blue' is defined and applied to block 'A', while block 'B' receives individual styling. This demonstrates the flexibility of Mermaid in applying both shared and unique styles within the same diagram.
+
+The ability to style blocks individually or through classes provides a powerful tool for enhancing the visual impact and clarity of block diagrams. Whether emphasizing certain elements or maintaining a cohesive design across the diagram, these styling capabilities are central to effective diagramming. The next sections will present practical examples and use cases, followed by tips for troubleshooting common issues.
+
+### 7. Practical Examples and Use Cases
+
+The versatility of Mermaid's block diagrams becomes evident when applied to real-world scenarios. This section provides practical examples demonstrating the application of various features discussed in previous sections. These examples showcase how block diagrams can be used to represent complex systems and processes in an accessible and informative manner.
+
+### Detailed Examples Illustrating Various Features
+
+Combining the elements of structure, linking, and styling, we can create comprehensive diagrams that serve specific purposes in different contexts.
+
+#### Example - System Architecture
+
+Illustrating a simple software system architecture with interconnected components:
+
+```mermaid-example
+block-beta
+  columns 2
+  Frontend Backend
+  Frontend-->Backend
+  Database[(Database)]
+  Backend-->Database
+  class Frontend,Backend fill:#f96,stroke:#333;
+  class Database fill:#9f9,stroke:#333;
+```
+
+```mermaid
+block-beta
+  columns 2
+  Frontend Backend
+  Frontend-->Backend
+  Database[(Database)]
+  Backend-->Database
+  class Frontend,Backend fill:#f96,stroke:#333;
+  class Database fill:#9f9,stroke:#333;
+```
+
+This example shows a basic architecture with a frontend, backend, and database. The blocks are styled to differentiate between types of components.
+
+#### Example - Business Process Flow
+
+Representing a business process flow with decision points and multiple stages:
+
+```mermaid-example
+block-beta
+  Start{Start}
+  Decision{Make Decision}
+  Process1[Process A]
+  Process2[Process B]
+  End((End))
+  Start --> Decision
+  Decision -- Yes --> Process1
+  Decision -- No --> Process2
+  Process1 --> End
+  Process2 --> End
+  style Start fill:#f9f;
+  style End fill:#bbf;
+
+```
+
+```mermaid
+block-beta
+  Start{Start}
+  Decision{Make Decision}
+  Process1[Process A]
+  Process2[Process B]
+  End((End))
+  Start --> Decision
+  Decision -- Yes --> Process1
+  Decision -- No --> Process2
+  Process1 --> End
+  Process2 --> End
+  style Start fill:#f9f;
+  style End fill:#bbf;
+
+```
+
+This diagram depicts a simple decision-making process with two possible paths leading to an endpoint, demonstrating the use of different shapes and directional arrows.
+
+### Real works Application Scenarios
+
+Block diagrams can be employed in a variety of real-world scenarios. Here are a few examples:
+
+- **IT Network Layouts**: Visualize the structure of IT networks, showing how different devices and services are connected.
+- **Educational Diagrams**: Explain complex scientific concepts, engineering systems, or historical timelines.
+- **Organizational Charts**: Represent the hierarchy and relationships within an organization or department.
+
+These practical examples and scenarios underscore the utility of Mermaid block diagrams in simplifying and effectively communicating complex information across various domains.
+
+The next section, 'Troubleshooting and Common Issues', will provide insights into resolving common challenges encountered when working with Mermaid block diagrams, ensuring a smooth diagramming experience.
+
+```mermaid-example
+
+```
+
+```mermaid
+
+```
+
+```mermaid-example
+
+```
+
+```mermaid
+
+```
+
+## 8. Troubleshooting and Common Issues
+
+Working with Mermaid block diagrams can sometimes present challenges, especially as the complexity of the diagrams increases. This section aims to provide guidance on resolving common issues and offers tips for managing more intricate diagram structures.
+
+### Common Syntax Errors
+
+Understanding and avoiding common syntax errors is key to a smooth experience with Mermaid diagrams.
+
+#### Example - Incorrect Linking
+
+A common mistake is incorrect linking syntax, which can lead to unexpected results or broken diagrams:
+
+    block-beta
+      A - B
+
+**Correction**:
+Ensure that links between blocks are correctly specified with arrows (--> or ---) to define the direction and type of connection:
+
+```mermaid-example
+block-beta
+  A --> B
+```
+
+```mermaid
+block-beta
+  A --> B
+```
+
+#### Example - Misplaced Styling
+
+Applying styles in the wrong context or with incorrect syntax can lead to blocks not being styled as intended:
+
+```mermaid-example
+  block-beta
+    A
+    style A fill#f9f;
+```
+
+```mermaid
+  block-beta
+    A
+    style A fill#f9f;
+```
+
+**Correction:**
+Correct the syntax by ensuring proper separation of style properties with commas and using the correct CSS property format:
+
+```mermaid-example
+block-beta
+  A
+  style A fill:#f9f,stroke:#333;
+
+```
+
+```mermaid
+block-beta
+  A
+  style A fill:#f9f,stroke:#333;
+
+```
+
+### Tips for Complex Diagram Structures
+
+Managing complexity in Mermaid diagrams involves planning and employing best practices.
+
+#### Modular Design
+
+Break down complex diagrams into smaller, more manageable components. This approach not only makes the diagram easier to understand but also simplifies the creation and maintenance process.
+
+#### Consistent Styling
+
+Use classes to maintain consistent styling across similar elements. This not only saves time but also ensures a cohesive and professional appearance.
+
+#### Comments and Documentation
+
+Use comments within the Mermaid syntax to document the purpose of various parts of the diagram. This practice is invaluable for maintaining clarity, especially when working in teams or returning to a diagram after some time.
+
+With these troubleshooting tips and best practices, you can effectively manage and resolve common issues in Mermaid block diagrams. The final section, 'Conclusion', will summarize the key points covered in this documentation and invite user feedback for continuous improvement.

docs/syntax/c4.md

@@ -2,13 +2,13 @@
 >
 > ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
 >
-> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/c4c.md](../../packages/mermaid/src/docs/syntax/c4c.md).
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/c4.md](../../packages/mermaid/src/docs/syntax/c4.md).
 
 # C4 Diagrams
 
 > C4 Diagram: This is an experimental diagram for now. The syntax and properties can change in future releases. Proper documentation will be provided when the syntax is stable.
 
-Mermaid's c4 diagram syntax is compatible with plantUML. See example below:
+Mermaid's C4 diagram syntax is compatible with plantUML. See example below:
 
 ```mermaid-example
     C4Context
@@ -114,7 +114,7 @@ For an example, see the source code demos/index.html
 - Dynamic diagram (C4Dynamic)
 - Deployment diagram (C4Deployment)
 
-Please refer to the linked document [C4-PlantUML syntax](https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/README.md) for how to write the c4 diagram.
+Please refer to the linked document [C4-PlantUML syntax](https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/README.md) for how to write the C4 diagram.
 
 C4 diagram is fixed style, such as css color, so different css is not provided under different skins.
 updateElementStyle and UpdateElementStyle are written in the diagram last part. updateElementStyle is inconsistent with the original definition and updates the style of the relationship, including the offset of the text label relative to the original position.
@@ -399,7 +399,7 @@ UpdateRelStyle(customerA, bankA, $offsetY="60")
     title Component diagram for Internet Banking System - API Application
 
     Container(spa, "Single Page Application", "javascript and angular", "Provides all the internet banking functionality to customers via their web browser.")
-    Container(ma, "Mobile App", "Xamarin", "Provides a limited subset ot the internet banking functionality to customers via their mobile mobile device.")
+    Container(ma, "Mobile App", "Xamarin", "Provides a limited subset to the internet banking functionality to customers via their mobile mobile device.")
     ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
     System_Ext(mbs, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
 
@@ -439,7 +439,7 @@ UpdateRelStyle(customerA, bankA, $offsetY="60")
     title Component diagram for Internet Banking System - API Application
 
     Container(spa, "Single Page Application", "javascript and angular", "Provides all the internet banking functionality to customers via their web browser.")
-    Container(ma, "Mobile App", "Xamarin", "Provides a limited subset ot the internet banking functionality to customers via their mobile mobile device.")
+    Container(ma, "Mobile App", "Xamarin", "Provides a limited subset to the internet banking functionality to customers via their mobile mobile device.")
     ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
     System_Ext(mbs, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
 

docs/syntax/classDiagram.md

@@ -240,9 +240,9 @@ 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**). **Nested** type declarations such as `List<List<int>>` are supported.
+Generics can be representated as part of a class definition, and for class members/return types. In order to denote an item as generic, you enclose that type within `~` (**tilde**). **Nested** type declarations such as `List<List<int>>` are supported, though generics that include a comma are currently not supported. (such as `List<List<K, V>>`)
 
-Generics can be represented as part of a class definition and also in the parameters or the return value of a method/function:
+> _note_ when a generic is used within a class definition, the generic type is NOT considered part of the class name. i.e.: for any syntax which required you to reference the class name, you need to drop the type part of the definition. This also means that mermaid does not currently support having two classes with the same name, but different generic types.
 
 ```mermaid-example
 classDiagram
@@ -425,8 +425,6 @@ And `Link` can be one of:
 
 A namespace groups classes.
 
-Code:
-
 ```mermaid-example
 classDiagram
 namespace BaseShapes {
@@ -461,9 +459,9 @@ The different cardinality options are :
 - `0..1` Zero or One
 - `1..*` One or more
 - `*` Many
-- `n` n {where n>1}
-- `0..n` zero to n {where n>1}
-- `1..n` one to n {where n>1}
+- `n` n (where n>1)
+- `0..n` zero to n (where n>1)
+- `1..n` one to n (where n>1)
 
 Cardinality can be easily defined by placing the text option within quotes `"` before or after a given arrow. For example:
 
@@ -768,9 +766,30 @@ Beginner's tip—a full example using interactive links in an HTML page:
 
 ## Styling
 
-### Styling a node
+### Styling a node (v10.7.0+)
 
-It is possible to apply specific styles such as a thicker border or a different background color to individual nodes. This is done by predefining classes in css styles that can be applied from the graph definition using the `cssClass` statement or the `:::` short hand.
+It is possible to apply specific styles such as a thicker border or a different background color to an individual node using the `style` keyword.
+
+```mermaid-example
+classDiagram
+  class Animal
+  class Mineral
+  style Animal fill:#f9f,stroke:#333,stroke-width:4px
+  style Mineral fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+```mermaid
+classDiagram
+  class Animal
+  class Mineral
+  style Animal fill:#f9f,stroke:#333,stroke-width:4px
+  style Mineral fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+#### Classes
+
+More convenient than defining the style every time is to define a class of styles and attach this class to the nodes that
+should have a different look. This is done by predefining classes in css styles that can be applied from the graph definition using the `cssClass` statement or the `:::` short hand.
 
 ```html
 <style>

docs/syntax/entityRelationshipDiagram.md

@@ -90,7 +90,7 @@ Mermaid syntax for ER diagrams is compatible with PlantUML, with an extension to
 
 Where:
 
-- `first-entity` is the name of an entity. Names must begin with an alphabetic character and may also contain digits, hyphens, and underscores.
+- `first-entity` is the name of an entity. Names must begin with an alphabetic character or an underscore (from v10.5.0+), and may also contain digits and hyphens.
 - `relationship` describes the way that both entities inter-relate. See below.
 - `second-entity` is the name of the other entity.
 - `relationship-label` describes the relationship from the perspective of the first entity.
@@ -198,6 +198,34 @@ erDiagram
 
 The `type` values must begin with an alphabetic character and may contain digits, hyphens, underscores, parentheses and square brackets. The `name` values follow a similar format to `type`, but may start with an asterisk as another option to indicate an attribute is a primary key. Other than that, there are no restrictions, and there is no implicit set of valid data types.
 
+### Entity Name Aliases (v10.5.0+)
+
+An alias can be added to an entity using square brackets. If provided, the alias will be showed in the diagram instead of the entity name.
+
+```mermaid-example
+erDiagram
+    p[Person] {
+        string firstName
+        string lastName
+    }
+    a["Customer Account"] {
+        string email
+    }
+    p ||--o| a : has
+```
+
+```mermaid
+erDiagram
+    p[Person] {
+        string firstName
+        string lastName
+    }
+    a["Customer Account"] {
+        string email
+    }
+    p ||--o| a : has
+```
+
 #### Attribute Keys and Comments
 
 Attributes may also have a `key` or comment defined. Keys can be `PK`, `FK` or `UK`, for Primary Key, Foreign Key or Unique Key. To specify multiple key constraints on a single attribute, separate them with a comma (e.g., `PK, FK`).. A `comment` is defined by double quotes at the end of an attribute. Comments themselves cannot have double-quote characters in them.

docs/syntax/flowchart.md

@@ -11,6 +11,13 @@ Flowcharts are composed of **nodes** (geometric shapes) and **edges** (arrows or
 > **Warning**
 > If you are using the word "end" in a Flowchart node, capitalize the entire word or any of the letters (e.g., "End" or "END"), or apply this [workaround](https://github.com/mermaid-js/mermaid/issues/1444#issuecomment-639528897). Typing "end" in all lowercase letters will break the Flowchart.
 
+> **Warning**
+> If you are using the letter "o" or "x" as the first letter in a connecting Flowchart node, add a space before the letter or capitalize the letter (e.g., "dev--- ops", "dev---Ops").
+>
+> Typing "A---oB" will create a [circle edge](#circle-edge-example).
+>
+> Typing "A---xB" will create a [cross edge](#cross-edge-example).
+
 ### A node (default)
 
 ```mermaid-example
@@ -467,7 +474,7 @@ flowchart TB
     A & B--> C & D
 ```
 
-If you describe the same diagram using the the basic syntax, it will take four lines. A
+If you describe the same diagram using the basic syntax, it will take four lines. A
 word of warning, one could go overboard with this making the flowchart harder to read in
 markdown form. The Swedish word `lagom` comes to mind. It means, not too much and not too little.
 This goes for expressive syntaxes as well.
@@ -488,23 +495,38 @@ flowchart TB
     B --> D
 ```
 
-### New arrow types
+## New arrow types
 
-There are new types of arrows supported as per below:
+There are new types of arrows supported:
+
+- circle edge
+- cross edge
+
+### Circle edge example
 
 ```mermaid-example
 flowchart LR
     A --o B
-    B --x C
 ```
 
 ```mermaid
 flowchart LR
     A --o B
-    B --x C
 ```
 
-### Multi directional arrows
+### Cross edge example
+
+```mermaid-example
+flowchart LR
+    A --x B
+```
+
+```mermaid
+flowchart LR
+    A --x B
+```
+
+## Multi directional arrows
 
 There is the possibility to use multidirectional arrows.
 
@@ -608,12 +630,12 @@ It is possible to escape characters using the syntax exemplified here.
 
 ```mermaid-example
     flowchart LR
-        A["A double quote:#quot;"] -->B["A dec char:#9829;"]
+        A["A double quote:#quot;"] --> B["A dec char:#9829;"]
 ```
 
 ```mermaid
     flowchart LR
-        A["A double quote:#quot;"] -->B["A dec char:#9829;"]
+        A["A double quote:#quot;"] --> B["A dec char:#9829;"]
 ```
 
 Numbers given are base 10, so `#` can be encoded as `#35;`. It is also supported to use HTML character names.
@@ -748,6 +770,48 @@ flowchart LR
   B1 --> B2
 ```
 
+#### Limitation
+
+If any of a subgraph's nodes are linked to the outside, subgraph direction will be ignored. Instead the subgraph will inherit the direction of the parent graph:
+
+```mermaid-example
+flowchart LR
+    subgraph subgraph1
+        direction TB
+        top1[top] --> bottom1[bottom]
+    end
+    subgraph subgraph2
+        direction TB
+        top2[top] --> bottom2[bottom]
+    end
+    %% ^ These subgraphs are identical, except for the links to them:
+
+    %% Link *to* subgraph1: subgraph1 direction is maintained
+    outside --> subgraph1
+    %% Link *within* subgraph2:
+    %% subgraph2 inherits the direction of the top-level graph (LR)
+    outside ---> top2
+```
+
+```mermaid
+flowchart LR
+    subgraph subgraph1
+        direction TB
+        top1[top] --> bottom1[bottom]
+    end
+    subgraph subgraph2
+        direction TB
+        top2[top] --> bottom2[bottom]
+    end
+    %% ^ These subgraphs are identical, except for the links to them:
+
+    %% Link *to* subgraph1: subgraph1 direction is maintained
+    outside --> subgraph1
+    %% Link *within* subgraph2:
+    %% subgraph2 inherits the direction of the top-level graph (LR)
+    outside ---> top2
+```
+
 ## Markdown Strings
 
 The "Markdown Strings" feature enhances flowcharts and mind maps by offering a more versatile string type, which supports text formatting options such as bold and italics, and automatically wraps text within labels.
@@ -818,8 +882,8 @@ flowchart LR
     C-->D
     click A callback "Tooltip for a callback"
     click B "https://www.github.com" "This is a tooltip for a link"
-    click A call callback() "Tooltip for a callback"
-    click B href "https://www.github.com" "This is a tooltip for a link"
+    click C call callback() "Tooltip for a callback"
+    click D href "https://www.github.com" "This is a tooltip for a link"
 ```
 
 ```mermaid
@@ -829,13 +893,13 @@ flowchart LR
     C-->D
     click A callback "Tooltip for a callback"
     click B "https://www.github.com" "This is a tooltip for a link"
-    click A call callback() "Tooltip for a callback"
-    click B href "https://www.github.com" "This is a tooltip for a link"
+    click C call callback() "Tooltip for a callback"
+    click D href "https://www.github.com" "This is a tooltip for a link"
 ```
 
 > **Success** The tooltip functionality and the ability to link to urls are available from version 0.5.2.
 
-?> Due to limitations with how Docsify handles JavaScript callback functions, an alternate working demo for the above code can be viewed at [this jsfiddle](https://jsfiddle.net/s37cjoau/3/).
+?> Due to limitations with how Docsify handles JavaScript callback functions, an alternate working demo for the above code can be viewed at [this jsfiddle](https://jsfiddle.net/Ogglas/2o73vdez/7).
 
 Links are opened in the same browser tab/window by default. It is possible to change this by adding a link target to the click definition (`_self`, `_blank`, `_parent` and `_top` are supported):
 
@@ -1009,9 +1073,9 @@ flowchart LR
     classDef foobar stroke:#00f
 ```
 
-### Css classes
+### CSS classes
 
-It is also possible to predefine classes in css styles that can be applied from the graph definition as in the example
+It is also possible to predefine classes in CSS styles that can be applied from the graph definition as in the example
 below:
 
 **Example style**
@@ -1056,7 +1120,7 @@ The icons are accessed via the syntax fa:#icon class name#.
 
 ```mermaid-example
 flowchart TD
-    B["fab:fa-twitter for peace"]
+    B["fa:fa-twitter for peace"]
     B-->C[fa:fa-ban forbidden]
     B-->D(fa:fa-spinner)
     B-->E(A fa:fa-camera-retro perhaps?)
@@ -1064,13 +1128,13 @@ flowchart TD
 
 ```mermaid
 flowchart TD
-    B["fab:fa-twitter for peace"]
+    B["fa:fa-twitter for peace"]
     B-->C[fa:fa-ban forbidden]
     B-->D(fa:fa-spinner)
     B-->E(A fa:fa-camera-retro perhaps?)
 ```
 
-Mermaid is compatible with Font Awesome up to verion 5, Free icons only. Check that the icons you use are from the [supported set of icons](https://fontawesome.com/v5/search?o=r&m=free).
+Mermaid is compatible with Font Awesome up to version 5, Free icons only. Check that the icons you use are from the [supported set of icons](https://fontawesome.com/v5/search?o=r&m=free).
 
 ## Graph declarations with spaces between vertices and link and without semicolon
 
@@ -1104,7 +1168,7 @@ The layout of the diagram is done with the renderer. The default renderer is dag
 
 Starting with Mermaid version 9.4, you can use an alternate renderer named elk. The elk renderer is better for larger and/or more complex diagrams.
 
-The _elk_ renderer is an experimenal feature.
+The _elk_ renderer is an experimental feature.
 You can change the renderer to elk by adding this directive:
 
     %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%

docs/syntax/gantt.md

@@ -241,7 +241,7 @@ The following formatting strings are supported:
 
 More info in: <https://github.com/d3/d3-time-format/tree/v4.0.0#locale_format>
 
-### Axis ticks
+### Axis ticks (v10.3.0+)
 
 The default output ticks are auto. You can custom your `tickInterval`, like `1day` or `1week`.
 
@@ -252,7 +252,7 @@ tickInterval 1day
 The pattern is:
 
 ```javascript
-/^([1-9][0-9]*)(minute|hour|day|week|month)$/;
+/^([1-9][0-9]*)(millisecond|second|minute|hour|day|week|month)$/;
 ```
 
 More info in: <https://github.com/d3/d3-time#interval_every>
@@ -271,6 +271,8 @@ gantt
   weekday monday
 ```
 
+> **Warning** > `millisecond` and `second` support was added in vMERMAID_RELEASE_VERSION
+
 ## Output in compact mode
 
 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 preceeding YAML settings.
@@ -418,11 +420,21 @@ mermaid.ganttConfig can be set to a JSON string with config parameters or the co
 
 ```javascript
 mermaid.ganttConfig = {
-  titleTopMargin: 25,
-  barHeight: 20,
-  barGap: 4,
-  topPadding: 75,
-  sidePadding: 75,
+  titleTopMargin: 25, // Margin top for the text over the diagram
+  barHeight: 20, // The height of the bars in the graph
+  barGap: 4, // The margin between the different activities in the gantt diagram
+  topPadding: 75, // Margin between title and gantt diagram and between axis and gantt diagram.
+  rightPadding: 75, // The space allocated for the section name to the right of the activities
+  leftPadding: 75, // The space allocated for the section name to the left of the activities
+  gridLineStartPadding: 10, // Vertical starting position of the grid lines
+  fontSize: 12, // Font size
+  sectionFontSize: 24, // Font size for sections
+  numberSectionStyles: 1, // The number of alternating section styles
+  axisFormat: '%d/%m', // Date/time format of the axis
+  tickInterval: '1 week', // Axis ticks
+  topAxis: true, // When this flag is set, date labels will be added to the top of the chart
+  displayMode: 'compact', // Turns compact mode on
+  weekday: 'sunday', // On which day a week-based interval should start
 };
 ```
 

docs/syntax/gitgraph.md

@@ -366,41 +366,49 @@ A few important rules to note here are:
 1.  You need to provide the `id` for an existing commit to be cherry-picked. If given commit id does not exist it will result in an error. For this, make use of the `commit id:$value` format of declaring commits. See the examples from above.
 2.  The given commit must not exist on the current branch. The cherry-picked commit must always be a different branch than the current branch.
 3.  Current branch must have at least one commit, before you can cherry-pick, otherwise it will cause an error is throw.
+4.  When cherry-picking a merge commit, providing a parent commit ID is mandatory. If the parent attribute is omitted or an invalid parent commit ID is provided, an error will be thrown.
+5.  The specified parent commit must be an immediate parent of the merge commit being cherry-picked.
 
 Let see an example:
 
 ```mermaid-example
     gitGraph
-       commit id: "ZERO"
-       branch develop
-       commit id:"A"
-       checkout main
-       commit id:"ONE"
-       checkout develop
-       commit id:"B"
-       checkout main
-       commit id:"TWO"
-       cherry-pick id:"A"
-       commit id:"THREE"
-       checkout develop
-       commit id:"C"
+        commit id: "ZERO"
+        branch develop
+        branch release
+        commit id:"A"
+        checkout main
+        commit id:"ONE"
+        checkout develop
+        commit id:"B"
+        checkout main
+        merge develop id:"MERGE"
+        commit id:"TWO"
+        checkout release
+        cherry-pick id:"MERGE" parent:"B"
+        commit id:"THREE"
+        checkout develop
+        commit id:"C"
 ```
 
 ```mermaid
     gitGraph
-       commit id: "ZERO"
-       branch develop
-       commit id:"A"
-       checkout main
-       commit id:"ONE"
-       checkout develop
-       commit id:"B"
-       checkout main
-       commit id:"TWO"
-       cherry-pick id:"A"
-       commit id:"THREE"
-       checkout develop
-       commit id:"C"
+        commit id: "ZERO"
+        branch develop
+        branch release
+        commit id:"A"
+        checkout main
+        commit id:"ONE"
+        checkout develop
+        commit id:"B"
+        checkout main
+        merge develop id:"MERGE"
+        commit id:"TWO"
+        checkout release
+        cherry-pick id:"MERGE" parent:"B"
+        commit id:"THREE"
+        checkout develop
+        commit id:"C"
 ```
 
 ## Gitgraph specific configuration options
@@ -825,20 +833,27 @@ NOTE: Because we have overridden the `mainBranchOrder` to `2`, the `main` branch
 
 Here, we have changed the default main branch name to `MetroLine1`.
 
-## Orientation
+## Orientation (v10.3.0+)
 
-In Mermaid, the default orientation is Left to Right. The branches are lined vertically.
+Mermaid supports two graph orientations: **Left-to-Right** (default) and **Top-to-Bottom**.
+
+You can set this with either `LR:` (for [**Left-to-Right**](#left-to-right-default-lr)) or `TB:` (for [**Top-to-Bottom**](#top-to-bottom-tb)) after `gitGraph`.
+
+### Left to Right (default, `LR:`)
+
+In Mermaid, the default orientation is for commits to run from left to right and for branches to be stacked on top of one another.
+
+However, you can set this explicitly with `LR:` after `gitGraph`.
 
 Usage example:
 
 ```mermaid-example
-    gitGraph
+    gitGraph LR:
        commit
        commit
        branch develop
        commit
        commit
-       commit
        checkout main
        commit
        commit
@@ -848,13 +863,12 @@ Usage example:
 ```
 
 ```mermaid
-    gitGraph
+    gitGraph LR:
        commit
        commit
        branch develop
        commit
        commit
-       commit
        checkout main
        commit
        commit
@@ -863,9 +877,11 @@ Usage example:
        commit
 ```
 
-Sometimes we may want to change the orientation. Currently, Mermaid supports two orientations: **Left to Right**(default) and **Top to Bottom**.
+### Top to Bottom (`TB:`)
 
-In order to change the orientation from top to bottom i.e. branches lined horizontally, you need to add `TB` along with `gitGraph`.
+In `TB` (**Top-to-Bottom**) orientation, the commits run from top to bottom of the graph and branches are arranged side-by-side.
+
+To orient the graph this way, you need to add `TB:` after gitGraph.
 
 Usage example:
 
@@ -876,7 +892,6 @@ Usage example:
        branch develop
        commit
        commit
-       commit
        checkout main
        commit
        commit
@@ -892,7 +907,6 @@ Usage example:
        branch develop
        commit
        commit
-       commit
        checkout main
        commit
        commit

docs/syntax/mindmap.md

@@ -58,7 +58,7 @@ mindmap
 
 The syntax for creating Mindmaps is simple and relies on indentation for setting the levels in the hierarchy.
 
-In the following example you can see how there are 3 different levels. One with starting at the left of the text and another level with two rows starting at the same column, defining the node A. At the end there is one more level where the text is indented further then the previous lines defining the nodes B and C.
+In the following example you can see how there are 3 different levels. One with starting at the left of the text and another level with two rows starting at the same column, defining the node A. At the end there is one more level where the text is indented further than the previous lines defining the nodes B and C.
 
     mindmap
         Root
@@ -66,7 +66,7 @@ In the following example you can see how there are 3 different levels. One with
                 B
                 C
 
-In summary is a simple text outline where there are one node at the root level called `Root` which has one child `A`. `A` in turn has two children `B`and `C`. In the diagram below we can see this rendered as a mindmap.
+In summary is a simple text outline where there is one node at the root level called `Root` which has one child `A`. `A` in turn has two children `B`and `C`. In the diagram below we can see this rendered as a mindmap.
 
 ```mermaid-example
 mindmap
@@ -228,7 +228,7 @@ _These classes need to be supplied by the site administrator._
 
 ## Unclear indentation
 
-The actual indentation does not really matter only compared with the previous rows. If we take the previous example and disrupt it a little we can se how the calculations are performed. Let us start with placing C with a smaller indentation than `B`but larger then `A`.
+The actual indentation does not really matter only compared with the previous rows. If we take the previous example and disrupt it a little we can see how the calculations are performed. Let us start with placing C with a smaller indentation than `B` but larger then `A`.
 
     mindmap
         Root

docs/syntax/quadrantChart.md

@@ -47,8 +47,8 @@ quadrantChart
 ## Syntax
 
 > **Note**
-> If there is no points available in the chart both **axis** text and **quadrant** will be rendered in the center of the respective quadrant.
-> If there are points **x-axis** labels will rendered from left of the respective quadrant also they will be displayed in bottom of the chart, and **y-axis** lables will be rendered in bottom of the respective quadrant, the quadrant text will render at top of the respective quadrant.
+> If there are no points available in the chart both **axis** text and **quadrant** will be rendered in the center of the respective quadrant.
+> If there are points **x-axis** labels will rendered from the left of the respective quadrant also they will be displayed at the bottom of the chart, and **y-axis** labels will be rendered at the bottom of the respective quadrant, the quadrant text will render at the top of the respective quadrant.
 
 > **Note**
 > For points x and y value min value is 0 and max value is 1.
@@ -64,7 +64,7 @@ The title is a short description of the chart and it will always render on top o
 
 ### x-axis
 
-The x-axis determine what text would be displayed in the x-axis. In x-axis there is two part **left** and **right** you can pass **both** or you can pass only **left**. The statement should start with `x-axis` then the `left axis text` followed by the delimiter `-->` then `right axis text`.
+The x-axis determines what text would be displayed in the x-axis. In x-axis there is two part **left** and **right** you can pass **both** or you can pass only **left**. The statement should start with `x-axis` then the `left axis text` followed by the delimiter `-->` then `right axis text`.
 
 #### Example
 
@@ -73,7 +73,7 @@ The x-axis determine what text would be displayed in the x-axis. In x-axis there
 
 ### y-axis
 
-The y-axis determine what text would be displayed in the y-axis. In y-axis there is two part **top** and **bottom** you can pass **both** or you can pass only **bottom**. The statement should start with `y-axis` then the `bottom axis text` followed by the delimiter `-->` then `top axis text`.
+The y-axis determines what text would be displayed in the y-axis. In y-axis there is two part **top** and **bottom** you can pass **both** or you can pass only **bottom**. The statement should start with `y-axis` then the `bottom axis text` followed by the delimiter `-->` then `top axis text`.
 
 #### Example
 
@@ -102,26 +102,26 @@ Points are used to plot a circle inside the quadrantChart. The syntax is `<text>
 
 ## Chart Configurations
 
-| Parameter                         | Description                                                                                       | Default value |
-| --------------------------------- | ------------------------------------------------------------------------------------------------- | :-----------: |
-| chartWidth                        | Width of the chart                                                                                |      500      |
-| chartHeight                       | Height of the chart                                                                               |      500      |
-| titlePadding                      | Top and Bottom padding of the title                                                               |      10       |
-| titleFontSize                     | Title font size                                                                                   |      20       |
-| quadrantPadding                   | Padding outside all the quadrants                                                                 |       5       |
-| quadrantTextTopPadding            | Quadrant text top padding when text is drawn on top ( not data points are there)                  |       5       |
-| quadrantLabelFontSize             | Quadrant text font size                                                                           |      16       |
-| quadrantInternalBorderStrokeWidth | Border stroke width inside the quadrants                                                          |       1       |
-| quadrantExternalBorderStrokeWidth | Quadrant external border stroke width                                                             |       2       |
-| xAxisLabelPadding                 | Top and bottom padding of x-axis text                                                             |       5       |
-| xAxisLabelFontSize                | X-axis texts font size                                                                            |      16       |
-| xAxisPosition                     | Position of x-axis (top , bottom) if there are points the x-axis will alway be rendered in bottom |     'top'     |
-| yAxisLabelPadding                 | Left and Right padding of y-axis text                                                             |       5       |
-| yAxisLabelFontSize                | Y-axis texts font size                                                                            |      16       |
-| yAxisPosition                     | Position of y-axis (left , right)                                                                 |    'left'     |
-| pointTextPadding                  | Padding between point and the below text                                                          |       5       |
-| pointLabelFontSize                | Point text font size                                                                              |      12       |
-| pointRadius                       | Radius of the point to be drawn                                                                   |       5       |
+| Parameter                         | Description                                                                                        | Default value |
+| --------------------------------- | -------------------------------------------------------------------------------------------------- | :-----------: |
+| chartWidth                        | Width of the chart                                                                                 |      500      |
+| chartHeight                       | Height of the chart                                                                                |      500      |
+| titlePadding                      | Top and Bottom padding of the title                                                                |      10       |
+| titleFontSize                     | Title font size                                                                                    |      20       |
+| quadrantPadding                   | Padding outside all the quadrants                                                                  |       5       |
+| quadrantTextTopPadding            | Quadrant text top padding when text is drawn on top ( not data points are there)                   |       5       |
+| quadrantLabelFontSize             | Quadrant text font size                                                                            |      16       |
+| quadrantInternalBorderStrokeWidth | Border stroke width inside the quadrants                                                           |       1       |
+| quadrantExternalBorderStrokeWidth | Quadrant external border stroke width                                                              |       2       |
+| xAxisLabelPadding                 | Top and bottom padding of x-axis text                                                              |       5       |
+| xAxisLabelFontSize                | X-axis texts font size                                                                             |      16       |
+| xAxisPosition                     | Position of x-axis (top , bottom) if there are points the x-axis will always be rendered in bottom |     'top'     |
+| yAxisLabelPadding                 | Left and Right padding of y-axis text                                                              |       5       |
+| yAxisLabelFontSize                | Y-axis texts font size                                                                             |      16       |
+| yAxisPosition                     | Position of y-axis (left , right)                                                                  |    'left'     |
+| pointTextPadding                  | Padding between point and the below text                                                           |       5       |
+| pointLabelFontSize                | Point text font size                                                                               |      12       |
+| pointRadius                       | Radius of the point to be drawn                                                                    |       5       |
 
 ## Chart Theme Variables
 

docs/syntax/sankey.md

@@ -4,13 +4,12 @@
 >
 > ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/sankey.md](../../packages/mermaid/src/docs/syntax/sankey.md).
 
-# Sankey diagrams
+# Sankey diagram (v10.3.0+)
 
 > A sankey diagram is a visualization used to depict a flow from one set of values to another.
 
-::: warning
-This is an experimental diagram. Its syntax are very close to plain CSV, but it is to be extended in the nearest future.
-:::
+> **Warning**
+> This is an experimental diagram. Its syntax are very close to plain CSV, but it is to be extended in the nearest future.
 
 The things being connected are called nodes and the connections are called links.
 
@@ -19,6 +18,11 @@ The things being connected are called nodes and the connections are called links
 This example taken from [observable](https://observablehq.com/@d3/sankey/2?collection=@d3/d3-sankey). It may be rendered a little bit differently, though, in terms of size and colors.
 
 ```mermaid-example
+---
+config:
+  sankey:
+    showValues: false
+---
 sankey-beta
 
 Agricultural 'waste',Bio-conversion,124.729
@@ -92,6 +96,11 @@ Wind,Electricity grid,289.366
 ```
 
 ```mermaid
+---
+config:
+  sankey:
+    showValues: false
+---
 sankey-beta
 
 Agricultural 'waste',Bio-conversion,124.729
@@ -197,7 +206,7 @@ Electricity grid,H2 conversion,27.14
 
 ### Empty Lines
 
-CSV does not support empty lines without comma delimeters by default. But you can add them if needed:
+CSV does not support empty lines without comma delimiters by default. But you can add them if needed:
 
 ```mermaid-example
 sankey-beta

docs/syntax/sequenceDiagram.md

@@ -94,7 +94,7 @@ sequenceDiagram
     J->>A: Great!
 ```
 
-### Actor Creation and Destruction
+### Actor Creation and Destruction (v10.3.0+)
 
 It is possible to create and destroy actors by messages. To do so, add a create or destroy directive before the message.
 
@@ -131,6 +131,14 @@ sequenceDiagram
     Bob->>Alice: I agree
 ```
 
+#### Unfixable actor/participant creation/deletion error
+
+If an error of the following type occurs when creating or deleting an actor/participant:
+
+> The destroyed participant **participant-name** does not have an associated destroying message after its declaration. Please check the sequence diagram.
+
+And fixing diagram code does not get rid of this error and rendering of all other diagrams results in the same error, then you need to update the mermaid version to (v10.7.0+).
+
 ### Grouping / Box
 
 The actor(s) can be grouped in vertical boxes. You can define a color (if not, it will be transparent) and/or a descriptive label using the following notation:
@@ -164,7 +172,7 @@ The actor(s) can be grouped in vertical boxes. You can define a color (if not, i
     end
     A->>J: Hello John, how are you?
     J->>A: Great!
-    A->>B: Hello Bob, how is Charly ?
+    A->>B: Hello Bob, how is Charly?
     B->>C: Hello Charly, how are you?
 ```
 
@@ -180,7 +188,7 @@ The actor(s) can be grouped in vertical boxes. You can define a color (if not, i
     end
     A->>J: Hello John, how are you?
     J->>A: Great!
-    A->>B: Hello Bob, how is Charly ?
+    A->>B: Hello Bob, how is Charly?
     B->>C: Hello Charly, how are you?
 ```
 

docs/syntax/timeline.md

@@ -217,7 +217,7 @@ Note that there are no sections defined, and each time period and its correspond
 
 2.  Disable the multiColor option using the `disableMultiColor` option. This will make all time periods and events follow the same color scheme.
 
-You will need to add this option either via mermaid.intialize function or directives.
+You will need to add this option either via mermaid.initialize function or directives.
 
 ```javascript
 mermaid.initialize({

docs/syntax/xyChart.md

@@ -0,0 +1,188 @@
+> **Warning**
+>
+> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
+>
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/xyChart.md](../../packages/mermaid/src/docs/syntax/xyChart.md).
+
+# XY Chart
+
+> In the context of mermaid-js, the XY chart is a comprehensive charting module that encompasses various types of charts that utilize both x-axis and y-axis for data representation. Presently, it includes two fundamental chart types: the bar chart and the line chart. These charts are designed to visually display and analyze data that involve two numerical variables.
+
+> It's important to note that while the current implementation of mermaid-js includes these two chart types, the framework is designed to be dynamic and adaptable. Therefore, it has the capacity for expansion and the inclusion of additional chart types in the future. This means that users can expect an evolving suite of charting options within the XY chart module, catering to various data visualization needs as new chart types are introduced over time.
+
+## Example
+
+```mermaid-example
+xychart-beta
+    title "Sales Revenue"
+    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
+    y-axis "Revenue (in $)" 4000 --> 11000
+    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+```
+
+```mermaid
+xychart-beta
+    title "Sales Revenue"
+    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
+    y-axis "Revenue (in $)" 4000 --> 11000
+    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+```
+
+## Syntax
+
+> **Note**
+> All text values that contain only one word can be written without `"`. If a text value has many words in it, specifically if it contains spaces, enclose the value in `"`
+
+### Orientations
+
+The chart can be drawn horizontal or vertical, default value is vertical.
+
+    xychart-beta horizontal
+    ...
+
+### Title
+
+The title is a short description of the chart and it will always render on top of the chart.
+
+#### Example
+
+    xychart-beta
+        title "This is a simple example"
+        ...
+
+> **Note**
+> If the title is a single word one no need to use `"`, but if it has space `"` is needed
+
+### x-axis
+
+The x-axis primarily serves as a categorical value, although it can also function as a numeric range value when needed.
+
+#### Example
+
+1.  `x-axis title min --> max` x-axis will function as numeric with the given range
+2.  `x-axis "title with space" [cat1, "cat2 with space", cat3]` x-axis if categorical, categories are text type
+
+### y-axis
+
+The y-axis is employed to represent numerical range values, it cannot have categorical values.
+
+#### Example
+
+1.  `y-axis title min --> max`
+2.  `y-axis title` it will only add the title, the range will be auto generated from data.
+
+> **Note**
+> Both x and y axis are optional if not provided we will try to create the range
+
+### Line chart
+
+A line chart offers the capability to graphically depict lines.
+
+#### Example
+
+1.  `line [2.3, 45, .98, -3.4]` it can have all valid numeric values.
+
+### Bar chart
+
+A bar chart offers the capability to graphically depict bars.
+
+#### Example
+
+1.  `bar [2.3, 45, .98, -3.4]` it can have all valid numeric values.
+
+#### Simplest example
+
+The only two things required are the chart name (`xychart-beta`) and one data set. So you will be able to draw a chart with a simple config like
+
+    xychart-beta
+        line [+1.3, .6, 2.4, -.34]
+
+## Chart Configurations
+
+| Parameter                | Description                                    | Default value |
+| ------------------------ | ---------------------------------------------- | :-----------: |
+| width                    | Width of the chart                             |      700      |
+| height                   | Height of the chart                            |      500      |
+| titlePadding             | Top and Bottom padding of the title            |      10       |
+| titleFontSize            | Title font size                                |      20       |
+| showTitle                | Title to be shown or not                       |     true      |
+| xAxis                    | xAxis configuration                            |  AxisConfig   |
+| yAxis                    | yAxis configuration                            |  AxisConfig   |
+| chartOrientation         | 'vertical' or 'horizontal'                     |  'vertical'   |
+| plotReservedSpacePercent | Minimum space plots will take inside the chart |      50       |
+
+### AxisConfig
+
+| Parameter     | Description                          | Default value |
+| ------------- | ------------------------------------ | :-----------: |
+| showLabel     | Show axis labels or tick values      |     true      |
+| labelFontSize | Font size of the label to be drawn   |      14       |
+| labelPadding  | Top and Bottom padding of the label  |       5       |
+| showTitle     | Axis title to be shown or not        |     true      |
+| titleFontSize | Axis title font size                 |      16       |
+| titlePadding  | Top and Bottom padding of Axis title |       5       |
+| showTick      | Tick to be shown or not              |     true      |
+| tickLength    | How long the tick will be            |       5       |
+| tickWidth     | How width the tick will be           |       2       |
+| showAxisLine  | Axis line to be shown or not         |     true      |
+| axisLineWidth | Thickness of the axis line           |       2       |
+
+## Chart Theme Variables
+
+> **Note**
+> Themes for xychart resides inside xychart attribute so to set the variables use this syntax
+> %%{init: { "themeVariables": {"xyChart": {"titleColor": "#ff0000"} } }}%%
+
+| Parameter        | Description                                               |
+| ---------------- | --------------------------------------------------------- |
+| backgroundColor  | Background color of the whole chart                       |
+| titleColor       | Color of the Title text                                   |
+| xAxisLableColor  | Color of the x-axis labels                                |
+| xAxisTitleColor  | Color of the x-axis title                                 |
+| xAxisTickColor   | Color of the x-axis tick                                  |
+| xAxisLineColor   | Color of the x-axis line                                  |
+| yAxisLableColor  | Color of the y-axis labels                                |
+| yAxisTitleColor  | Color of the y-axis title                                 |
+| yAxisTickColor   | Color of the y-axis tick                                  |
+| yAxisLineColor   | Color of the y-axis line                                  |
+| plotColorPalette | String of colors separated by comma e.g. "#f3456, #43445" |
+
+## Example on config and theme
+
+```mermaid-example
+---
+config:
+    xyChart:
+        width: 900
+        height: 600
+    themeVariables:
+        xyChart:
+            titleColor: "#ff0000"
+---
+xychart-beta
+    title "Sales Revenue"
+    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
+    y-axis "Revenue (in $)" 4000 --> 11000
+    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+```
+
+```mermaid
+---
+config:
+    xyChart:
+        width: 900
+        height: 600
+    themeVariables:
+        xyChart:
+            titleColor: "#ff0000"
+---
+xychart-beta
+    title "Sales Revenue"
+    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
+    y-axis "Revenue (in $)" 4000 --> 11000
+    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+```