User Journey Maps in Confluence Using Mermaid

The product review opened on a Confluence page titled "Trial signup journey."

Design had a FigJam map. Research had interview quotes in a spreadsheet. Product had a bullet list that said "user discovers product → signs up → activates workspace" without showing which actor did what, which steps frustrated users, or where the journey split by plan type. When someone scrolled the page, the horizontal shape of the journey — discover, evaluate, commit, activate — was nowhere visible.

"We did the journey research. Why does the Confluence page still read like a feature list?"

UX writers and product managers hit this wall when Confluence UX documentation hides phase structure inside prose. A user journey diagram Confluence page makes sections, tasks, and actors visible — and keeps Mermaid source editable beside the research narrative teams already maintain.

This how-to shows how to write Mermaid journey maps, keep labels readable, and use reader tools when long horizontal flows outgrow the page column.

Quick Answer

• Use journey when the question is experience across phases — who does what and how satisfied they are at each step.
• Use flowchart LR when the question is topology — systems, handoffs, and decision branches without satisfaction scoring.
• Keep task labels short; research detail in prose. Quotes and metrics do not belong inside every task line.
• Open wide reading when sections sprawl horizontally. Search and minimap help PMs and UX writers follow long customer flow diagram maps without a guided walkthrough.

BacklogBridge Diagram Lens for Confluence is one macro with source editing, live preview, wide reader, search, and minimap. Verify the current Marketplace listing before install.

What You Are Trying To Accomplish

You want a customer flow diagram in Confluence where:

• journey phases are visible as sections, not buried in numbered bullets
• each task shows which actors participate
• satisfaction or pain is encoded consistently and explained for non-Mermaid readers
• Mermaid source stays editable beside UX research prose
• stakeholders can inspect a long horizontal map without the author driving every review

The outcome is documentation where phase structure and actor involvement are inspectable — not reconstructed from bullet indentation.

Requirements

Step 1: Journey vs Flowchart LR

Choose the diagram type before writing source. The wrong type forces satisfaction scores into a topology map — or hides branching inside a journey renderer that expects linear tasks.

The Mermaid documentation describes diagrams defined as text and code. Backlog Bridge's Mermaid chart tips guide recommends picking the chart type that matches the question — not defaulting every customer map to flowchart.

Same journey as bullets vs Mermaid (micro-example)

Bullets:

• Discover product (mostly smooth)
• Sign up (email verify painful)
• Activate workspace (smooth once wizard completes)

Journey: the same phases as horizontal sections with explicit scores and actors. The journey does not replace research — it exposes structure bullets force readers to reconstruct.

Step 2: Mermaid Journey Syntax

Mermaid provides a dedicated journey diagram type. The Mermaid user journey syntax docs describe maps built from sections and tasks.

Basic skeleton:

journey
    title Trial signup journey
    section Discover
      Visit marketing site: 5: Prospect
      Read pricing page: 4: Prospect
    section Sign up
      Create account: 3: Prospect, Product
      Verify email: 2: Prospect
    section Activate
      Complete onboarding wizard: 4: Prospect, Support
      Invite teammates: 5: Prospect

Syntax rules:

Tasks render left-to-right within each section. Sections stack vertically, which makes Mermaid user journey maps naturally wide as phases accumulate — the layout pattern that triggers readability problems in a normal Confluence column.

Step 3: Map UX Phases To Sections

Align section labels with how your team already talks about the journey:

Keep section names stable across releases. Rename prose H3 headings and section labels together so diffs stay readable.

Step 4: Readable Task Labels And Actor Notation

Bad — entire research note in the task line:

Create account after clicking hero CTA and seeing SSO error on Safari: 3: Prospect who came from paid search

Good — task names the step; prose owns context:

Create account: 3: Prospect, Product

Then under Sign up friction in prose:

• Safari SSO error tracked in PROD-4412
• Paid search cohort shows higher drop-off at email verify

Use consistent actor names: Prospect, Customer, Support, Sales, System — not alternating synonyms in the same diagram.

Quote task labels when text contains punctuation or characters Mermaid may parse specially. Keep labels plain for predictable Confluence rendering; Backlog Bridge's knowledge-base page notes that Diagram Lens-safe examples avoid raw markup and source-defined interactivity.

Step 5: Satisfaction Scores — Explain In Prose

Mermaid journey tasks include a numeric score between the task label and actors. In current Mermaid journey examples, higher scores typically indicate better satisfaction and lower scores indicate more friction — but confirm against the Mermaid user journey syntax docs and your macro preview before publishing, because renderer conventions can change.

Add a score legend every stakeholder can read without opening the macro:

Scores are editorial signals for discussion, not statistical proof unless prose cites the underlying study. When research uses a different scale, map it explicitly in the legend rather than assuming readers infer the conversion.

If the journey type in your renderer supports accessibility metadata, add accTitle and accDescr near the source so screen-reader users get a summary — verify support in preview before relying on it in shared UX spaces.

Step 6: Recommended Page Template

Place the macro under the journey summary — not on a separate attachments page stakeholders skip during roadmap reviews.

Map each H3 phase section to a section label so comments like "Update verify-email pain for the Sign up section" are actionable.

Step 7: Author, Preview, And Navigate Long Horizontal Flows

After an admin installs an approved Mermaid macro:

1. Paste a skeleton with two sections and three tasks total.
2. Add tasks one section at a time; preview after each section.
3. Confirm actor lists render when multiple participants share a task.
4. Save, reopen, and confirm stored configuration matches preview.

Horizontal journey maps fail predictably once phases multiply:

Confluence layout controls can widen the page column. That helps prose tables. It does not replace diagram-level navigation when a multi-section journey grows wider than the viewport.

"Which phase had the lowest satisfaction last quarter?"

Without search or minimap, the reviewer pans and asks the author. With search, they jump to the task label already used in research readouts.

Diagram Lens public pages describe a source editor with live preview, line and character counts for source size, wide reader with pan/zoom/fit/reset, search across rendered SVG text, and minimap navigation. Diagram Lens support docs recommend starting from a small known-good diagram and using the syntax error panel for line, column, and token details when render fails. The same authoring loop applies to any preview-capable Mermaid macro.

For deeper reader-tool guidance, see Mermaid Diagrams in Confluence: Why Big Diagrams Need a Reader.

For export workflows, see Exporting Mermaid Diagrams From Confluence. SVG and Mermaid source are the primary reliable export paths per Diagram Lens public pages; PNG and PDF are best effort and can depend on browser support, diagram size, and Forge iframe permissions.

Step 8: Split Oversized Multi-Phase Journeys

Reader tools help large diagrams. They do not replace scope discipline.

Overview vs detail task budget:

A practical documentation set on one Confluence parent page:

01_journey_overview
02_discover_detail
03_signup_detail
04_activate_detail
05_support_escalation_flowchart

Each diagram answers one review question. Link them from the parent journey page. For splitting standards, see Mermaid Diagram Governance in Confluence.

Worked Example: Trial Signup Journey

Research summary in prose:

Prospects discover the product through marketing and docs, sign up with moderate friction at email verification, and activate faster when onboarding offers a sample workspace.

Prose section to task mapping:

Matching journey skeleton:

journey
    title SaaS trial signup
    section Discover
      Find product via search: 4: Prospect
      Read docs landing page: 5: Prospect
    section Sign up
      Submit signup form: 3: Prospect
      Verify email address: 2: Prospect, System
    section Activate
      Finish onboarding wizard: 4: Prospect
      Create first project: 5: Prospect

PMs and UX writers follow the rendered path during roadmap reviews. Interview quotes and cohort notes live in H3 sections below the macro — not inside task labels.

Common Pitfalls

Backlog Bridge's knowledge-base page notes that Diagram Lens-safe examples avoid source-defined interactivity and raw markup patterns — appropriate for shared product spaces.

Admin Checks Before Rollout

Atlassian's Manage your apps documentation says Confluence apps are usually installed from Marketplace through Connected Apps and require site admin access.

At the time of research on July 23, 2026, I did not find an official Atlassian Marketplace listing for BacklogBridge Diagram Lens for Confluence through available public sources in sibling editorial research. Search Marketplace again before install.

The public Diagram Lens security page describes client-side rendering, storage:app scope, no external egress declared in the current manifest, and strict Mermaid sanitization. The privacy page says app-owned diagram configuration is stored in Atlassian Forge hosted storage.

Do not infer SOC 2, ISO, Cloud Fortified, GDPR/DPA, or procurement approval without explicit published evidence.

See Mermaid Macro Security in Confluence for a fuller macro security review.

What Diagram Lens Is Not Trying To Be

The Diagram Lens product page describes a source-first Mermaid editor. It states that it does not include visual drag-and-drop editing, AI generation, or repository sync. Mermaid renders client-side inside Forge Custom UI; the launch model does not use a remote Mermaid renderer or vendor-hosted diagram backend.

That makes Diagram Lens a fit for teams that want editable Mermaid journey source beside Confluence UX prose — not for teams whose primary requirement is canvas journey mapping, AI-generated diagrams, or Git-backed diagram sync.

When To Use A Different Approach

• Cross-team handoffs and queues fit swimlane flowcharts — see Swimlane Flowcharts in Confluence With Mermaid Subgraphs.
• Branching eligibility or policy logic fit decision trees — see Decision Trees in Confluence: When Mermaid Beats a Bulleted List.
• Phased operational runbooks without satisfaction scoring fit process flowcharts — see How to Document Business Processes in Confluence With Mermaid Flowcharts.
• Workshop sketches may fit canvas tools — see Mermaid vs draw.io and Gliffy in Confluence.

Trial Checklist

Test with one real journey your PM and UX writers reopen every quarter — not a toy two-section sketch.

1. Pick a journey page where phase structure is currently unclear in prose alone.
2. Draft research summary prose: persona, scope, score legend, last reviewed date.
3. List phases as sections on paper; count tasks per section.
4. If more than five sections or heavy branching, plan overview plus detail pages first.
5. Build a journey macro with two sections; preview after each section you add.
6. Add actor lists and scores; confirm legend matches previewed score direction.
7. Add H3 phase sections referencing task labels.
8. Change one pain-point note in prose; confirm diagram tasks still match.
9. Open wide view and search for two task names used in research readouts.
10. Ask a second reviewer to locate the lowest-scored task without author guidance.
11. Export Mermaid source; test SVG if compliance needs snapshots outside Confluence.
12. Try PNG or PDF only if those formats matter, using your widest expected journey map.
13. Record Marketplace, scope, privacy, and classification questions before production use.

If the second reviewer can locate the lowest-scored task without a guided screen share, the journey-plus-prose workflow is doing real work.

Final Recommendation

User journey diagram Confluence pages stay maintainable when Mermaid journey sections express phases, short task labels name steps, actors show involvement, and a prose score legend explains satisfaction numbers for every reader.

Split before sections sprawl past reviewability. When maps grow wide, wide reading, search, and minimap help product and UX stakeholders follow long horizontal Mermaid user journey flows without a guided screen share. If your team already keeps Mermaid in Confluence and wants source editing plus reader tools for Confluence UX documentation, Diagram Lens is worth a focused trial — after you verify the current Marketplace listing, install prompt, and export behavior on your widest real customer journey map.

For deeper Mermaid authoring patterns, see Backlog Bridge's Mermaid chart tips guide.