A diagram that stays in the document
Mermaid describes diagrams as text. A few named nodes and arrows can describe a workflow; messages between participants can describe a sequence. Put that text inside a fenced code block labelled mermaid, and a supporting editor can render the diagram.
Beauty renders Mermaid in the page while preserving the fence in the Markdown file. Your diagram source travels with the explanation. You can revise a label without finding a separate drawing, and someone reading the raw file can still inspect the relationships.
This works well for small system explanations, an editorial workflow, a request moving through services, or a decision you want to document clearly.
Write your first flowchart
Create a fenced block with mermaid as its language. Add the following source inside it:
flowchart LR Idea --> Draft Draft --> Review Review --> Share
flowchart LR asks for a flowchart arranged from left to right. Each arrow connects two nodes. Names used in more than one line refer to the same node, which is how a series of short statements becomes a connected diagram.
The animation above arranges the same connections to fit the illustration. A Mermaid renderer chooses the actual layout from the source, available space, and its layout rules. The important information is the sequence of connections.
Give nodes labels your reader will recognize. “Check payment” says more than “Step 3.” Keep a diagram focused on one question; a second small diagram is often easier to read than one containing every detail.
Describe a conversation with a sequence
A sequence diagram is useful when timing and participants matter more than the shape of a workflow. Put this source in another mermaid fence:
sequenceDiagram participant Reader participant Editor Reader->>Editor: Open a note Editor-->>Reader: Show the document Reader->>Editor: Continue writing
The participant declarations name the columns. The messages explain what happens between them. Begin with the ordinary path before adding branches or failure cases; readers need to understand the main conversation first.
Keep the explanation beside the diagram
A diagram should answer a question in the surrounding document. Introduce what the reader is looking at, then explain a connection that could be misunderstood. A diagram of a save workflow, for example, should say whether “saved” means a local write or a completed sync.
Use headings to separate the context, the diagram, and the consequences. A short Markdown table can record responsibilities or tradeoffs beside a flowchart without adding more nodes to it.
Check the destination before sharing
Mermaid is an extension, not a feature of every Markdown renderer. A tool without Mermaid support may display the fence as code. The source is preserved, but the picture depends on a supporting renderer.
For editable technical notes, send the Markdown source. For a finished document, export it and inspect the diagram in the result before sharing. Large diagrams may need a simpler layout to remain readable on a page.
Beauty also supports code blocks, formulas, and visual table editing. Together, those let a technical explanation remain a readable document with a portable text source.