Documentation index: /llms.txt. Each page is also available as Markdown by adding .md to its URL.

Skip to content

Mermaid

Explore software architecture, workflows, relationships, and Git history rendered with Pele.

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.

Flowcharts

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
From upload to delivery

Sequence diagrams

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
Signing in with a passkey
opt[Cached copy is stale]Request pageServe cached pageFetch latest revisionUpdated pageRequest againServe refreshed pageReplace cached copyReaderEdgeOriginReaderEdgeOrigin
Serving stale content while refreshing

State diagrams

DeliverySubmitRequest changesApproveBuild succeedsBuild failsRetryPromoteRetireRestore
Draft
ReviewArchivedBuildingPreviewFailed
Live
A page's lifecycle
StartPauseResumeAll chunks sentChecksum matchesChecksum differsRetryCancelCancelQueuedUploadingPausedVerifyingCompleteFailedCancelled
A resumable upload
OnlineConnectAcceptedTimeoutQueue messageAcknowledgedConnection lostRetry timerDisconnectOfflineConnectingBackoffIdleSending
Keeping a connection alive

Class diagrams

loadshistorypublishes1many«interface»
Source
+discover() : Page[]+load(id) : Page
FileSource
+root string+watch() : Change[]
RemoteSource
+endpoint string+refresh() : Page[]
Page
+id string+title string+revisions Revision[]
Revision
+version string+publishedAt Date
Publisher
+validate() : Issue[]+publish(page) : Revision
Publishing contracts
returns«interface»SearchProvider+search(query) : SearchResult[]+index(documents) : voidLocalSearch+maxResults number+search(query) : SearchResult[]RemoteSearch+endpoint string+search(query) : SearchResult[]SearchResult+title string+url string+score number
A pluggable search provider
placescontainsreferences1many1manyCustomer+email string+placeOrder() : OrderOrder+id string+total() : numberLineItem+quantity number+subtotal() : numberProduct+name string+price number
Building an order

Entity relationships

containsgrantsholdswritesrecordscreates
WORKSPACE
stringidPKstringname
PAGE
stringidPKstringworkspace_idFKstringauthor_idFKstringslugUK
MEMBERSHIPstringworkspace_idFKstringauthor_idFKstringroleAUTHORstringidPKstringnamestringemailUKREVISIONstringidPKstringpage_idFKstringauthor_idFKdatetimepublished_at
Content and ownership
placescontainsappears_intracksCUSTOMERstringidPKstringemailUKPURCHASEstringidPKstringcustomer_idFKdatetimeplaced_atLINE_ITEMstringpurchase_idFKstringproduct_idFKintquantityPRODUCTstringidPKstringnamedecimalpriceSTOCKstringproduct_idPK, FKintavailable
Orders and inventory
teachesincludesholdsacceptsINSTRUCTORstringidPKstringnameCOURSEstringidPKstringinstructor_idFKstringtitleLESSONstringidPKstringcourse_idFKintpositionSTUDENTstringidPKstringemailUKENROLLMENTstringstudent_idFKstringcourse_idFKdatetimeenrolled_at
Courses and enrollment

Git graphs

Branch badges appear in commit order, followed by their drawn branch lines. Every badge uses the selected interface bundle's branch icon.

main
feature
BaselineImplementationFixReleasev1.0
Feature integration
main
api
docs
StartEndpointGuideAPI mergedDocs merged
Parallel changes
main
maintenance
v1PatchNextForward port
Release maintenance

Swimlanes

StorageAPIClient
Request
ValidateReplyQuery
Request ownership
BuildReviewerAuthorYesNoDraftApproved?Publish
Publishing workflow
NotificationsWorkerAPIRetryDoneAccept jobExecuteSucceeded?Notify user
Background processing

Arrow showcase

Each chart selects its arrow style; the background and curvature follow the theme. Each example includes a solid request and a dashed response.

requestresponseReaderService
Open
requestresponseReaderService
Soft fill
requestresponseReaderService
Filled

Using Mermaid

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.

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.

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.

Diagram fonts

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.

ReaderCompilerPage
Interface font
ReaderCompilerPage
Code font

Title icons

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.

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.

Diagram frames

Set frame on an individual diagram to choose its presentation. These options also apply in fullscreen.

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.

DraftReviewPublish
Inline-only diagram

Background-only showcase

YesNo
Read source
Compile pagesValid?Publish artifactsShow diagnostics
Publishing with a fading background
[Cache miss]alt[Cache hit]Request pageCached responseLoad pageRendered HTMLFresh responseReaderEdgeOriginReaderEdgeOrigin
Requests with a fading background
main
feature
BaselineRendererViewerFixReleasev1.0
Git history with a fading background

Tier 2 diagrams

Together with the Tier 1 examples above, this gallery covers every chart family in Pele's catalog.

These examples inherit the shared colors, fonts, frame, and viewer. They use Pele's layout and styling without the ordered Tier 1 entrance animation.

Architecture

PlatformAPIQueueWorkerMetadataArtifactsDelivery
Publication services
WorkersQueueBuildCache
Worker architecture

Mindmap

ContentGuidesAPI referenceExamplesDeliveryServer renderingArtifact cacheSearch indexExperienceNavigationThemesAccessibilityOperationsPreview buildsReview workflowRelease historyDocumentation
Documentation building blocks
FastUnitContractIntegratedAPIBrowserTests
Testing strategy

Pie chart

38%29%18%10%5%Guides [38]API reference [29]Tutorials [18]Release notes [10]Examples [5]
A documentation collection
48%32%20%Compile [48]Type check [32]Bundle [20]
Build time by task

Sankey

Readers → Edge cache: 1000Edge cache → Cached response: 760Edge cache → Build queue: 240Build queue → Fresh response: 225Build queue → Diagnostic: 15Cached response → Delivered: 760Fresh response → Delivered: 225Readers 1000Edge cache 1000Cached response 760Build queue 240Fresh response 225Diagnostic 15Delivered 985
Where 1,000 requests go
Requests → Stable: 90Requests → Canary: 10Stable → Success: 88Stable → Failure: 2Canary → Success: 9Canary → Failure: 1Requests 100Stable 90Canary 10Success 97Failure 3
Deployment traffic

Gantt

Outline and researchWrite guidesAPI examplesTechnical reviewAccessibility checkFinal editsPublishNov 03Nov 05Nov 07Nov 09Nov 11Nov 13Nov 15
Documentation release plan
ReproducePatchRegression checkDeployNov 02Nov 03Nov 04Nov 05Nov 06
Patch delivery schedule

Block

API gatewayCacheJob queueArtifactsEdge deliveryParse contentValidate linksBuild index
Build service layers

C4

Documentation platform[SYSTEM]«person»AuthorWrites and reviewsdocumentation«person»ReaderFinds answers inpublished pages«external system»Git providerStores source and reviewhistory«container»Editor[React]Previews content changes«container»Publishing API[Node.js]Validates and publishesrevisions«container»Public site[Next.js]Serves pages and search«container db»Artifact store[Object storage]Keeps immutablerevisionsEdits pagesPublishes[HTTPS]Readssource[HTTPS]Writes revisionsReadsartifactsBrowses andsearches[HTTPS]
Documentation platform containers

Event modeling

UI/AutomationCommand/Read ModelEventsEditorSubmitRevisionpageId: stringrevision: numberauthor: stringRevisionSubmittedpageId: stringrevision: numberauthor: stringBuildWorkerPublishArtifactArtifactPublishedpageId: stringchecksum: stringurl: stringSearchIndexerSearchUpdated
Publishing events

Kanban

Backlog2Import redirectsMayaAdd SDK examplesSamIn progress2Tune search rankingAlexKeyboard navigationMayaIn review2Migration guideSamCheck contrastAlexDone2Validate linksDeploy previews
Release work board

Packet

VersionMessage typeFlagsPayload lengthRequest IDRevision numberSource IDChecksumContent hashContent hashPayloadPayload034781516313263649596111112127128159160191192223224255
Build protocol message

Quadrant chart

Plan carefullyDo nextFill gapsReconsiderLow effortHigh effortLow impactHigh impactBroken linksSearch rankingFaster previewsNew editorIcon cleanupLegacy export
Prioritizing platform improvements

Requirement

«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
Publication requirements and verification

Timeline

Private previewJanuaryImport existingpagesAdd previewdeploymentsFebruaryInvite pilotteamsCollect searchfeedbackPublic betaMarchLaunch hostedsearchPublish migrationguideAprilAdd versioned docsAuditaccessibilityGeneral availabilityMayEnable customdomainsPublish SDKexamplesJuneOpen self-servicesignupAnnounce supportpolicy
Platform rollout milestones

User journey

54321DiscoverFind thequickstartDeveloperCompareexamplesDeveloperIntegrateCreate an APIkeyDeveloperAdminInstall theSDKDeveloperDebug a failedrequestDeveloperSupportShipRun integrationtestsDeveloperApproveproductionaccessAdminDeploy theapplicationDeveloperAdminAdminDeveloperSupport
A developer's first integration

XY chart

020406080100120W1W2W3W4W5W6W7W8Build time in seconds
Weekly build latency

Agentflow

ReviewWritingResearchChangerequestInspect APIchangesExistingguidesDraftupdatedguideCheckexamplesReady topublish?Open reviewrequest
Assisted documentation review

Cynefin

ComplexProbe → Sense → RespondEmergent PracticesIntermittent latencyUnexpected user behaviorComplicatedSense → Analyse → RespondGood PracticesQuery plan regressionMemory leak analysisChaoticAct → Sense → RespondNovel PracticesRegion outageActive credential leakClearSense → Categorise → RespondBest PracticesExpired certificateFull diskConfusionDisorderStabilize serviceFind a repeatable causeWrite a runbook
Choosing an incident response

Ishikawa

ContentDuplicate examplesLarge imagesInfrastructureCold workersStorage latencyCompilationMissing cache keysRepeated parsingDependenciesFull package rebuildsSlow package downloadsWorkflowSerial upload stepsRedundant checksSlow previewbuilds
Why preview builds are slow

Radar

SpeedControlAffordabilityScalabilitySetup easeObservabilityManagedSelf-hostedHybrid
Comparing deployment options

Railroad

queryfilterANDfilterfilterfield:valuefieldtitletagversionvalueword"phrase"phraseword␣word
Search filter grammar

Tree view

docs-appapplayout.tsxdocspage.tsxcontentguidesquickstart.mdauthentication.mdreferenceclient.mderrors.mdpubliclogo.svgbrief.config.tspackage.json
A documentation application

Treemap

Client JavaScript184Documentation UI71Framework66Interactive mediaInteractive…47Search32Code blocks21Navigation18React42Router24Diagrams27Video12Image viewerImage…8
Client bundle composition

Use case

WorkspaceSite«include»AuthorReviewerReaderEdit draftPreview changesApprove revisionPublish pagesBrowse guidesSearch reference
Documentation workspace roles

Venn

Unit testsPure functionsIntegration testsService contractsBrowser testsUser interactionsValidationNavigationFormattingReleaseconfidence
Testing responsibilities

Wardley map

GenesisCustom BuiltProductCommodityEvolutionVisibilityReaderDocumentationSearchPublishingContent storageHosting
Documentation platform strategy

Label hints

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.