Diagrams you write instead of draw
Mermaid turns text into diagrams. A few names and arrows become a flowchart; a list of messages becomes a sequence diagram. Put that text in a code block labelled mermaid and an editor that supports it draws the picture.
Beauty renders the diagram right on the page and keeps the source in your Markdown file. Rename a step by editing one word, no drawing app required. Anyone reading the raw file can still follow the logic.
It is perfect for explaining how a system works, mapping out a process, showing a request moving between services, or documenting a decision.
Your first flowchart in four lines
Create a code block with mermaid as the language and paste this in:
flowchart LR Idea --> Draft Draft --> Review Review --> Share
flowchart LR means a flowchart that reads left to right. Each arrow connects two boxes. Reuse a name and Mermaid treats it as the same box, which is how a few short lines become a connected diagram.
The animation above arranges the boxes to fit the page. In a real note, Mermaid picks the layout based on your source and the available space. What matters is the connections.
Use labels your reader will recognize: "Check payment" beats "Step 3." And keep each diagram to one idea. Two small diagrams almost always read better than one that tries to show everything.
Show who talks to whom with a sequence diagram
When the order of events matters more than the overall shape, use a sequence diagram. Put this in another mermaid block:
sequenceDiagram participant Reader participant Editor Reader->>Editor: Open a note Editor-->>Reader: Show the document Reader->>Editor: Continue writing
Each participant becomes a column, and each line is a message between them. Start with the happy path; add error cases and branches once the main flow is clear.
Explain the diagram, don't just drop it in
A diagram should answer a question the text raises. Say what the reader is looking at, then call out anything easy to misread. In a diagram of saving, for example, say whether "saved" means written to disk or fully synced.
Use headings to separate the context, the diagram, and what it means. A small Markdown table is a great place for responsibilities or trade-offs, so the flowchart does not have to carry them.
Before you share
Mermaid is an extension, and not every Markdown app supports it. Elsewhere, your diagram may show up as a plain code block. The source is safe, but the picture needs a Mermaid-aware renderer.
Sending technical notes to someone who will edit them? Send the Markdown. Sending a finished document? Export it and check the diagram looks right first. Very large diagrams may need simplifying to fit a page.
Beauty also handles code blocks, math formulas, and visual table editing, so a whole technical write-up can live in one readable Markdown file.