# Mermaid diagrams

A fenced mermaid block becomes escaped source during build and SVG in the browser through locally bundled Mermaid. Build success does not validate every diagram grammar expression or prove labels/relationships are correct.

# Rendering stages

Pages without diagrams do not load the diagram bundle just because loader script exists. The loader locates vendor bundle relative to its script URL, so template-owned base path matters. It caches pending library load; loading failure clears pending script so a later invocation can retry. There is no general guarantee every hosting/browser error repairs itself automatically.

Reader public rendering is serialized and catches errors. Editor preview uses same library with its own render loop inside script-blocked frame. Surrounding navigation/media/path/focus behavior still differs.

# Flowchart: document release

```mermaid
flowchart TD
  Save[Save Markdown] --> Build[Build output]
  Build --> Review[Review reader]
  Review --> Deploy[Deploy reviewed files]
```

flowchart TD
  Save[Save Markdown] --> Build[Build output]
  Build --> Review[Review reader]
  Review --> Deploy[Deploy reviewed files]

The process is save, build, review and deploy. These arrows describe required workflow, not automatic background actions. Save does not deploy remotely; administrator Publish changes local output. If an external CI pipeline deploys, state its actual verified trigger separately.

Use a flowchart for decisions/stage order. Keep node IDs short and stable, labels concise and direction truthful. A neat incorrect arrow is still a documentation error.

# Sequence: save confirmation

```mermaid
sequenceDiagram
  actor Writer
  participant Editor
  participant Source
  Writer->>Editor: Save
  Editor->>Source: Write Markdown
  Source-->>Editor: Success response
  Editor-->>Writer: Saved snapshot confirmed
```

sequenceDiagram
  actor Writer
  participant Editor
  participant Source
  Writer->>Editor: Save
  Editor->>Source: Write Markdown
  Source-->>Editor: Success response
  Editor-->>Writer: Saved snapshot confirmed

This sequence stops at a confirmed server source snapshot. Newer typing can still remain Unsaved. Publish/host release is outside the diagram. Drafts and saving owns exact queued/failure/late-response states.

Sequence diagrams answer interactions over time; flowcharts answer progression/choice. Do not put every possible workflow into one unreadable diagram. A numbered list can be clearer for a short procedure.

# Bundled diagram type inventory

The pinned asset manifest records Mermaid 12.1.0. The local vendor entry includes the following registered detectors. A detector recognizing the opening line is not proof every expression, layout option, icon package or browser works. The exact examples below are rendered checks; other rows describe the version’s source registration, not an execution certificate.

The type purposes and limits are:

• Flowchart: Steps, decisions and dependencies.
• Flowchart ELK: Requests ELK layout; verify available layout/runtime before adopting.
• Sequence: Ordered messages between participants.
• Class: Classes, members and relations.
• State: States and transitions; example uses stateDiagram-v2.
• Entity relationship: Entities and cardinality.
• Git graph: Illustrative branch/commit history, not live repository state.
• Gantt: Explicit dated work, not a live scheduler.
• Pie: Labeled parts of a stated illustrative total.
• XY chart: Axes and numeric bar/line series.
• Quadrant: Labeled normalized coordinates.
• Requirement: Requirements, elements and relations.
• Journey: Steps, actors and illustrative scores.
• Timeline: Dated/ordered narrative events.
• Mindmap: Indented parent/child hierarchy.
• Kanban: Authored columns/items, not synchronized tasks.
• Sankey: CSV-like source/target/value flows.
• Packet: Bit-range packet descriptions.
• Radar: Multiaxis scores; beta opening is required.
• Block: Explicit blocks and arrangement.
• Tree view: Tree display; beta opening is required.
• Architecture: Service/group diagrams; common syntax uses architecture-beta.
• C4: C4 views are distinct grammars, not arbitrary UML.
• Agent flow: Beta agent-workflow grammar.
• Swimlane: Beta swimlane grammar.
• Event modeling: Event-modeling grammar.
• Ishikawa: Cause/effect grammar; detector is case-insensitive.
• Venn: Set relationship grammar.
• Treemap: Hierarchical quantity grammar.
• Use case: Beta use-case grammar.
• Wardley: Beta mapping grammar; detector is case-insensitive.
• Cynefin: Beta domain grammar.
• Railroad: Authored railroad grammar.
• Railroad EBNF: EBNF input grammar.
• Railroad ABNF: ABNF input grammar.
• Railroad PEG: PEG input grammar.
• Info: Library information display, not handbook navigation.

Mermaid also registers internal error/frontmatter handlers. Those are not diagram choices. Prefix detection can accept a start and still fail the parser. These opening forms belong inside a lowercase mermaid fence, not in the fence language itself. For example, use mermaid plus a classDiagram first line, not a classDiagram fence.

The committed vendor bundle is the reader dependency. Installing another Mermaid package alone does not replace it. Asset regeneration is maintainer work described in Assets and bundles. Do not solve an authoring typo by rebuilding vendor libraries or changing the pinned engine.

# Choose a diagram by the question

The accompanying text requirements are:

• Flowchart: state conditions and stop/failure rules.
• Sequence: state exact response/commit boundary.
• State: state transition meaning and recovery.
• Class or ER: state relation/cardinality meaning.
• Gantt or timeline: state dates, owner and illustrative/live status.
• Pie: state total, units and source.
• Mindmap: state important hierarchy in text.
• Git graph: state fictional versus verified history.
• XY, quadrant or Sankey: state units, axes, values and provenance.

The following small specimens are fictional teaching models. They are not measurements, account records, actual project deadlines, a repository audit or a certification of MarkStack’s data model. Copy the fence, replace its meaning deliberately, render, then review both themes and phone width.

# Class relationships

A handbook groups pages; the example relation is structural, not the engine runtime class model.

```mermaid
classDiagram
  class Handbook
  class Page
  Handbook "1" --> "many" Page : groups
```

classDiagram
  class Handbook
  class Page
  Handbook "1" --> "many" Page : groups

# State transitions

Work moves from Writing to Saved after save success. Saved reaches Reviewed after reader checks. These simplified states do not replace the detailed save-controller contract.

```mermaid
stateDiagram-v2
  [*] --> Writing
  Writing --> Saved: save succeeds
  Saved --> Reviewed: reader checked
  Reviewed --> [*]
```

stateDiagram-v2
  [*] --> Writing
  Writing --> Saved: save succeeds
  Saved --> Reviewed: reader checked
  Reviewed --> [*]

# Entity cardinality

An illustrative section contains many pages; this is a conceptual content relationship, not a supplied relational database.

```mermaid
erDiagram
  SECTION ||--o{ PAGE : contains
  SECTION {
    string title
  }
  PAGE {
    string path
  }
```

erDiagram
  SECTION ||--o{ PAGE : contains
  SECTION {
    string title
  }
  PAGE {
    string path
  }

# Dated planning

These two one-day tasks are fictional dates. Review follows writing. The chart does not schedule reminders or change a calendar.

```mermaid
gantt
  title Fictional release plan
  dateFormat YYYY-MM-DD
  section Handbook
  Write :write, 2026-01-05, 1d
  Review :review, after write, 1d
```

gantt
  title Fictional release plan
  dateFormat YYYY-MM-DD
  section Handbook
  Write :write, 2026-01-05, 1d
  Review :review, after write, 1d

# Labeled proportions

The fictional example totals ten pages: six reviewed and four still drafting. The counts are illustrative, not this handbook status.

```mermaid
pie title Fictional page review
  "Reviewed" : 6
  "Drafting" : 4
```

pie title Fictional page review
  "Reviewed" : 6
  "Drafting" : 4

# Topic hierarchy

The handbook root has Start, Run and Use children. This is a shortened teaching hierarchy, not the complete navigation.

```mermaid
mindmap
  root((Handbook))
    Start
    Run
    Use
```

mindmap
  root((Handbook))
    Start
    Run
    Use

# Illustrative branch history

A fictional review branch starts after a commit, adds another commit and merges into main. This diagram neither reads nor changes Git.

```mermaid
gitGraph
  commit
  branch review
  checkout review
  commit
  checkout main
  merge review
```

gitGraph
  commit
  branch review
  checkout review
  commit
  checkout main
  merge review

# Narrative timeline

Draft then review then release are labeled stages. The diagram is authored narrative, not an automatic release feed.

```mermaid
timeline
  title Fictional handbook stages
  Draft : Write complete instructions
  Review : Check source and reader
  Release : Deploy approved output
```

timeline
  title Fictional handbook stages
  Draft : Write complete instructions
  Review : Check source and reader
  Release : Deploy approved output

# Journey scores

A fictional writer drafts, reviews and releases. Scores from one to five are illustrative and have no measured user-study claim.

```mermaid
journey
  title Fictional writing journey
  section Prepare
    Draft: 3: Writer
    Review: 4: Writer
  section Deliver
    Release: 5: Writer
```

journey
  title Fictional writing journey
  section Prepare
    Draft: 3: Writer
    Review: 4: Writer
  section Deliver
    Release: 5: Writer

# Numeric comparison

Three illustrative batches A, B and C have values two, four and three. Axis maximum is five; units and provenance must be supplied for real data.

```mermaid
xychart-beta
  title "Fictional batch counts"
  x-axis [A, B, C]
  y-axis "Pages" 0 --> 5
  bar [2, 4, 3]
```

xychart-beta
  title "Fictional batch counts"
  x-axis [A, B, C]
  y-axis "Pages" 0 --> 5
  bar [2, 4, 3]

# Packet fields

An illustrative sixteen-bit record has two eight-bit fields. It is not a MarkStack wire protocol.

```mermaid
packet-beta
  0-7: "Kind"
  8-15: "Length"
```

packet-beta
  0-7: "Kind"
  8-15: "Length"

# Flow values

Six fictional units move from Draft to Review and four from Review to Ready. This difference requires interpretation for real data; the diagram does not reconcile a ledger.

```mermaid
sankey-beta

Draft,Review,6
Review,Ready,4
```

sankey-beta

Draft,Review,6
Review,Ready,4

# Extend examples safely

Add one relation at a time and inspect actual SVG. Markdown fence language is a dispatch condition; Mermaid or another label can take ordinary code path rather than diagram rendering. Mermaid supports its own grammar/version; the inventory above states the pinned registered types. It does not promise another upstream version, external plugin, icon package or custom layout is available.

Raw HTML allowance is not required for supported Mermaid. Strict security mode is configured. Arbitrary click handlers/HTML integrations are not a promised execution surface. Keep diagrams descriptive and review hostile/user-supplied syntax as untrusted content.

# Diagnose failure in order

1. Confirm exact fence label and minimal source.
2. Open generated page through HTTP and inspect loader/vendor responses.
3. Wait for actual SVG, not only code/container.
4. Distinguish syntax error from missing bundle/secure-context/resource failure.
5. Add complexity back, checking labels/relationships each time.
6. Inspect both themes and phone/desktop width.
7. Preserve minimal nonsecret source/error for support.

A missing bundle can be deployment root/base prefix, not bad authored syntax. Syntax failure is not automatically a host outage. Inspect real responses and console; do not fabricate a successful fallback when loader error only logs failure.

Browser rendering uses modern platform features, including secure-context cryptographic UUID generation in reader. HTTP localhost/HTTPS testing is different from arbitrary plain remote HTTP or file://. Bundled assets do not certify all browsers/devices or protocols. Use the actual target browser/host for final check.

# Search and accessible text

Search strips diagram/preformatted source, so node labels alone are not a dependable search entry. Write question, conclusion and important relationships in normal prose. The flowchart’s sequence and sequence diagram’s stop condition above provide that fallback.

Do not rely on color to distinguish failure/success. Review contrast, tiny text, long arrows, overflow and crop in actual pixels. A readable explanation must remain when SVG fails or a reader cannot interpret it visually. Labels should complement, not replace, nearby instructions.

# Completion evidence

Review diagrams when procedure changes, not only when syntax changes. This handbook’s local examples are measured browser renders; they are not proof production TLS, physical Safari, every Mermaid grammar or organizational diagrams were tested. Validation limits states the wider boundary.