Block diagram
A block diagram is composed of blocks and connectors to visually represent complex systems, processes, or architectures. Blocks represent basic components or functions, and connectors show the relationships or flows between these components; block diagrams are essential in various fields such as engineering, software development, and process management.
Copy
Embed
block-beta
columns 1
db(("DB"))
blockArrowId6<[" "]>(down)
block:ID
A
B["A wide one in the middle"]
C
end
space
D
ID --> D
C --> D
style B fill:#f96,stroke:#333,stroke-width:4px
Uses of block diagrams
The main purpose of a block diagram is to provide a high-level view of a system, enabling people to easily understand and analyze it without delving into the complex details of each component. This makes block diagrams especially useful for simplifying complex systems and for explaining the overall structure and interactions of the components within a system.
Usage scenarios
Block diagrams have a wide range of applications across industries and disciplines, mainly including:
- Software architecture: in software development, block diagrams can be used to illustrate the architecture of a software application. This includes showing how the various modules or services interact, data flow, and high-level component interactions.
- Network topology: block diagrams are well suited to representing network architectures in IT and telecommunications. They can show how different network devices and services connect to each other, including routers, switches, firewalls, and the flow of data through the network.
- Process flow: in business and manufacturing, block diagrams can be used to create flowcharts. These flowcharts represent the various stages of a business or manufacturing process and help visualize the sequence of steps, decision points, and control flow.
- Electrical systems: engineers use block diagrams to represent electrical systems and circuits. They can illustrate the high-level structure of an electrical system, the interactions between different electrical components, and the flow of current.
- Educational purposes: block diagrams are also widely used in educational materials to explain complex concepts and systems in a simplified way. Block diagrams help break down and visualize scientific theories, engineering principles, and technical systems.
Next, we will take a deep dive into how to create and work with block diagrams using Mermaid, covering everything from basic syntax to advanced configuration and styling.
Simple block diagram
Basic structure
A block diagram is composed of blocks that represent different entities or components, and in Mermaid blocks can be created easily using simple text labels. The most basic form of a block diagram can be a series of blocks without any connecting lines.
Simple block diagram example: to create a simple block diagram containing three blocks labeled a, b, and c, the syntax is as follows:
Copy
Embed
block-beta
a b c
This code generates three horizontally arranged blocks, each automatically spaced and aligned for optimal readability.
Define the number of columns to use
Multi-column diagram
Although a simple block diagram is linear and simple, more complex systems may require a structured layout. Mermaid allows blocks to be organized into multiple columns, which helps create more complex and more detailed diagrams.
Multi-column diagram example: when blocks need to be distributed across multiple columns, the number of columns can be specified and the blocks arranged accordingly. The following shows how to create a block diagram with three columns and four blocks, where the fourth block appears on the second row:
Copy
Embed
block-beta
columns 3
a b c d
With this syntax, Mermaid arranges blocks a, b, c, and d into three columns and wraps to the next row as needed. This feature is especially useful for representing hierarchical or multi-layered systems.
Advanced block configuration
Mermaid's advanced syntax gives diagram design greater flexibility and complexity, accommodating a wider range of use cases and scenarios.
Adjusting block width
Spanning multiple columns
In more complex diagrams, you may need blocks that span multiple columns to emphasize certain components or represent larger entities. Mermaid allows the block width to be adjusted to cover multiple columns, thereby enhancing the readability and structure of the diagram.
Example: to create a block that spans two columns, you can specify the desired width for each block:
Copy
Embed
block-beta
columns 3
a["A label"] b:2 c:2 d
In this example, the block labeled A label occupies one column, while blocks b and c span 2 columns, and d is assigned to its own column. This flexibility in block size is essential for accurately representing systems with components of different importance or size.
Creating composite blocks
Nested blocks
Composite blocks allow representing nested or hierarchical systems, in which one component contains multiple sub-components.
Example: creating a composite block involves defining a parent block and then nesting child blocks within it. The following is the syntax for defining a composite block with nested elements:
Copy
Embed
block-beta
block
D
end
A["A: I am a wide one"]
In this syntax, D is a child block nested within a larger parent block. This feature is especially useful for describing complex structures, such as a server with multiple services or a department within a larger organizational framework.
Automatic column width
Adjusting width
Mermaid allows the column width to be adjusted dynamically based on the content of the blocks. The width of a column is determined by the widest block in the column, ensuring the diagram stays balanced and readable.
Example: in a diagram with blocks of different sizes, Mermaid automatically adjusts the column width to fit the largest block in each column.
Copy
Embed
block-beta
columns 3
a:3
block:group1:2
columns 2
h i j k
end
g
block:group2:3
%% columns auto (default)
l m n o p q r
end
This demonstrates how Mermaid dynamically adjusts the width of a column to fit the widest block.
Horizontally merging blocks: when blocks need to be stacked horizontally, this can be accomplished using column width. The following is the syntax for a block diagram that creates 4 blocks stacked together:
Copy
Embed
block-beta
block
columns 1
a["A label"] b c d
end
In this example, the width of the merged block is automatically adjusted to the width of the largest child block.
Block types and shapes
Mermaid block diagrams are not limited to standard rectangular shapes. Mermaid provides a variety of block shapes, allowing for a more nuanced and personalized representation of different types of information or entities.
Standard block shapes
Rounded rectangle
Creates a rounded rectangle box, which can be used to represent a softer or more flexible component:
Copy
Embed
block-beta
id1("This is the text in the box")
Stadium shape
A stadium-shaped block can be used to represent a process-oriented component:
Copy
Embed
block-beta
id1(["This is the text in the box"])
Subprocess shape
Used to represent a subprocess or an included process, represented by a rectangular block with double vertical lines:
Copy
Embed
block-beta
id1[["This is the text in the box"]]
Cylinder
A cylinder is very suitable for representing a database or storage component:
Copy
Embed
block-beta
id1[("Database")]
Circle
A circle can be used to represent a centralized or critical component:
Copy
Embed
block-beta
id1(("This is the text in the circle"))
Asymmetric shape, diamond, and hexagon
Use a diamond for decisions; for unique or specialized processes, you can use asymmetric and hexagonal shapes:
Asymmetric shape
Copy
Embed
block-beta
id1>"This is the text in the box"]
Copy
Embed
block-beta
id1{"This is the text in the box"}
Copy
Embed
block-beta
id1{{"This is the text in the box"}}
Parallelogram and trapezoid
Parallelograms and trapezoids are very suitable for input/output and transition processes
Copy
Embed
block-beta
id1[/"This is the text in the box"/]
id2["This is the text in the box"]
A[/"Christmas"]
B["Go shopping"/]
Double circle
To highlight critical or high-priority components, using a double circle can be very effective:
Copy
Embed
block-beta
id1((("This is the text in the circle")))
Arrow blocks and empty blocks
Arrow block
Block arrows can visually show the direction or flow within a process:
Copy
Embed
block-beta
blockArrowId<["Label"]>(right)
blockArrowId2<["Label"]>(left)
blockArrowId3<["Label"]>(up)
blockArrowId4<["Label"]>(down)
blockArrowId5<["Label"]>(x)
blockArrowId6<["Label"]>(y)
blockArrowId6<["Label"]>(x, down)
Empty block
Empty blocks can be used to create blank space, which is useful for layout and readability:
Copy
Embed
block-beta
columns 3
a space b
c d e
Copy
Embed
block-beta
ida space:3 idb idc
Note that you can use the numeric symbol space:num to set the number of columns an empty block occupies, where num represents the column width. You can also use space, which defaults to one column.
The standard shapes and special shapes in Mermaid enhance the expressive power of block diagrams, enabling more accurate and more contextual representation.
Connecting blocks with lines
A key feature of Mermaid block diagrams is the ability to connect the individual blocks using various types of lines or links.
Basic connections and arrow types
Connecting blocks requires arrows or lines. These connectors describe the relationships or information flow between blocks. Mermaid provides a range of arrow types to meet different diagramming needs.
Basic links
Create a simple link with an arrow that shows the direction or flow from one block to another:
Copy
Embed
block-beta
A space B
A-->B
This example illustrates a direct connection from block A to block B.
Text on links
Besides connecting blocks, it is often necessary to describe or label the relationship. Mermaid allows text to be added to links to provide context for the link.
To add text to a link, the syntax is to include that text in the link definition:
Copy
Embed
block-beta
A space:2 B
A-- "X" -->B
Copy
Embed
block-beta
columns 1
db(("DB"))
blockArrowId6<[" "]>(down)
block:ID
A
B["A wide one in the middle"]
C
end
space
D
ID --> D
C --> D
style B fill:pink,stroke:#333,stroke-width:4px
Styles and customization
In addition to the structure and layout of a block diagram, Mermaid also provides a large number of styling options; these customization features allow you to create more visually distinctive and informative diagrams.
Individual block style
Mermaid can apply detailed styling to individual blocks, and you can apply various CSS properties, such as color, stroke, and border thickness.
Customizing the style of an individual block
To apply a custom style to a block, you can use the style syntax, followed by the block identifier and the desired CSS properties:
Copy
Embed
block-beta
id1 space id2
id1("Start")-->id2("Stop")
style id1 fill:pink,stroke:#333,stroke-width:4px
style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
Class style
Mermaid supports applying styles to classes. If you want to apply a specific set of styles to multiple elements, using style settings may be easier, because you only need to link these elements to a class.
Setting a style for a single class
Copy
Embed
block-beta
A space B
A-->B
classDef blue fill:pink,stroke:#333,stroke-width:4px;
class A blue
style B fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
Here, a class named blue is defined and applied to block A, while block B receives a separate style.
Use cases
When Mermaid block diagrams are applied to real scenarios, their versatility is fully demonstrated.
Detailed examples of various features
Through structural, linking, and styling elements, we can create Mermaid block diagrams that play specific roles in different contexts.
System architecture
The following is a simple software system architecture with interconnected components:
Copy
Embed
block-beta
columns 3
Frontend blockArrowId6<[" "]>(right) Backend
space:2 down<[" "]>(down)
Disk left<[" "]>(left) Database[("Database")]
classDef front fill:pink,stroke:#333;
classDef back fill:#f96,stroke:#333;
class Frontend front
class Backend,Database back
This example shows a basic architecture containing a frontend, a backend, and a database, with each block presented differently to distinguish the different component types.
Business process
The following is a business process with decision points and multiple stages:
Copy
Embed
block-beta
columns 3
Start(("Start")) space:2
down<[" "]>(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:pink;
style End fill:pink;
These real-world cases highlight the practical value of Mermaid block diagrams in simplifying complex information and enabling effective cross-domain communication.
Troubleshooting
Creating complex block diagrams with Mermaid syntax can sometimes be challenging; common syntax errors are listed here, along with tips for managing more complex diagram structures.
Common syntax errors
Avoiding common syntax errors is key to using Mermaid block diagrams smoothly.
Link error
Using incorrect link syntax may lead to unexpected results or broken diagrams:
Copy
Embed
block-beta
A - B
Correction: make sure to use arrow connections (--> or ---) correctly between blocks to define the direction and type of the connection. In addition, one of the basic principles of block diagrams is to give the author full control over the position of the blocks, so in the case above, spaces need to be added between the blocks:
Copy
Embed
block-beta
A space B
A --> B
Style misalignment
Applying styles in the wrong context or with incorrect syntax may result in the styling not being applied as expected:
Copy
Embed
block-beta
A
style A fillpink;
Correction: make sure style properties are correctly separated by commas, and use the correct CSS property format to fix the syntax:
Copy
Embed
block-beta
A
style A fill:pink,stroke:#333;
