#3358 Doc updates after viewing the page

2025-09-24 17:59:39 +02:00 · 2024-01-18 18:03:37 +01:00
parent bf64509216
commit d075766760
9 changed files with 297 additions and 528 deletions
--- a/packages/mermaid/src/docs/syntax/block.md
+++ b/packages/mermaid/src/docs/syntax/block.md
@@ -5,7 +5,24 @@ outline: 'deep' # shows all h3 headings in outline in Vitepress

 # Block Diagrams Documentation

-## 1. Introduction to Block Diagrams
+## Introduction to Block Diagrams
+
+```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:#969,stroke:#333,stroke-width:4px
+```

 ### Definition and Purpose

@@ -13,6 +30,8 @@ Block diagrams are an intuitive and efficient way to represent complex systems,

 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.

+Many people use mermaid flowcharts for this purpose. A side-effect of this is that the automatic layout sometimes move shapes to positions that the diagram maker does not want. Block diagrams use a different approach. In this diagram we give the author full control over where the shapes are positioned.
+
 ### General Use Cases

 Block diagrams have a wide range of applications across various industries and disciplines. Some of the key use cases include:
@@ -145,7 +164,7 @@ To create a block with round edges, which can be used to represent a softer or m

 ```mermaid-example
 block-beta
-    id1(This is the text in the box)
+    id1("This is the text in the box")
 ```

 #### Example - Stadium-Shaped Block
@@ -154,7 +173,7 @@ A stadium-shaped block, resembling an elongated circle, can be used for componen

 ```mermaid-example
 block-beta
-    id1([This is the text in the box])
+    id1(["This is the text in the box"])
 ```

 #### Example - Subroutine Shape
@@ -163,7 +182,7 @@ For representing subroutines or contained processes, a block with double vertica

 ```mermaid-example
 block-beta
-    id1[[This is the text in the box]]
+    id1[["This is the text in the box"]]
 ```

 #### Example - Cylindrical Shape
@@ -172,7 +191,7 @@ The cylindrical shape is ideal for representing databases or storage components:

 ```mermaid-example
 block-beta
-    id1[(Database)]
+    id1[("Database")]
 ```

 #### Example - Circle Shape
@@ -181,7 +200,7 @@ A circle can be used for centralized or pivotal components:

 ```mermaid-example
 block-beta
-    id1((This is the text in the circle))
+    id1(("This is the text in the circle"))
 ```

 #### Example - Asymmetric, Rhombus, and Hexagon Shapes
@@ -192,21 +211,21 @@ For decision points, use a rhombus, and for unique or specialized processes, asy

 ```mermaid-example
 block-beta
-  id1>This is the text in the box]
+  id1>"This is the text in the box"]
 ```

 **Rhombus**

 ```mermaid-example
 block-beta
-    id1{This is the text in the box}
+    id1{"This is the text in the box"}
 ```

 **Hexagon**

 ```mermaid-example
 block-beta
-    id1{{This is the text in the box}}
+    id1{{"This is the text in the box"}}
 ```

 #### Example - Parallelogram and Trapezoid Shapes
@@ -215,10 +234,10 @@ Parallelogram and trapezoid shapes are perfect for inputs/outputs and transition

 ```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/]
+  id1[/"This is the text in the box"/]
+  id2[\"This is the text in the box"\]
+  A[/"Christmas"\]
+  B[\"Go shopping"/]
 ```

 #### Example - Double Circle
@@ -227,7 +246,7 @@ For highlighting critical or high-priority components, a double circle can be ef

 ```mermaid-example
 flowchart TD
-    id1(((This is the text in the circle)))
+    id1((("This is the text in the circle")))
 ```

 ### Block Arrows and Space Blocks
@@ -281,6 +300,7 @@ A simple link with an arrow can be created to show direction or flow from one bl

 ```mermaid-example
 block-beta
+  A space B
  A-->B
 ```

@@ -291,6 +311,7 @@ For connections that are less direct or to represent a different type of relatio

 ```mermaid-example
 block-beta
+  A space B
  A --- B
 ```

@@ -305,7 +326,8 @@ 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
+  A space:2 B
+  A-- "X" -->B
 ```

 This example show how to add descriptive text to the links, enhancing the information conveyed by the diagram.
@@ -319,16 +341,10 @@ A dotted link can be used to represent a weaker or less formal relationship:

 ```mermaid-example
 block-beta
+  A space:2 B
  A-.->B
 ```

-For a more pronounced connection, a thick link can be used:
-
-```mermaid-example
-block-beta
-  A==>B
-```
-
 Example - Edges and Styles:

 ```mermaid-example
@@ -345,7 +361,7 @@ columns 1
  D
  ID --> D
  C --> D
-  style B fill:#f9F,stroke:#333,stroke-width:4px
+  style B fill:#939,stroke:#333,stroke-width:4px
 ```

 ## 6. Styling and Customization
@@ -362,8 +378,9 @@ To apply custom styles to a block, you can use the `style` keyword followed by t

 ```mermaid-example
 block-beta
-  id1(Start)-->id2(Stop)
-  style id1 fill:#f9f,stroke:#333,stroke-width:4px
+  id1 space id2
+  id1("Start")-->id2("Stop")
+  style id1 fill:#636,stroke:#333,stroke-width:4px
  style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
 ```

@@ -385,13 +402,15 @@ Illustrating a simple software system architecture with interconnected component

 ```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;
+  columns 3
+  Frontend blockArrowId6<["&nbsp;&nbsp;"]>(right) Backend
+  space:2 down<["&nbsp;&nbsp;"]>(down)
+  Disk left<["&nbsp;&nbsp;"]>(left) Database[("Database")]
+
+  classDef front fill:#696,stroke:#333;
+  classDef back fill:#969,stroke:#333;
+  class Frontend front
+  class Backend,Database back
 ```

 This example shows a basic architecture with a frontend, backend, and database. The blocks are styled to differentiate between types of components.
@@ -402,24 +421,21 @@ 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;
+  columns 3
+  Start(("Start")) space:2
+  down<["&nbsp;&nbsp;"]>(down) space:2
+  Decision{{"Make Decision"}} right<["Yes"]>(right) Process1["Process A"]
+  downAgain<["No"]>(down) space r3<["Done"]>(down)
+  Process2["Process B"] r2<["Done"]>(right) End(("End"))
+
+  style Start fill:#969;
+  style End fill:#696;

 ```

 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
+### Real world Scenarios

 Block diagrams can be employed in a variety of real-world scenarios. Here are a few examples:

@@ -431,14 +447,6 @@ These practical examples and scenarios underscore the utility of Mermaid block d

 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-example
-
-```
-
 ## 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.
@@ -457,10 +465,11 @@ block-beta
 ```

 **Correction**:
-Ensure that links between blocks are correctly specified with arrows (--> or ---) to define the direction and type of connection:
+Ensure that links between blocks are correctly specified with arrows (--> or ---) to define the direction and type of connection. Also rememeber that one of the fundaments for block diagram is to give the author full control of where the boxes are positioned so in the example you need to add a space between the boxes:

 ```mermaid-example
 block-beta
+  A space B
  A --> B
 ```

@@ -471,7 +480,7 @@ Applying styles in the wrong context or with incorrect syntax can lead to blocks
 ```mermaid-example
  block-beta
    A
-    style A fill#f9f;
+    style A fill#969;
 ```

 **Correction:**
@@ -480,7 +489,7 @@ Correct the syntax by ensuring proper separation of style properties with commas
 ```mermaid-example
 block-beta
  A
-  style A fill:#f9f,stroke:#333;
+  style A fill:#969,stroke:#333;

 ```