Why this page exists
Session 3 gave you graph TD; A-->B; and moved on - there was a page to ship. But Mermaid is a full diagram language living inside a markdown fence, and the difference between a basic flowchart and a great one is a handful of learnable marks. This page is the vocabulary lesson: shapes, arrows, directions, and three whole new diagram types.
Flowchart fluency: shapes, arrows, directions 7 min read
Everything on this page lives inside the Session 3 fence: ```mermaid ... ```. What changes is your vocabulary inside it.
Self-studyFour directions: which way does it flow?2 min▶
Three boxes flowing left to right: Draft → Review → Ship. Change LR to TD and the same three boxes stack top-down instead - one code, any direction.
- The four codes: TD top-down (Session 3's default, same as TB), BT bottom-to-top, LR left-to-right, RL right-to-left.
- Pick by content: timelines and pipelines read best LR; hierarchies and decisions read best TD. In a README, LR fits wide screens; TD survives narrow phones better.
- flowchart vs graph: flowchart is the current keyword; the older graph from Session 3 still works. Either is fine on GitHub.
Self-studySix node shapes, each with a meaning3 min▶
Six differently-shaped nodes: a rectangle, a rounded rectangle, a stadium (pill), a circle, a diamond, and a cylinder. The brackets around the label ARE the shape.
- The convention readers already know: rectangle [x] = process step, stadium ([x]) = start/end, diamond {x} = decision with yes/no exits, cylinder [(x)] = data store, circle ((x)) = connector or hub, rounded (x) = a gentler step.
- Memory hook: the code looks like the shape - curly braces pinch like a diamond, double parens are round, [( )] is a box with a curved lid.
- Use meaningfully, not decoratively: one diagram, one shape language. A diamond that isn't a decision just confuses people.
Self-studyArrow styles, labels, and subgraphs3 min▶
Draft and Final sit together inside a labeled box called Writing. A thick arrow leads to the Publish? diamond, a dotted "not yet" arrow loops back to Draft, and a plain line (no arrowhead) ties the diamond to the Archive cylinder. The |labels| ride on their arrows.
- Four link styles: --> normal arrow, --- plain line, -.-> dotted (the "maybe/sometimes" arrow), ==> thick (the happy path).
- Labels: A -->|yes| B - pipes right after the arrow. Decision diamonds practically demand labeled exits.
- Subgraphs: subgraph Name ... end draws a titled box around related nodes - phases, teams, systems. Nesting works; one level is usually plenty.
Beyond flowcharts: three more types GitHub renders 6 min read
The first line inside the fence declares the diagram type. GitHub renders the standard Mermaid set at whatever Mermaid version it currently ships (Part 3 shows how to check it) - these three are the ones you'll reach for most.
Self-studySequence diagrams: who talks to whom2 min▶
Two vertical lifelines labeled You and GitHub, with horizontal message arrows between them, in order, top to bottom: "push README.md" going right, "renders your page" coming back.
- The grammar: participant Name declares each actor; A->>B: message draws one arrow with its text. Order on the page = order in time.
- When it beats a flowchart: anything that's a conversation - API calls, approval chains, "then the form emails the manager". Flowcharts show logic; sequences show dialogue over time.
Self-studyPie charts: proportions in four lines2 min▶
A titled pie chart with three colored slices and a legend - Building the biggest slice, then Meetings, then Learning. Mermaid computes the percentages for you.
- The grammar: pie title Text, then one "label" : value per line. Values are any numbers; slices are proportional.
- README-worthy uses: a skills mix, how a project's time went, language breakdown - light data, zero chart tooling.
Self-studyGantt charts: plans on a timeline2 min▶
A timeline chart titled Page relaunch with a Content section: a three-day Draft bar starting July 13, and a two-day Review bar that begins right where Draft ends - after a1 chains them automatically.
- The grammar: gantt + title + dateFormat, then section headers with one task per line: name, an id, a start (a date or after otherId), a duration like 3d.
- Perfect for: a project README's plan section - the plan lives next to the code and updates with a text edit, not a screenshot re-export.
The Mermaid workflow: draft, check, commit 4 min read
Typing diagram code straight into a README commit is flying blind. The pros use a three-step loop.
Self-studyDraft at mermaid.live, verify the version, then commit3 min▶
- 1 · Draft in the playground: mermaid.live is the official live editor - code on the left, diagram on the right, errors flagged as you type. Iterate there, paste the finished code into your fence. It's StackEdit for diagrams.
- 2 · Check GitHub's version: a fence containing just the word info with the mermaid language tag renders a block reporting the Mermaid version GitHub currently runs. If a shiny new feature from the docs won't render, compare versions before debugging your syntax - the playground may be newer than GitHub.
- 3 · Commit and preview: paste into your README inside ```mermaid ... ```, use GitHub's Preview tab before committing - the Session 4 muscle memory.
Self-studyWhen a diagram beats a paragraph (and when it doesn't)2 min▶
- Diagram wins: branching logic ("if approved, then..."), anything with more than three arrows of flow, conversations between systems, timelines. If your paragraph keeps saying "then" and "otherwise", it wants to be a flowchart.
- Paragraph wins: linear explanations, nuance, anything needing more than a label's worth of words per step. A five-node diagram whose nodes hold full sentences is a paragraph in boxes - worse than either.
- The README test: one good diagram near the top of a project README ("how the pieces fit") earns its place forever. A diagram per section is decoration. Deep config and theming exist in Mermaid for when you truly need them - mermaid.js.org covers that layer; it's linked, not taught, here.
Upgrade your Session 3 diagram ◐ 15 min hands-on
Open mermaid.live and paste in your profile README's journey diagram from Session 3 (or start from flowchart LR with three nodes if you skipped it).
Add one decision: a diamond node like D{Keep learning?} with two labeled exits - D -->|yes| next and a dotted -.-> loop back for "revisit".
Group the finished chapters in a subgraph Done ... end box. Watch the playground redraw as you type; fix errors while they're one keystroke old.
Paste the upgraded code back into your README's mermaid fence, check the Preview tab, and commit. Your live page just got measurably smarter - that's the project growing again.
Three questions before you go 🎯 ◐ 90 seconds
1 · Your flowchart should read left to right. Which first line?
LR = left to right. TD stacks top-down, BT climbs bottom-to-top, RL flows right-to-left - four codes, one habit.
2 · Which node syntax draws a decision diamond?
Curly braces pinch like a diamond. Square brackets = rectangle step, double parens = circle, ([x]) = start/end stadium, [(x)] = database cylinder.
3 · How do you check which Mermaid version GitHub currently renders?
The info block is the built-in version check - compare it against mermaid.live before assuming a new feature will render in your README.
Official sources covered
This page teaches the beginner-relevant working content of the syntax docs at mermaid.js.org and GitHub's guide to creating diagrams.