← All diagram types

Mermaid journey syntax: user journey maps, scores and actors with examples

Mermaid journey syntax with rendered examples: tasks in order, satisfaction scores from 1 to 5, sections that group a stage, and named actors.

A user journey map follows one person through a process and records how each step felt. Mermaid's journey plots the tasks left to right and the satisfaction score as the height of each point, so the dips show where the experience fails.

Everything on this page is rendered by makesPDF's own Mermaid renderer, so a ```mermaid block produces exactly this in the PDF.

Tasks and scores

Each task line is name : score, where the score runs from 1 (worst) to 5 (best). Tasks are drawn in source order:

mermaid
journey
  title First render
  Sign up: 4
  Create an API key: 3
  Send a request: 2
  Read the PDF: 5
Render this to PDF →How diagram blocks work

The line between the points traces the experience, so a drop to 2 then a rise to 5 is the story the diagram tells.

Sections

section groups the tasks that belong to one stage and draws a labelled band behind them:

mermaid
journey
  title First render
  section Onboarding
    Sign up: 4
    Confirm email: 3
    Create an API key: 3
  section First request
    Read the docs: 2
    Send a request: 2
    Debug the error: 1
  section Success
    Read the PDF: 5
Render this to PDF →How diagram blocks work

Stages need no declared length — a section spans exactly the tasks written under it.

Actors

A third field after the score lists who performs or observes the step, separated by commas. Actors get a colour each and appear as dots under the task, with a legend below the lane:

mermaid
journey
  title Checkout
  section Browse
    Open the store: 5: Shopper
    Search for an item: 4: Shopper
  section Buy
    Add to cart: 4: Shopper
    Pay: 3: Shopper, Payment provider
    Receive receipt: 5: Shopper, Email service
Render this to PDF →How diagram blocks work

The same actor name always gets the same colour, so a legend with three or four actors stays readable.

Scores are the data

Only the score changes the shape; the task text is just a label. Two versions of the same journey can be compared by changing the numbers, which makes this a lightweight way to show a before/after in a report:

mermaid
journey
  title Support ticket
  section Report
    Find the form: 3: Customer
    Describe the issue: 2: Customer
  section Wait
    First reply: 2: Customer, Agent
    Resolution: 4: Customer, Agent
Render this to PDF →How diagram blocks work

A score outside 1–5 is clamped into the range, so a typo never breaks the diagram.

Not supported in makesPDF yet: %%{init}%% theming directives are ignored, so every journey uses the same mood palette. Task labels wrap to a shared width across the whole diagram, so one long task name widens every column.