Mermaid user journey examples

Mermaid user journey syntax

Mermaid’s documentation defines the diagram in three lines: a journey is split into sections that describe parts of the task, each task is written as Task name: <score>: <comma separated list of actors>, and the score is a number from 1 to 5 inclusive. The journey keyword and a title come first; the rest is sections and tasks, indented for readability.

Tasks are drawn left to right in the order written, grouped under coloured section bands. Each task shows a face for its score, and each actor named anywhere in the diagram gets a colour, a legend entry and a marker on the tasks they take part in. That is the whole vocabulary; there are no arrows, conditions or durations, which is what keeps the diagram quick to write in a planning document or a research summary.

What do the scores mean?

The score is how the actor feels at that step, from 1 (bad) to 5 (good); the documentation only fixes the range, so agree the meaning with your team before scoring. In the rendered diagram, a score above 3 draws a smiling face, exactly 3 a neutral face and below 3 a sad face, and the face sits higher or lower on the task card with the score. Readers scan the row of faces first, so the chart is at its best when it has a handful of low scores that point at the steps worth fixing.

Scores are per task, not per actor. If two actors experience a step differently, split it into two tasks, or score the actor whose experience you are mapping, as the hiring example does by giving the candidate and the recruiter separate application steps.

Which configuration options does a user journey have?

The journey has no theme variables of its own; its colours and spacing are configuration keys under config: journey in the YAML block at the top of the diagram. These are the ones worth knowing; the full list is in Mermaid’s configuration schema.

Where does a user journey render, and when should you use one?

The user journey is one of Mermaid’s older diagram types, so it renders on every platform that supports Mermaid at all: GitHub draws mermaid blocks in issues, pull requests, discussions, wikis and Markdown files, and GitLab, Obsidian, Notion and the VS Code Markdown preview render them too. The Mermaid in Markdown page shows how each one embeds a diagram and how to check the Mermaid version with the info diagram. To share a journey with people outside those tools, paste the Markdown into the Docs MD editor and send the link, or convert the document to PDF.

Use a user journey to summarise research or a walkthrough: what a person does, in order, and how it feels. It is not a flowchart, so it cannot show branches or failures, and it is not a timeline, so it carries no dates. For the status of work items use a kanban; for a schedule use a Gantt chart. The hub of Mermaid examples compares every chart type Docs MD covers.

What score range does a Mermaid user journey accept?

Whole numbers from 1 to 5 inclusive, as stated in Mermaid’s documentation. A score above 3 is drawn as a smiling face, 3 as a neutral face and below 3 as a sad face. Decide what the numbers mean for your team before scoring, since the diagram only fixes the range; a common reading is 1 for frustrating and 5 for delightful.

How many actors can a task in a Mermaid user journey have?

As many as you list after the second colon, separated by commas. Each distinct actor name in the diagram gets its own colour and legend entry, and a marker on every task it appears in. Keep the names consistent, because User and user would become two actors. In practice three or four actors is the readable limit for one journey.

Can a Mermaid user journey have tasks without sections?

Yes. Sections are optional; tasks written directly after the title are drawn without a section band, as the short Monday morning example shows. Once you use one section, put every task under a section so that the bands read consistently from left to right.

How do I change the colours of a Mermaid user journey?

Set sectionFills and actorColours under config: journey in a YAML block at the top of the diagram, each as a list of colours used in order. These are configuration options rather than theme variables, which is why the usual themeVariables approach for other charts does not apply here. The section colours example on this page shows the block.

Does GitHub render Mermaid user journey diagrams?

Yes. GitHub renders fenced mermaid blocks in issues, pull requests, discussions, wikis and Markdown files, and the user journey is an established diagram type that predates Mermaid 10, so it does not depend on a recent version. GitHub chooses the Mermaid version it runs; render an info block there if you want to know which one.