How to build an org chart mermaid diagram

An org chart mermaid file is a flowchart drawn top to bottom, where each arrow is a reporting line. You can sketch the same teams as a mindmap when you don't need reporting lines at all. Don't put photos in it, and don't put HTML in it. The chart is text. That's the feature.

I keep a version of this in the repo because the one in the wiki is a slide, and the slide still shows a manager who left in March. The slide looks better than my flowchart. The flowchart is the one I can edit in the same pull request as the team change. I'll take the ugly one.

Reporting lines are arrows

flowchart TD is the whole layout decision. Top-down matches the way people already read an org chart: the boss above, the reports below. Left-to-right makes it look like a pipeline, and then someone asks which team "hands off" to which. They don't. They report.

The arrow points from the manager to the report. ceo --> eng means engineering reports to the CEO. I tried the other direction once, because a dependency graph points at the thing it needs, and a report "needs" a manager. Everyone read it as the CEO reporting to engineering. Arrows in an org chart are not dependencies. Pick down, write it in a sentence under the figure, and don't get clever.

Node ids are short and stable. eng, product, finance. Labels are the words on the box: eng[Engineering]. When the team renames itself from "Platform" to "Infrastructure," you change the label and keep the id. Every arrow still lands. If the id and the label are the same long title, a rename edits every line, and the diff looks like a reorg when it was a rebrand. I've made that diff. Reviewers asked if three teams had moved. They had not.

The flowchart syntax page documents shapes, subgraphs, and edge styles. An org chart barely uses them. Rectangles and solid arrows are enough. A diamond is a decision, and a reporting line is not a decision. Don't make the CEO a diamond because you want the box to look important. Importance is not a shape.

A small company, top to bottom

This is a fictional chart for a company that fits on one screen. The names are roles, not people. People change, and a chart full of legal names goes stale the week someone leaves. Roles go stale too, but they go stale when the structure changes, which is the event you wanted the chart to track.

flowchart TD
  ceo[CEO] --> eng[Engineering]
  ceo --> product[Product]
  ceo --> finance[Finance]
  eng --> backend[Backend]
  eng --> frontend[Frontend]
  product --> research[Research]
  product --> design[Design]
  finance --> payroll[Payroll]
  finance --> close[Monthly close]

Read it as nine claims. Engineering, product, and finance report to the CEO. Backend and frontend report to engineering. Research and design report to product. Payroll and monthly close report to finance. There is no arrow from design to engineering. They work together. Working together is not a reporting line. I used to add a dotted arrow for "collaborates," and then nobody could tell whether design had two bosses. If it isn't a reporting line, it doesn't belong on this chart.

A dotted arrow is available in the syntax, and it's the right tool for a real matrix: a person with a solid-line manager and a dotted-line manager. Use it only when both lines are actual reporting, with two people who can assign work. Use it for nothing else. A dotted line that means "we chat" trains readers to ignore dotted lines, and then the real matrix is invisible. I made that mess on a chart that had fourteen dotted arrows. We deleted all of them in one commit and the chart finally matched the offer letters.

Keep labels to a team or a role. "Backend, currently three people, hiring" is a status report. It will be wrong next month, and it will still be in the picture. Headcount belongs in a sentence under the figure or in the HR system. The chart that tries to be the HR system becomes a chart nobody updates.

Subgraphs are tempting as "divisions." A box around engineering and its two teams repeats the arrows. Skip it until you have two reporting trees that a reader could mix up. Then a subgraph is a visual boundary, still not a third kind of management. Don't give the subgraph an id of end. That word closes the box. Name it division or skip the box.

Photos and HTML are how the chart dies

Mermaid will not reliably put a face in a node, and this workflow shouldn't try. An HTML image tag inside a label is HTML. It shows up as text, or it breaks the node, and it definitely doesn't belong in a repo diagram. I pasted an image tag into a node because a template from another tool did that. The preview showed the tag. The git history showed a URL with an access token in it, which was worse than the ugly box. Strip that instinct out.

Photos go stale in a specific way text doesn't. Someone leaves, the photo stays, and the chart becomes a memorial that still assigns them reports. A role label doesn't smile, and it doesn't pretend the person is still here. If you need faces, use the HR tool. Link it under the figure. Don't embed it.

Colors have the same problem at a smaller scale. Painting engineering blue and product green feels like design and communicates nothing unless you also maintain a legend. The legend drifts. A new team gets no color, and readers think the missing color means something. Leave the default theme. If two nodes are easy to confuse, their labels are too similar. Rename them. Don't recolor them.

The same rule kills icons you downloaded as SVG sprites and pasted into labels. The org chart's job is the lines. A custom icon font that one preview can see is a portability bug. The mindmap syntax won't save you here either. It also doesn't take a portrait. Good.

A mindmap when you don't need bosses

Sometimes the question is "what teams exist and what sits inside them," and a reporting line would be a guess. A mindmap has no arrows. Indent is the only relationship. That's the right picture for an onboarding note that lists where work happens, and the wrong picture for who approves time off.

mindmap
  root((Company))
    Engineering
      Backend
      Frontend
    Product
      Research
      Design
    Finance
      Payroll
      Close

The root is the company, not the CEO. I don't put the CEO in the center of a mindmap unless I'm ready for readers to invent a reporting line the indent doesn't state. Engineering, product, and finance are siblings. Backend sits under engineering because it's indented further, not because an arrow says so. If you later decide frontend reports to product, this map doesn't claim otherwise. It also doesn't help you. You need the flowchart for that change.

People still scan a mindmap left to right and invent an order. Engineering isn't "before" product. If a reader needs an order, you drew the wrong diagram. Say that under the figure, in one sentence, or someone will turn the map into a roadmap.

Use the mindmap for the index and the flowchart for the lines. They can live in the same Markdown file as two fences. I've tried to make one diagram do both, with arrows and a tree, and it answered neither question cleanly. Two small pictures beat one clever one. The diagram examples are a wider set of "which picture" choices if the org chart is starting to collect other meanings.

A mindmap node is its own text. There's no separate id. Renaming "Close" to "Books" means re-indenting any children under the new line. Keep the names short so you don't hate that edit. And don't name a branch end. It's a confusing word in a file full of Mermaid, and you don't need it.

Titles change, and the chart rots on a schedule

The failure mode is politeness. Someone changes teams, and you don't want the chart to look harsh, so you leave the old box and add "(acting)" or a second arrow "for now." Six months later the chart has two managers for a team that has one, plus an acting label nobody remembers. Delete the old arrow in the same week as the announcement. The chart is allowed to be blunt. The announcement email can be kind.

"For now" is not a cardinality you can draw honestly without a date. If the date matters, put the date in the paragraph and a ticket link next to it. Don't encode a temporary state as a permanent arrow because you're unsure. An unsure arrow is how the next manager inherits a responsibility they don't have. I did this with a dotted line "until we backfill." We didn't backfill. The dotted line became the org.

Contractors and agencies are the other rot. A box called "External design" with an arrow from the CEO implies a reporting line that the contract doesn't include. If they don't report in, they don't get an arrow. Mention them under the figure. The flow chart posts are full of processes that look like org charts if you squint, and the squint is the mistake. A process has steps. An org chart has bosses. A contractor on a process chart is a step. A contractor on an org chart is a claim about management.

Vacancies can be nodes if the role is approved and the reports are real. Label it Backend lead (open), not with a person's name you hope to hire. When the role is cancelled, delete the node and move the arrows. A chart that keeps cancelled roles "so we remember" remembers the wrong structure. Remember in the commit message.

What this chart should refuse to show

It should refuse salaries, performance, and personal data. None of that belongs in a git repo diagram, even a private one. It should refuse to be the phone book. Email addresses in labels get copied into screenshots and live forever. Put a link to the directory under the figure if people need to find a human.

It should refuse matrix lines you can't defend. If you can't name the decision the dotted-line manager can make, you don't have a dotted line. You have a feeling. Feelings go in the mindmap as a shared project, or they go nowhere.

It should refuse to show every individual when the team is the unit the company actually manages. A forty-person engineering tree with every name is a directory, and it changes every sprint. Draw teams until someone asks who a specific person reports to, and then add that person. I drew all forty once. The next week I stopped updating it, which made it worse than not having it.

If the question is "how do we ship," you don't want this chart at all. You want a process flowchart. The make a flow chart walkthrough is that picture. If the question is "what is this kind of file even for," what a mermaid diagram is separates the artifact from the org-chart habit of decorating it. An org chart is one artifact. It claims reporting lines. It doesn't claim the deploy pipeline, the product strategy, or the on-call rotation. Those are other files. Mixing them produces a poster.

Templates are useful when you want a starting tree rather than a blank page. Replace the sample labels before you commit. A template company left in the repo is a special kind of wrong, because it looks complete.

Put the chart where a rename is a diff

Keep docs/org.md next to the rest of the docs, with one flowchart fence and, if you need it, one mindmap fence. Link it from the README in a single line. When a team moves, the pull request edits the arrow. Reviewers can see the old line and the new line. That's the advantage over the slide, and it's the advantage over any tool that exports a PNG and throws away the source.

If you're staring at a blank file and don't want to hand-place the first nine boxes, describe the tree in a sentence and let the flowchart generator draft the TD chart. Then delete every arrow that isn't a reporting line. Generators add "related" edges. Related is not a boss. Read the draft the way you'd read a policy.

Open the editor when you want the picture to follow the edit. Paste the result back into docs/org.md. Don't export a PNG as the thing you commit, unless a specific reader can't see Mermaid. Even then, commit the source beside the PNG. The source is the chart. The PNG is a view of it on the day you exported, and that day ends.