Tier 1 diagrams have detailed styling and ordered entrance animations. All diagrams render as SVG on the server through Pele. Expand any example to zoom, pan, or select its text.
Mermaid uses the code-block frame configured by components.code.frame, including its mobile edge-to-edge layout. The per-diagram frame option controls whether that frame and background are shown.
Cached requests return immediately. Uncached requests load and validate content before publishing an artifact, or return a diagnostic when validation fails.Build pipelineHitMissYesNo
Reader
Cached?
Render response
Load content
Valid?Publish artifactShow diagnostic
From request to response
YesNoSearch querySearch indexAny matches?Rank by relevanceShow excerptsOpen pageSuggest relatedtopics
Finding the right page
NoYesUpload imageSupported format?Explain acceptedformatsStore originalCreate thumbnailOptimize full sizePublish to CDNReady to embed
The compiler validates an author's changes, writes the artifact and search index in parallel, then reports either success or a diagnostic.loop[Up to 3 attempts][Update search]par[Store page][Invalid content]alt[Valid content]Publish changesValidate links and metadataWrite versioned artifactStored or retryIndex headings and textIndexedPublication readyDiagnostic with source locationActivate only after both writes succeedAuthor
Compiler
Artifact store
Search index
Author
Compiler
Artifact store
Search index
Publishing with retries
[Verification failed]alt[Signature accepted]Sign inRequest challengeOne-time challengeAsk for signatureConfirm identityApproveSigned challengeVerify signatureStart sessionOpen workspaceReject challengeTry another methodReaderBrowserServerAuthenticatorReaderBrowserServerAuthenticator
Use the Mermaid component with a source property in your document.
A mermaid code fence displays highlighted source. Source examples can contain incomplete or invalid Mermaid.
flowchart LR Reader --> Server
::Mermaid{title="Publishing flow"maxHeight=480}---source:| flowchart LR Author --> Compiler --> Reader class Compiler brief_violet---::
Use brief_ color classes for named VISUALS colors that adapt to light and dark modes. Flowcharts and state diagrams use class; class diagrams use cssClass. Explicit style and classDef colors remain fixed overrides. Class members and entity types share the Fields syntax palette.
Setting
Behavior
title
Caption below the diagram
font=interface or font=code
Use the configured interface or code typography
titleAlign=center or titleAlign=left
Align Tier-1 box titles and icons together; defaults to center
arrowStyle=soft
Tier-1 directional arrowheads: open, soft, or filled
maxHeight=640
Overview height cap; defaults to 480px
height=360 or height=auto
Fixed overview height or the full aspect ratio
animationDuration=6000
Total entrance time in milliseconds, from 600 to 30,000; otherwise scales with complexity
animate=false
Show the complete diagram in the server-rendered page, retaining fullscreen, zoom, and hints after hydration
Boxes and their text share one entrance animation, including timing, blur, and movement. Line labels reveal over 120ms as the stroke reaches them. Sequence diagrams introduce their columns before the message flow. Reduced motion and pages without JavaScript show the complete diagram. Use accTitle and accDescr for accessible SVG titles and descriptions.
Set application defaults in VISUALS.components.mermaid. Each chart can override arrowStyle and titleAlign through the Mermaid component. background and curveStrength are global-only settings. Omitted settings inherit the global default. Arrow styles affect directional arrowheads; UML inheritance, composition, and ER cardinality symbols keep their meaning. The soft arrow uses an outlined triangle with a 30% fill.
Global background accepts grid, dashed-grid, blueprint, dots, cross, or none. Global curveStrength controls connector bends from 0 to 2; auto follows the app radius. Arrow corners follow the app radius, and their outlines use the app border thickness.
Global variant accepts framed or borderless, and global frame accepts none, debossed, or embossed. Dots follow the configured corner radius. Dashed grids alternate solid and dashed lines at the same spacing as grids. Chart backgrounds retain the same parallax and zoom behavior in fullscreen.
Set VISUALS.components.mermaid.font to interface or code for all diagrams, or set font on an individual Mermaid component. The selected role supplies its family, size, weight, and spacing for layout and rendering. Class members and other code-specific labels retain the code font.
Attach an icon from VISUALS.icons to a Tier-1 box title with an %% icon: comment. target is the node's Mermaid ID, even when its displayed title uses an alias.
::Mermaid---source:| flowchart LR %% icon: {"target":"Reader","name":"globe"} Reader[Documentation reader] --> Page class Reader brief_blue---::
Icons sit left of the title, reserve space in the layout, and use the box's color ramp at the same softer intensity as badge icons. The icon and title are centered together by default; set titleAlign to left on the component to align box titles to the left. They share the box's entrance animation and remain visible in static and fullscreen views. Supported targets are flowchart nodes, swimlane steps, sequence participants, named states, classes, and entities. Groups, start/end markers, and sequence actor figures do not accept title icons. Each target accepts one icon. Git branch badges always use the interface bundle's branch icon.
Set frame on an individual diagram to choose its presentation. These options also apply in fullscreen.
Option
Appearance
frame=full
Default. Uses the configured background, borders, and embossed or debossed frame.
frame=background-only
Fades the background toward all four edges, without a card frame or border.
frame=none
Shows the diagram on its own, without a background or border.
SourceBuildPublish
Full frame
SourceBuildPublish
Fading background
SourceBuildPublish
Diagram only
In fullscreen, scroll or pinch to zoom, drag to pan, and use Fit to reset the view. Text remains selectable. Escape closes the viewer.
Set fullscreen=false to keep a diagram in the page, or replay=false to hide its replay button. animate=false renders the complete diagram immediately and also hides replay. These options do not remove label hints.
«contains»«contains»«satisfies»«satisfies»«verifies»«Requirement»safe_publishID1TextPublished pages must bevalid and recoverable.RiskHighVerificationTest«Functional Requirement»validate_linksID1.1TextReject revisions with brokeninternal links.RiskMediumVerificationTest«Functional Requirement»rollbackID1.2TextRestore the previouspublished revision.RiskHighVerificationDemonstration«Element»compilerTypeservice«Element»artifact_storeTypestorage«Element»release_suiteTypetest suite
54321DiscoverFind thequickstartDeveloperCompareexamplesDeveloperIntegrateCreate an APIkeyDeveloperAdminInstall theSDKDeveloperDebug a failedrequestDeveloperSupportShipRun integrationtestsDeveloperApproveproductionaccessAdminDeploy theapplicationDeveloperAdminAdminDeveloperSupport
Add a %% hint: comment with JSON containing the label's text and a plain-text legend. The label uses the same dotted underline and popup as Hint. Hover, focus, or tap it to read the explanation, including in fullscreen.
HitCached?Read artifact
Hints without entrance animation
target optionally limits the hint to a node or edge ID. Without it, matching labels share the hint. Box titles, edge labels, and other SVG text can have hints, including diagrams with animate=false. Each label accepts one hint; overlapping annotations are reported as errors.
Brief compiles Mermaid into SVG alongside the document, validating syntax, icons, and hints before the page renders. The compiled SVG preserves live theme tokens for the theme builder. Geometry settings such as curve strength and title alignment take effect when the diagram is compiled; rebuild documents after changing those defaults.