[{"data":1,"prerenderedAt":1003},["ShallowReactive",2],{"blog-post:en:\u002Fen\u002Fblog\u002Fpreview-mermaid-diagrams-in-markdown-online":3},{"id":4,"title":5,"author":6,"body":7,"category":975,"date":976,"description":977,"extension":978,"image":979,"imageAlt":980,"meta":981,"navigation":982,"path":983,"seo":984,"stem":985,"tags":986,"translationKey":987,"updatedAt":976,"__hash__":988,"html":989,"bodyMarkdown":990,"translations":991,"previous":998,"next":986},"blog\u002Fen\u002Fblog\u002F12.preview-mermaid-diagrams-in-markdown-online.md","How to Preview Mermaid Diagrams in Markdown Online","Antoine Frankart",{"type":8,"value":9,"toc":950},"minimark",[10,14,17,22,30,71,77,80,102,105,109,118,135,142,145,148,152,155,282,285,289,292,328,335,345,369,372,376,379,426,429,433,436,498,501,505,508,587,590,594,597,602,605,624,631,635,642,661,664,668,679,702,712,716,723,727,730,734,737,759,765,769,784,798,802,817,821,824,838,841,845,848,852,861,865,879,882,906,909,913,921,924,939,946],[11,12,13],"p",{},"Already have a Mermaid diagram in a README or Markdown file and want to check the result before publishing? Fude's free Markdown viewer shows the source and rendered diagram side by side, directly in your browser.",[11,15,16],{},"Mermaid turns text syntax into a diagram embedded in Markdown. This guide shows you how to add a Mermaid code block, preview it with the Fude sample, test the main diagram types, and fix common rendering errors.",[18,19,21],"h2",{"id":20},"the-shortest-valid-mermaid-block-in-markdown","The shortest valid Mermaid block in Markdown",[11,23,24,25,29],{},"Mermaid source belongs in a code block marked as ",[26,27,28],"code",{},"mermaid",":",[31,32,37],"pre",{"className":33,"code":34,"language":35,"meta":36,"style":36},"language-markdown shiki shiki-themes github-light github-dark","```mermaid\nflowchart LR\n  Draft --> Review\n  Review --> Publish\n```\n","markdown","",[26,38,39,47,53,59,65],{"__ignoreMap":36},[40,41,44],"span",{"class":42,"line":43},"line",1,[40,45,46],{},"```mermaid\n",[40,48,50],{"class":42,"line":49},2,[40,51,52],{},"flowchart LR\n",[40,54,56],{"class":42,"line":55},3,[40,57,58],{},"  Draft --> Review\n",[40,60,62],{"class":42,"line":61},4,[40,63,64],{},"  Review --> Publish\n",[40,66,68],{"class":42,"line":67},5,[40,69,70],{},"```\n",[11,72,73,74,76],{},"The three backticks open and close the code block. The word ",[26,75,28],{}," tells a compatible viewer to interpret the content as a diagram instead of displaying it as ordinary code.",[11,78,79],{},"The first line inside the block identifies the diagram type. In this example:",[81,82,83,90,96],"ul",{},[84,85,86,89],"li",{},[26,87,88],{},"flowchart"," selects a flowchart;",[84,91,92,95],{},[26,93,94],{},"LR"," lays it out from left to right;",[84,97,98,101],{},[26,99,100],{},"Draft --> Review"," creates two nodes and a directed connection.",[11,103,104],{},"If the language label is missing, a standard Markdown renderer will correctly show a code block, but it will not know that it should create a diagram.",[18,106,108],{"id":107},"preview-a-mermaid-diagram-with-fude","Preview a Mermaid diagram with Fude",[11,110,111,112,117],{},"The ",[113,114,116],"a",{"href":115},"\u002Fen\u002Fmarkdown-viewer\u002F","free Fude Markdown viewer"," uses the same rendering pipeline as the desktop reader and runs it locally in your browser.",[119,120,121,129,132],"ol",{},[84,122,123,124,128],{},"Open the viewer and choose ",[125,126,127],"strong",{},"Mermaid sample",".",[84,130,131],{},"Replace the sample nodes and arrows with your own Mermaid source.",[84,133,134],{},"Watch the rendered diagram update in the preview pane.",[11,136,137,138,141],{},"You can also paste a complete README or ",[26,139,140],{},".md"," document containing several diagrams. The viewer keeps headings, paragraphs, tables, highlighted code, and Mermaid blocks together, so you are checking the document that readers will actually see rather than an isolated diagram.",[11,143,144],{},"Nothing you type is uploaded by the viewer. Rendering happens in the current tab, which is useful for architecture notes, internal process maps, and diagrams that contain project names you do not want to send to a conversion service.",[11,146,147],{},"If the syntax is invalid, Fude keeps the source below the error message. You can fix the diagram without losing the rest of the document.",[18,149,151],{"id":150},"which-mermaid-diagram-type-should-you-choose","Which Mermaid diagram type should you choose?",[11,153,154],{},"The first line selects the diagram type. Choose it based on the information you need to communicate:",[156,157,158,174],"table",{},[159,160,161],"thead",{},[162,163,164,168,171],"tr",{},[165,166,167],"th",{},"Need",[165,169,170],{},"First line",[165,172,173],{},"Common use",[175,176,177,191,204,217,230,243,256,269],"tbody",{},[162,178,179,183,188],{},[180,181,182],"td",{},"Show a process or decision",[180,184,185],{},[26,186,187],{},"flowchart LR",[180,189,190],{},"User journeys, pipelines, simple architecture",[162,192,193,196,201],{},[180,194,195],{},"Show messages over time",[180,197,198],{},[26,199,200],{},"sequenceDiagram",[180,202,203],{},"API calls, authentication, events",[162,205,206,209,214],{},[180,207,208],{},"Show the states of an object",[180,210,211],{},[26,212,213],{},"stateDiagram-v2",[180,215,216],{},"Lifecycles, state machines, workflows",[162,218,219,222,227],{},[180,220,221],{},"Show code structure",[180,223,224],{},[26,225,226],{},"classDiagram",[180,228,229],{},"Classes, interfaces, and dependencies",[162,231,232,235,240],{},[180,233,234],{},"Show a data model",[180,236,237],{},[26,238,239],{},"erDiagram",[180,241,242],{},"Entities, relationships, and cardinality",[162,244,245,248,253],{},[180,246,247],{},"Show a schedule",[180,249,250],{},[26,251,252],{},"gantt",[180,254,255],{},"Phases, dependencies, and deadlines",[162,257,258,261,266],{},[180,259,260],{},"Show Git branches",[180,262,263],{},[26,264,265],{},"gitGraph",[180,267,268],{},"Branching strategies and history",[162,270,271,274,279],{},[180,272,273],{},"Organize ideas",[180,275,276],{},[26,277,278],{},"mindmap",[180,280,281],{},"Notes, concepts, and hierarchies",[11,283,284],{},"The four types most often used in technical documentation are covered below. The others follow the same pattern: a declaration on the first line followed by the diagram source.",[18,286,288],{"id":287},"flowchart-example","Flowchart example",[11,290,291],{},"Flowcharts are useful for decision paths, build pipelines, onboarding sequences, and service interactions.",[31,293,296],{"className":294,"code":295,"language":28,"meta":36,"style":36},"language-mermaid shiki shiki-themes github-light github-dark","flowchart LR\n  Source[Markdown source] --> Parse[Parse document]\n  Parse --> HasDiagram{Mermaid block?}\n  HasDiagram -->|Yes| Render[Render diagram]\n  HasDiagram -->|No| Read[Display document]\n  Render --> Read\n",[26,297,298,302,307,312,317,322],{"__ignoreMap":36},[40,299,300],{"class":42,"line":43},[40,301,52],{},[40,303,304],{"class":42,"line":49},[40,305,306],{},"  Source[Markdown source] --> Parse[Parse document]\n",[40,308,309],{"class":42,"line":55},[40,310,311],{},"  Parse --> HasDiagram{Mermaid block?}\n",[40,313,314],{"class":42,"line":61},[40,315,316],{},"  HasDiagram -->|Yes| Render[Render diagram]\n",[40,318,319],{"class":42,"line":67},[40,320,321],{},"  HasDiagram -->|No| Read[Display document]\n",[40,323,325],{"class":42,"line":324},6,[40,326,327],{},"  Render --> Read\n",[11,329,330,331,334],{},"The text inside square brackets becomes a readable node label. A shape wrapped in braces becomes a decision. Labels such as ",[26,332,333],{},"|Yes|"," describe individual connections.",[11,336,337,338,341,342,344],{},"Use ",[26,339,340],{},"TD"," instead of ",[26,343,94],{}," when a top-to-bottom diagram fits the page better:",[31,346,348],{"className":294,"code":347,"language":28,"meta":36,"style":36},"flowchart TD\n  Idea --> Draft\n  Draft --> Review\n  Review --> Release\n",[26,349,350,355,360,364],{"__ignoreMap":36},[40,351,352],{"class":42,"line":43},[40,353,354],{},"flowchart TD\n",[40,356,357],{"class":42,"line":49},[40,358,359],{},"  Idea --> Draft\n",[40,361,362],{"class":42,"line":55},[40,363,58],{},[40,365,366],{"class":42,"line":61},[40,367,368],{},"  Review --> Release\n",[11,370,371],{},"Wide diagrams can become difficult to read on phones, so changing direction is often more effective than adding more styling.",[18,373,375],{"id":374},"sequence-diagram-example","Sequence diagram example",[11,377,378],{},"A sequence diagram focuses on messages exchanged over time. It works well for API calls, sign-in flows, background jobs, and interactions between an application and a database.",[31,380,382],{"className":294,"code":381,"language":28,"meta":36,"style":36},"sequenceDiagram\n  participant Reader\n  participant Renderer\n  participant Mermaid\n  Reader->>Renderer: Paste Markdown\n  Renderer->>Mermaid: Send diagram source\n  Mermaid-->>Renderer: Return SVG\n  Renderer-->>Reader: Show preview\n",[26,383,384,389,394,399,404,409,414,420],{"__ignoreMap":36},[40,385,386],{"class":42,"line":43},[40,387,388],{},"sequenceDiagram\n",[40,390,391],{"class":42,"line":49},[40,392,393],{},"  participant Reader\n",[40,395,396],{"class":42,"line":55},[40,397,398],{},"  participant Renderer\n",[40,400,401],{"class":42,"line":61},[40,402,403],{},"  participant Mermaid\n",[40,405,406],{"class":42,"line":67},[40,407,408],{},"  Reader->>Renderer: Paste Markdown\n",[40,410,411],{"class":42,"line":324},[40,412,413],{},"  Renderer->>Mermaid: Send diagram source\n",[40,415,417],{"class":42,"line":416},7,[40,418,419],{},"  Mermaid-->>Renderer: Return SVG\n",[40,421,423],{"class":42,"line":422},8,[40,424,425],{},"  Renderer-->>Reader: Show preview\n",[11,427,428],{},"Participants appear from left to right. Solid arrows usually represent a request, while dashed arrows are useful for a response. The source stays compact even when the rendered interaction contains several actors.",[18,430,432],{"id":431},"class-diagram-example","Class diagram example",[11,434,435],{},"Class diagrams describe types and their relationships. They are useful in technical documentation when a short structural overview communicates more than a complete generated API reference.",[31,437,439],{"className":294,"code":438,"language":28,"meta":36,"style":36},"classDiagram\n  class MarkdownDocument {\n    +string title\n    +string body\n    +render()\n  }\n  class MermaidBlock {\n    +string source\n    +renderSvg()\n  }\n  MarkdownDocument \"1\" --> \"0..*\" MermaidBlock : contains\n",[26,440,441,446,451,456,461,466,471,476,481,487,492],{"__ignoreMap":36},[40,442,443],{"class":42,"line":43},[40,444,445],{},"classDiagram\n",[40,447,448],{"class":42,"line":49},[40,449,450],{},"  class MarkdownDocument {\n",[40,452,453],{"class":42,"line":55},[40,454,455],{},"    +string title\n",[40,457,458],{"class":42,"line":61},[40,459,460],{},"    +string body\n",[40,462,463],{"class":42,"line":67},[40,464,465],{},"    +render()\n",[40,467,468],{"class":42,"line":324},[40,469,470],{},"  }\n",[40,472,473],{"class":42,"line":416},[40,474,475],{},"  class MermaidBlock {\n",[40,477,478],{"class":42,"line":422},[40,479,480],{},"    +string source\n",[40,482,484],{"class":42,"line":483},9,[40,485,486],{},"    +renderSvg()\n",[40,488,490],{"class":42,"line":489},10,[40,491,470],{},[40,493,495],{"class":42,"line":494},11,[40,496,497],{},"  MarkdownDocument \"1\" --> \"0..*\" MermaidBlock : contains\n",[11,499,500],{},"Keep these diagrams selective. Showing every property and method can turn a useful map into a second, harder-to-maintain version of the codebase.",[18,502,504],{"id":503},"entity-relationship-diagram-example","Entity relationship diagram example",[11,506,507],{},"Entity relationship diagrams document stored data and cardinality. They are especially helpful in architecture notes and migration plans.",[31,509,511],{"className":294,"code":510,"language":28,"meta":36,"style":36},"erDiagram\n  PROJECT ||--o{ DOCUMENT : contains\n  DOCUMENT ||--o{ DIAGRAM : includes\n  PROJECT {\n    string id\n    string name\n  }\n  DOCUMENT {\n    string id\n    string path\n  }\n  DIAGRAM {\n    string id\n    string source\n  }\n",[26,512,513,518,523,528,533,538,543,547,552,556,561,565,571,576,582],{"__ignoreMap":36},[40,514,515],{"class":42,"line":43},[40,516,517],{},"erDiagram\n",[40,519,520],{"class":42,"line":49},[40,521,522],{},"  PROJECT ||--o{ DOCUMENT : contains\n",[40,524,525],{"class":42,"line":55},[40,526,527],{},"  DOCUMENT ||--o{ DIAGRAM : includes\n",[40,529,530],{"class":42,"line":61},[40,531,532],{},"  PROJECT {\n",[40,534,535],{"class":42,"line":67},[40,536,537],{},"    string id\n",[40,539,540],{"class":42,"line":324},[40,541,542],{},"    string name\n",[40,544,545],{"class":42,"line":416},[40,546,470],{},[40,548,549],{"class":42,"line":422},[40,550,551],{},"  DOCUMENT {\n",[40,553,554],{"class":42,"line":483},[40,555,537],{},[40,557,558],{"class":42,"line":489},[40,559,560],{},"    string path\n",[40,562,563],{"class":42,"line":494},[40,564,470],{},[40,566,568],{"class":42,"line":567},12,[40,569,570],{},"  DIAGRAM {\n",[40,572,574],{"class":42,"line":573},13,[40,575,537],{},[40,577,579],{"class":42,"line":578},14,[40,580,581],{},"    string source\n",[40,583,585],{"class":42,"line":584},15,[40,586,470],{},[11,588,589],{},"An ER diagram is not a substitute for your real schema or migrations. It is a readable overview that helps people understand the important entities before they inspect implementation details.",[18,591,593],{"id":592},"write-mermaid-source-that-stays-readable-and-portable","Write Mermaid source that stays readable and portable",[11,595,596],{},"A diagram can render correctly today and still become difficult to maintain after several edits. A few conventions prevent most problems.",[598,599,601],"h3",{"id":600},"separate-identifiers-from-labels","Separate identifiers from labels",[11,603,604],{},"Use short, stable identifiers in relationships, then put the displayed text inside brackets and quotes:",[31,606,608],{"className":294,"code":607,"language":28,"meta":36,"style":36},"flowchart LR\n  draft[\"Draft ready\"] --> review[\"Technical review\"]\n  review --> publish[\"Publish\"]\n",[26,609,610,614,619],{"__ignoreMap":36},[40,611,612],{"class":42,"line":43},[40,613,52],{},[40,615,616],{"class":42,"line":49},[40,617,618],{},"  draft[\"Draft ready\"] --> review[\"Technical review\"]\n",[40,620,621],{"class":42,"line":55},[40,622,623],{},"  review --> publish[\"Publish\"]\n",[11,625,626,627,630],{},"You can change “Technical review” later without renaming every relationship that uses ",[26,628,629],{},"review",". Quotes also make spaces, punctuation, and Unicode text less ambiguous to the Mermaid parser.",[598,632,634],{"id":633},"comment-the-source","Comment the source",[11,636,637,638,641],{},"A line beginning with ",[26,639,640],{},"%%"," is a Mermaid comment and does not appear in the rendered diagram:",[31,643,645],{"className":294,"code":644,"language":28,"meta":36,"style":36},"flowchart LR\n  %% Legal review is optional for an internal draft.\n  draft[\"Draft\"] --> review[\"Review\"] --> publish[\"Publish\"]\n",[26,646,647,651,656],{"__ignoreMap":36},[40,648,649],{"class":42,"line":43},[40,650,52],{},[40,652,653],{"class":42,"line":49},[40,654,655],{},"  %% Legal review is optional for an internal draft.\n",[40,657,658],{"class":42,"line":55},[40,659,660],{},"  draft[\"Draft\"] --> review[\"Review\"] --> publish[\"Publish\"]\n",[11,662,663],{},"Comments are useful for documenting layout constraints or the reason behind a relationship without adding more text to the visual output.",[598,665,667],{"id":666},"add-an-accessible-title-and-description","Add an accessible title and description",[11,669,670,671,674,675,678],{},"Mermaid supports ",[26,672,673],{},"accTitle"," and ",[26,676,677],{},"accDescr",", which add a title and description to the generated SVG. They help screen-reader users and provide a textual equivalent of the diagram:",[31,680,682],{"className":294,"code":681,"language":28,"meta":36,"style":36},"flowchart LR\n  accTitle: Document publishing workflow\n  accDescr: A draft goes through review before it is published.\n  draft[\"Draft\"] --> review[\"Review\"] --> publish[\"Publish\"]\n",[26,683,684,688,693,698],{"__ignoreMap":36},[40,685,686],{"class":42,"line":43},[40,687,52],{},[40,689,690],{"class":42,"line":49},[40,691,692],{},"  accTitle: Document publishing workflow\n",[40,694,695],{"class":42,"line":55},[40,696,697],{},"  accDescr: A draft goes through review before it is published.\n",[40,699,700],{"class":42,"line":61},[40,701,660],{},[11,703,704,705,711],{},"Keep the title short. The description should communicate the useful conclusion rather than list every shape. The ",[113,706,710],{"href":707,"rel":708},"https:\u002F\u002Fmermaid.js.org\u002Fconfig\u002Faccessibility.html",[709],"nofollow","Mermaid accessibility documentation"," also covers multi-line descriptions.",[598,713,715],{"id":714},"do-not-rely-on-interactions-or-a-specific-theme","Do not rely on interactions or a specific theme",[11,717,718,719,722],{},"Fude renders diagrams in strict security mode and adapts their colors to the reader theme. Treat the result as a static visual: do not depend on a ",[26,720,721],{},"click"," action, HTML inside a label, or pixel-perfect positioning. The same rule improves compatibility with other Markdown viewers.",[18,724,726],{"id":725},"why-a-mermaid-diagram-fails-to-render","Why a Mermaid diagram fails to render",[11,728,729],{},"When a diagram fails, keep the rest of the Markdown document intact and reduce the Mermaid block until the smallest version renders.",[598,731,733],{"id":732},"the-code-block-is-not-marked-as-mermaid","The code block is not marked as Mermaid",[11,735,736],{},"This is ordinary Markdown code, not a Mermaid diagram:",[31,738,740],{"className":33,"code":739,"language":35,"meta":36,"style":36},"```\nflowchart LR\n  A --> B\n```\n",[26,741,742,746,750,755],{"__ignoreMap":36},[40,743,744],{"class":42,"line":43},[40,745,70],{},[40,747,748],{"class":42,"line":49},[40,749,52],{},[40,751,752],{"class":42,"line":55},[40,753,754],{},"  A --> B\n",[40,756,757],{"class":42,"line":61},[40,758,70],{},[11,760,761,762,764],{},"Add ",[26,763,28],{}," immediately after the opening backticks.",[598,766,768],{"id":767},"a-reserved-word-is-used-as-a-label","A reserved word is used as a label",[11,770,771,772,775,776,779,780,783],{},"In a flowchart, the lowercase word ",[26,773,774],{},"end"," can be interpreted as the end of a subgraph. Write ",[26,777,778],{},"End",", ",[26,781,782],{},"END",", or use a separate identifier with a quoted label:",[31,785,787],{"className":294,"code":786,"language":28,"meta":36,"style":36},"flowchart LR\n  start[\"Start\"] --> finish[\"End\"]\n",[26,788,789,793],{"__ignoreMap":36},[40,790,791],{"class":42,"line":43},[40,792,52],{},[40,794,795],{"class":42,"line":49},[40,796,797],{},"  start[\"Start\"] --> finish[\"End\"]\n",[598,799,801],{"id":800},"the-diagram-type-is-misspelled","The diagram type is misspelled",[11,803,804,805,779,807,779,809,811,812,814,815,128],{},"The first Mermaid line must use a supported diagram declaration such as ",[26,806,88],{},[26,808,200],{},[26,810,226],{},", or ",[26,813,239],{},". Capitalization matters for declarations such as ",[26,816,200],{},[598,818,820],{"id":819},"a-node-label-breaks-the-grammar","A node label breaks the grammar",[11,822,823],{},"Punctuation that also has meaning in Mermaid can make an otherwise simple label ambiguous. Give the node an identifier and place its readable label inside brackets:",[31,825,827],{"className":294,"code":826,"language":28,"meta":36,"style":36},"flowchart LR\n  Start[Start: read the file] --> Finish[Finish: show the preview]\n",[26,828,829,833],{"__ignoreMap":36},[40,830,831],{"class":42,"line":43},[40,832,52],{},[40,834,835],{"class":42,"line":49},[40,836,837],{},"  Start[Start: read the file] --> Finish[Finish: show the preview]\n",[11,839,840],{},"If a complex label still fails, temporarily replace it with a single word. Add the original text back only after the diagram structure works.",[598,842,844],{"id":843},"the-diagram-is-too-large-for-the-page","The diagram is too large for the page",[11,846,847],{},"A valid diagram may still be uncomfortable to read. Try a different direction, split one large diagram into two focused diagrams, or remove details that belong in the surrounding prose. A diagram should clarify the document, not reproduce it.",[598,849,851],{"id":850},"two-viewers-render-slightly-differently","Two viewers render slightly differently",[11,853,854,855,860],{},"Mermaid evolves, and products do not always bundle the same version or theme. Test a diagram in the destination where people will read it. Keep the source portable, avoid depending on a very specific pixel layout, and consult the ",[113,856,859],{"href":857,"rel":858},"https:\u002F\u002Fmermaid.js.org\u002Fintro\u002F",[709],"official Mermaid syntax documentation"," for the diagram type you use.",[18,862,864],{"id":863},"compatibility-with-github-gitlab-and-markdown-viewers","Compatibility with GitHub, GitLab, and Markdown viewers",[11,866,867,872,873,878],{},[113,868,871],{"href":869,"rel":870},"https:\u002F\u002Fdocs.github.com\u002Fen\u002Fget-started\u002Fwriting-on-github\u002Fworking-with-advanced-formatting\u002Fcreating-diagrams",[709],"GitHub supports Mermaid"," in Markdown files, issues, pull requests, discussions, and wikis. ",[113,874,877],{"href":875,"rel":876},"https:\u002F\u002Fdocs.gitlab.com\u002Fuser\u002Fmarkdown\u002F#mermaid",[709],"GitLab also supports Mermaid blocks",", but each platform chooses its own Mermaid version and security rules.",[11,880,881],{},"A diagram can therefore work in Fude and fail elsewhere if it uses recently added syntax, local configuration, or an interaction disabled by the destination. For the best portability:",[81,883,884,897,900,903],{},[84,885,886,887,779,889,779,891,893,894,896],{},"prefer stable types such as ",[26,888,88],{},[26,890,200],{},[26,892,226],{},", and ",[26,895,239],{},";",[84,898,899],{},"keep identifiers simple and quote displayed labels;",[84,901,902],{},"avoid interactive links, HTML, and theme settings that are essential to understanding the diagram;",[84,904,905],{},"test the document in its final destination before publishing.",[11,907,908],{},"A Markdown viewer without Mermaid support will display the code block instead. The sentence before the diagram should still explain its purpose.",[18,910,912],{"id":911},"mermaid-and-the-rest-of-your-markdown-document","Mermaid and the rest of your Markdown document",[11,914,915,916,920],{},"The biggest advantage of a Mermaid-aware Markdown viewer is context. A diagram can sit directly after the explanation it supports, alongside a ",[113,917,919],{"href":918},"\u002Fen\u002Fblog\u002Fmarkdown-table-complete-guide-with-examples\u002F","Markdown table",", code samples, links, and task lists.",[11,922,923],{},"Use prose to explain why a system behaves a certain way. Use the diagram to show relationships, direction, or sequence. Add a short sentence before every diagram so a reader who cannot render Mermaid still understands its purpose.",[11,925,926,927,929,930,934,935,938],{},"If you received an unfamiliar ",[26,928,140],{}," file, start with the guide to ",[113,931,933],{"href":932},"\u002Fen\u002Fblog\u002Fwhat-is-markdown-file-how-to-open\u002F","opening and reading Markdown files",". Then paste the document into the ",[113,936,937],{"href":115},"online Markdown viewer"," and select the Mermaid sample whenever you need a clean starting point.",[11,940,941,942,128],{},"For a local library of Markdown documents with themes, projects, and offline reading, ",[113,943,945],{"href":944},"\u002Fen\u002F#download","download Fude for macOS",[947,948,949],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":36,"searchDepth":49,"depth":49,"links":951},[952,953,954,955,956,957,958,959,965,973,974],{"id":20,"depth":49,"text":21},{"id":107,"depth":49,"text":108},{"id":150,"depth":49,"text":151},{"id":287,"depth":49,"text":288},{"id":374,"depth":49,"text":375},{"id":431,"depth":49,"text":432},{"id":503,"depth":49,"text":504},{"id":592,"depth":49,"text":593,"children":960},[961,962,963,964],{"id":600,"depth":55,"text":601},{"id":633,"depth":55,"text":634},{"id":666,"depth":55,"text":667},{"id":714,"depth":55,"text":715},{"id":725,"depth":49,"text":726,"children":966},[967,968,969,970,971,972],{"id":732,"depth":55,"text":733},{"id":767,"depth":55,"text":768},{"id":800,"depth":55,"text":801},{"id":819,"depth":55,"text":820},{"id":843,"depth":55,"text":844},{"id":850,"depth":55,"text":851},{"id":863,"depth":49,"text":864},{"id":911,"depth":49,"text":912},"markdown-guides","2026-08-18","Preview and test Mermaid diagrams in Markdown with Fude, including flowchart, sequence, class, ER examples, and fixes for common rendering errors.","md","\u002Fimages\u002Fblog\u002Fblog12","Mermaid source in a Markdown editor becoming a rendered flowchart",{},false,"\u002Fen\u002Fblog\u002Fpreview-mermaid-diagrams-in-markdown-online",{"title":5,"description":977},"en\u002Fblog\u002F12.preview-mermaid-diagrams-in-markdown-online",null,"preview-mermaid-diagrams-markdown","oD0wgq1jfrRb39sDqY_Tdmv5Dv7xeeoMdKMYIUoaM70","\u003Cp data-fude-source-line=\"2\">\u003Cspan data-fude-source-start=\"1\" data-fude-source-end=\"214\">Already have a Mermaid diagram in a README or Markdown file and want to check the result before publishing? Fude's free Markdown viewer shows the source and rendered diagram side by side, directly in your browser.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cp data-fude-source-line=\"4\">\u003Cspan data-fude-source-start=\"216\" data-fude-source-end=\"427\">Mermaid turns text syntax into a diagram embedded in Markdown. This guide shows you how to add a Mermaid code block, preview it with the Fude sample, test the main diagram types, and fix common rendering errors.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-the-shortest-valid-mermaid-block-in-markdown\" data-fude-source-line=\"6\">\u003Cspan data-fude-source-start=\"432\" data-fude-source-end=\"476\">The shortest valid Mermaid block in Markdown\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"8\">\u003Cspan data-fude-source-start=\"478\" data-fude-source-end=\"527\">Mermaid source belongs in a code block marked as \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"527\" data-fude-source-end=\"536\">mermaid\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"536\" data-fude-source-end=\"537\">:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cpre style=\"background-color:var(--fude-code-background, var(--color-code-bg));color:var(--fude-code-foreground, var(--color-code-text))\" tabindex=\"0\" class=\"shiki fude-code-theme fude-code-block\" data-language=\"markdown\" data-fude-code-block-start=\"552\" data-fude-code-block-end=\"619\" data-fude-source-line=\"10\">\u003Ccode class=\"language-markdown\" data-language=\"markdown\" data-fude-code-block-start=\"552\" data-fude-code-block-end=\"619\">\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--fude-code-token-string, color-mix(in srgb, var(--color-accent-primary) 78%, var(--color-code-text) 22%))\">```mermaid\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--fude-code-token-string, color-mix(in srgb, var(--color-accent-primary) 78%, var(--color-code-text) 22%))\">flowchart LR\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--fude-code-token-string, color-mix(in srgb, var(--color-accent-primary) 78%, var(--color-code-text) 22%))\">  Draft --> Review\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--fude-code-token-string, color-mix(in srgb, var(--color-accent-primary) 78%, var(--color-code-text) 22%))\">  Review --> Publish\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--fude-code-token-string, color-mix(in srgb, var(--color-accent-primary) 78%, var(--color-code-text) 22%))\">```\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp data-fude-source-line=\"18\">\u003Cspan data-fude-source-start=\"626\" data-fude-source-end=\"686\">The three backticks open and close the code block. The word \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"686\" data-fude-source-end=\"695\">mermaid\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"695\" data-fude-source-end=\"802\"> tells a compatible viewer to interpret the content as a diagram instead of displaying it as ordinary code.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cp data-fude-source-line=\"20\">\u003Cspan data-fude-source-start=\"804\" data-fude-source-end=\"881\">The first line inside the block identifies the diagram type. In this example:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cul data-fude-source-line=\"22\">\n\u003Cli>\u003Ccode>\u003Cspan data-fude-source-start=\"885\" data-fude-source-end=\"896\">flowchart\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"896\" data-fude-source-end=\"917\"> selects a flowchart;\u003C\u002Fspan>\u003C\u002Fli>\n\u003Cli>\u003Ccode>\u003Cspan data-fude-source-start=\"920\" data-fude-source-end=\"924\">LR\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"924\" data-fude-source-end=\"956\"> lays it out from left to right;\u003C\u002Fspan>\u003C\u002Fli>\n\u003Cli>\u003Ccode>\u003Cspan data-fude-source-start=\"959\" data-fude-source-end=\"977\">Draft --> Review\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"977\" data-fude-source-end=\"1022\"> creates two nodes and a directed connection.\u003C\u002Fspan>\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp data-fude-source-line=\"26\">\u003Cspan data-fude-source-start=\"1024\" data-fude-source-end=\"1174\">If the language label is missing, a standard Markdown renderer will correctly show a code block, but it will not know that it should create a diagram.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-preview-a-mermaid-diagram-with-fude\" data-fude-source-line=\"28\">\u003Cspan data-fude-source-start=\"1179\" data-fude-source-end=\"1214\">Preview a Mermaid diagram with Fude\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"30\">\u003Cspan data-fude-source-start=\"1216\" data-fude-source-end=\"1220\">The \u003C\u002Fspan>\u003Ca href=\"\u002Fen\u002Fmarkdown-viewer\u002F\" data-fude-link-kind=\"unopenable\">\u003Cspan data-fude-source-start=\"1221\" data-fude-source-end=\"1246\">free Fude Markdown viewer\u003C\u002Fspan>\u003C\u002Fa>\u003Cspan data-fude-source-start=\"1269\" data-fude-source-end=\"1361\"> uses the same rendering pipeline as the desktop reader and runs it locally in your browser.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Col data-fude-source-line=\"32\">\n\u003Cli>\u003Cspan data-fude-source-start=\"1366\" data-fude-source-end=\"1393\">Open the viewer and choose \u003C\u002Fspan>\u003Cstrong>\u003Cspan data-fude-source-start=\"1395\" data-fude-source-end=\"1409\">Mermaid sample\u003C\u002Fspan>\u003C\u002Fstrong>\u003Cspan data-fude-source-start=\"1411\" data-fude-source-end=\"1412\">.\u003C\u002Fspan>\u003C\u002Fli>\n\u003Cli>\u003Cspan data-fude-source-start=\"1416\" data-fude-source-end=\"1481\">Replace the sample nodes and arrows with your own Mermaid source.\u003C\u002Fspan>\u003C\u002Fli>\n\u003Cli>\u003Cspan data-fude-source-start=\"1485\" data-fude-source-end=\"1539\">Watch the rendered diagram update in the preview pane.\u003C\u002Fspan>\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp data-fude-source-line=\"36\">\u003Cspan data-fude-source-start=\"1541\" data-fude-source-end=\"1581\">You can also paste a complete README or \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"1581\" data-fude-source-end=\"1586\">.md\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"1586\" data-fude-source-end=\"1815\"> document containing several diagrams. The viewer keeps headings, paragraphs, tables, highlighted code, and Mermaid blocks together, so you are checking the document that readers will actually see rather than an isolated diagram.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cp data-fude-source-line=\"38\">\u003Cspan data-fude-source-start=\"1817\" data-fude-source-end=\"2050\">Nothing you type is uploaded by the viewer. Rendering happens in the current tab, which is useful for architecture notes, internal process maps, and diagrams that contain project names you do not want to send to a conversion service.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cp data-fude-source-line=\"40\">\u003Cspan data-fude-source-start=\"2052\" data-fude-source-end=\"2189\">If the syntax is invalid, Fude keeps the source below the error message. You can fix the diagram without losing the rest of the document.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-which-mermaid-diagram-type-should-you-choose\" data-fude-source-line=\"42\">\u003Cspan data-fude-source-start=\"2194\" data-fude-source-end=\"2239\">Which Mermaid diagram type should you choose?\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"44\">\u003Cspan data-fude-source-start=\"2241\" data-fude-source-end=\"2341\">The first line selects the diagram type. Choose it based on the information you need to communicate:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ctable data-fude-source-line=\"46\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>\u003Cspan data-fude-source-start=\"2345\" data-fude-source-end=\"2349\">Need\u003C\u002Fspan>\u003C\u002Fth>\n\u003Cth>\u003Cspan data-fude-source-start=\"2352\" data-fude-source-end=\"2362\">First line\u003C\u002Fspan>\u003C\u002Fth>\n\u003Cth>\u003Cspan data-fude-source-start=\"2365\" data-fude-source-end=\"2375\">Common use\u003C\u002Fspan>\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2400\" data-fude-source-end=\"2426\">Show a process or decision\u003C\u002Fspan>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u003Cspan data-fude-source-start=\"2429\" data-fude-source-end=\"2443\">flowchart LR\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2446\" data-fude-source-end=\"2491\">User journeys, pipelines, simple architecture\u003C\u002Fspan>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2496\" data-fude-source-end=\"2519\">Show messages over time\u003C\u002Fspan>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u003Cspan data-fude-source-start=\"2522\" data-fude-source-end=\"2539\">sequenceDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2542\" data-fude-source-end=\"2575\">API calls, authentication, events\u003C\u002Fspan>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2580\" data-fude-source-end=\"2608\">Show the states of an object\u003C\u002Fspan>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u003Cspan data-fude-source-start=\"2611\" data-fude-source-end=\"2628\">stateDiagram-v2\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2631\" data-fude-source-end=\"2668\">Lifecycles, state machines, workflows\u003C\u002Fspan>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2673\" data-fude-source-end=\"2692\">Show code structure\u003C\u002Fspan>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u003Cspan data-fude-source-start=\"2695\" data-fude-source-end=\"2709\">classDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2712\" data-fude-source-end=\"2749\">Classes, interfaces, and dependencies\u003C\u002Fspan>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2754\" data-fude-source-end=\"2771\">Show a data model\u003C\u002Fspan>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u003Cspan data-fude-source-start=\"2774\" data-fude-source-end=\"2785\">erDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2788\" data-fude-source-end=\"2828\">Entities, relationships, and cardinality\u003C\u002Fspan>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2833\" data-fude-source-end=\"2848\">Show a schedule\u003C\u002Fspan>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u003Cspan data-fude-source-start=\"2851\" data-fude-source-end=\"2858\">gantt\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2861\" data-fude-source-end=\"2896\">Phases, dependencies, and deadlines\u003C\u002Fspan>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2901\" data-fude-source-end=\"2918\">Show Git branches\u003C\u002Fspan>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u003Cspan data-fude-source-start=\"2921\" data-fude-source-end=\"2931\">gitGraph\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2934\" data-fude-source-end=\"2966\">Branching strategies and history\u003C\u002Fspan>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cspan data-fude-source-start=\"2971\" data-fude-source-end=\"2985\">Organize ideas\u003C\u002Fspan>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u003Cspan data-fude-source-start=\"2988\" data-fude-source-end=\"2997\">mindmap\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Cspan data-fude-source-start=\"3000\" data-fude-source-end=\"3032\">Notes, concepts, and hierarchies\u003C\u002Fspan>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003Cp data-fude-source-line=\"57\">\u003Cspan data-fude-source-start=\"3036\" data-fude-source-end=\"3212\">The four types most often used in technical documentation are covered below. The others follow the same pattern: a declaration on the first line followed by the diagram source.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-flowchart-example\" data-fude-source-line=\"59\">\u003Cspan data-fude-source-start=\"3217\" data-fude-source-end=\"3234\">Flowchart example\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"61\">\u003Cspan data-fude-source-start=\"3236\" data-fude-source-end=\"3342\">Flowcharts are useful for decision paths, build pipelines, onboarding sequences, and service interactions.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"flowchart LR\n  Source[Markdown source] --> Parse[Parse document]\n  Parse --> HasDiagram{Mermaid block?}\n  HasDiagram -->|Yes| Render[Render diagram]\n  HasDiagram -->|No| Read[Display document]\n  Render --> Read\" data-fude-mermaid-id=\"mermaid-1\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"63\">\u003C\u002Fdiv>\n\u003Cp data-fude-source-line=\"72\">\u003Cspan data-fude-source-start=\"3571\" data-fude-source-end=\"3695\">The text inside square brackets becomes a readable node label. A shape wrapped in braces becomes a decision. Labels such as \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"3695\" data-fude-source-end=\"3702\">|Yes|\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"3702\" data-fude-source-end=\"3735\"> describe individual connections.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cp data-fude-source-line=\"74\">\u003Cspan data-fude-source-start=\"3737\" data-fude-source-end=\"3741\">Use \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"3741\" data-fude-source-end=\"3745\">TD\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"3745\" data-fude-source-end=\"3757\"> instead of \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"3757\" data-fude-source-end=\"3761\">LR\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"3761\" data-fude-source-end=\"3812\"> when a top-to-bottom diagram fits the page better:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"flowchart TD\n  Idea --> Draft\n  Draft --> Review\n  Review --> Release\" data-fude-mermaid-id=\"mermaid-2\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"76\">\u003C\u002Fdiv>\n\u003Cp data-fude-source-line=\"83\">\u003Cspan data-fude-source-start=\"3900\" data-fude-source-end=\"4025\">Wide diagrams can become difficult to read on phones, so changing direction is often more effective than adding more styling.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-sequence-diagram-example\" data-fude-source-line=\"85\">\u003Cspan data-fude-source-start=\"4030\" data-fude-source-end=\"4054\">Sequence diagram example\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"87\">\u003Cspan data-fude-source-start=\"4056\" data-fude-source-end=\"4232\">A sequence diagram focuses on messages exchanged over time. It works well for API calls, sign-in flows, background jobs, and interactions between an application and a database.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"sequenceDiagram\n  participant Reader\n  participant Renderer\n  participant Mermaid\n  Reader->>Renderer: Paste Markdown\n  Renderer->>Mermaid: Send diagram source\n  Mermaid-->>Renderer: Return SVG\n  Renderer-->>Reader: Show preview\" data-fude-mermaid-id=\"mermaid-3\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"89\">\u003C\u002Fdiv>\n\u003Cp data-fude-source-line=\"100\">\u003Cspan data-fude-source-start=\"4479\" data-fude-source-end=\"4692\">Participants appear from left to right. Solid arrows usually represent a request, while dashed arrows are useful for a response. The source stays compact even when the rendered interaction contains several actors.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-class-diagram-example\" data-fude-source-line=\"102\">\u003Cspan data-fude-source-start=\"4697\" data-fude-source-end=\"4718\">Class diagram example\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"104\">\u003Cspan data-fude-source-start=\"4720\" data-fude-source-end=\"4909\">Class diagrams describe types and their relationships. They are useful in technical documentation when a short structural overview communicates more than a complete generated API reference.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"classDiagram\n  class MarkdownDocument {\n    +string title\n    +string body\n    +render()\n  }\n  class MermaidBlock {\n    +string source\n    +renderSvg()\n  }\n  MarkdownDocument "1" --> "0..*" MermaidBlock : contains\" data-fude-mermaid-id=\"mermaid-4\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"106\">\u003C\u002Fdiv>\n\u003Cp data-fude-source-line=\"120\">\u003Cspan data-fude-source-start=\"5141\" data-fude-source-end=\"5286\">Keep these diagrams selective. Showing every property and method can turn a useful map into a second, harder-to-maintain version of the codebase.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-entity-relationship-diagram-example\" data-fude-source-line=\"122\">\u003Cspan data-fude-source-start=\"5291\" data-fude-source-end=\"5326\">Entity relationship diagram example\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"124\">\u003Cspan data-fude-source-start=\"5328\" data-fude-source-end=\"5465\">Entity relationship diagrams document stored data and cardinality. They are especially helpful in architecture notes and migration plans.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"erDiagram\n  PROJECT ||--o{ DOCUMENT : contains\n  DOCUMENT ||--o{ DIAGRAM : includes\n  PROJECT {\n    string id\n    string name\n  }\n  DOCUMENT {\n    string id\n    string path\n  }\n  DIAGRAM {\n    string id\n    string source\n  }\" data-fude-mermaid-id=\"mermaid-5\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"126\">\u003C\u002Fdiv>\n\u003Cp data-fude-source-line=\"144\">\u003Cspan data-fude-source-start=\"5708\" data-fude-source-end=\"5899\">An ER diagram is not a substitute for your real schema or migrations. It is a readable overview that helps people understand the important entities before they inspect implementation details.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-write-mermaid-source-that-stays-readable-and-portable\" data-fude-source-line=\"146\">\u003Cspan data-fude-source-start=\"5904\" data-fude-source-end=\"5957\">Write Mermaid source that stays readable and portable\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"148\">\u003Cspan data-fude-source-start=\"5959\" data-fude-source-end=\"6096\">A diagram can render correctly today and still become difficult to maintain after several edits. A few conventions prevent most problems.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch3 id=\"user-content-separate-identifiers-from-labels\" data-fude-source-line=\"150\">\u003Cspan data-fude-source-start=\"6102\" data-fude-source-end=\"6134\">Separate identifiers from labels\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"152\">\u003Cspan data-fude-source-start=\"6136\" data-fude-source-end=\"6239\">Use short, stable identifiers in relationships, then put the displayed text inside brackets and quotes:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"flowchart LR\n  draft["Draft ready"] --> review["Technical review"]\n  review --> publish["Publish"]\" data-fude-mermaid-id=\"mermaid-6\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"154\">\u003C\u002Fdiv>\n\u003Cp data-fude-source-line=\"160\">\u003Cspan data-fude-source-start=\"6356\" data-fude-source-end=\"6442\">You can change “Technical review” later without renaming every relationship that uses \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"6442\" data-fude-source-end=\"6450\">review\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"6450\" data-fude-source-end=\"6544\">. Quotes also make spaces, punctuation, and Unicode text less ambiguous to the Mermaid parser.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch3 id=\"user-content-comment-the-source\" data-fude-source-line=\"162\">\u003Cspan data-fude-source-start=\"6550\" data-fude-source-end=\"6568\">Comment the source\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"164\">\u003Cspan data-fude-source-start=\"6570\" data-fude-source-end=\"6592\">A line beginning with \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"6592\" data-fude-source-end=\"6596\">%%\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"6596\" data-fude-source-end=\"6662\"> is a Mermaid comment and does not appear in the rendered diagram:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"flowchart LR\n  %% Legal review is optional for an internal draft.\n  draft["Draft"] --> review["Review"] --> publish["Publish"]\" data-fude-mermaid-id=\"mermaid-7\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"166\">\u003C\u002Fdiv>\n\u003Cp data-fude-source-line=\"172\">\u003Cspan data-fude-source-start=\"6807\" data-fude-source-end=\"6944\">Comments are useful for documenting layout constraints or the reason behind a relationship without adding more text to the visual output.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch3 id=\"user-content-add-an-accessible-title-and-description\" data-fude-source-line=\"174\">\u003Cspan data-fude-source-start=\"6950\" data-fude-source-end=\"6989\">Add an accessible title and description\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"176\">\u003Cspan data-fude-source-start=\"6991\" data-fude-source-end=\"7008\">Mermaid supports \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"7008\" data-fude-source-end=\"7018\">accTitle\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"7018\" data-fude-source-end=\"7023\"> and \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"7023\" data-fude-source-end=\"7033\">accDescr\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"7033\" data-fude-source-end=\"7169\">, which add a title and description to the generated SVG. They help screen-reader users and provide a textual equivalent of the diagram:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"flowchart LR\n  accTitle: Document publishing workflow\n  accDescr: A draft goes through review before it is published.\n  draft["Draft"] --> review["Review"] --> publish["Publish"]\" data-fude-mermaid-id=\"mermaid-8\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"178\">\u003C\u002Fdiv>\n\u003Cp data-fude-source-line=\"185\">\u003Cspan data-fude-source-start=\"7366\" data-fude-source-end=\"7479\">Keep the title short. The description should communicate the useful conclusion rather than list every shape. The \u003C\u002Fspan>\u003Ca href=\"https:\u002F\u002Fmermaid.js.org\u002Fconfig\u002Faccessibility.html\" data-fude-link-kind=\"external\" rel=\"noopener noreferrer\">\u003Cspan data-fude-source-start=\"7480\" data-fude-source-end=\"7515\">Mermaid accessibility documentation\u003C\u002Fspan>\u003C\u002Fa>\u003Cspan data-fude-source-start=\"7566\" data-fude-source-end=\"7603\"> also covers multi-line descriptions.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch3 id=\"user-content-do-not-rely-on-interactions-or-a-specific-theme\" data-fude-source-line=\"187\">\u003Cspan data-fude-source-start=\"7609\" data-fude-source-end=\"7656\">Do not rely on interactions or a specific theme\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"189\">\u003Cspan data-fude-source-start=\"7658\" data-fude-source-end=\"7805\">Fude renders diagrams in strict security mode and adapts their colors to the reader theme. Treat the result as a static visual: do not depend on a \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"7805\" data-fude-source-end=\"7812\">click\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"7812\" data-fude-source-end=\"7937\"> action, HTML inside a label, or pixel-perfect positioning. The same rule improves compatibility with other Markdown viewers.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-why-a-mermaid-diagram-fails-to-render\" data-fude-source-line=\"191\">\u003Cspan data-fude-source-start=\"7942\" data-fude-source-end=\"7979\">Why a Mermaid diagram fails to render\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"193\">\u003Cspan data-fude-source-start=\"7981\" data-fude-source-end=\"8113\">When a diagram fails, keep the rest of the Markdown document intact and reduce the Mermaid block until the smallest version renders.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch3 id=\"user-content-the-code-block-is-not-marked-as-mermaid\" data-fude-source-line=\"195\">\u003Cspan data-fude-source-start=\"8119\" data-fude-source-end=\"8158\">The code block is not marked as Mermaid\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"197\">\u003Cspan data-fude-source-start=\"8160\" data-fude-source-end=\"8214\">This is ordinary Markdown code, not a Mermaid diagram:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cpre style=\"background-color:var(--fude-code-background, var(--color-code-bg));color:var(--fude-code-foreground, var(--color-code-text))\" tabindex=\"0\" class=\"shiki fude-code-theme fude-code-block\" data-language=\"markdown\" data-fude-code-block-start=\"8229\" data-fude-code-block-end=\"8259\" data-fude-source-line=\"199\">\u003Ccode class=\"language-markdown\" data-language=\"markdown\" data-fude-code-block-start=\"8229\" data-fude-code-block-end=\"8259\">\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--fude-code-token-string, color-mix(in srgb, var(--color-accent-primary) 78%, var(--color-code-text) 22%))\">```\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--fude-code-token-string, color-mix(in srgb, var(--color-accent-primary) 78%, var(--color-code-text) 22%))\">flowchart LR\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--fude-code-token-string, color-mix(in srgb, var(--color-accent-primary) 78%, var(--color-code-text) 22%))\">  A --> B\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--fude-code-token-string, color-mix(in srgb, var(--color-accent-primary) 78%, var(--color-code-text) 22%))\">```\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp data-fude-source-line=\"206\">\u003Cspan data-fude-source-start=\"8266\" data-fude-source-end=\"8270\">Add \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"8270\" data-fude-source-end=\"8279\">mermaid\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"8279\" data-fude-source-end=\"8320\"> immediately after the opening backticks.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch3 id=\"user-content-a-reserved-word-is-used-as-a-label\" data-fude-source-line=\"208\">\u003Cspan data-fude-source-start=\"8326\" data-fude-source-end=\"8360\">A reserved word is used as a label\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"210\">\u003Cspan data-fude-source-start=\"8362\" data-fude-source-end=\"8397\">In a flowchart, the lowercase word \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"8397\" data-fude-source-end=\"8402\">end\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"8402\" data-fude-source-end=\"8454\"> can be interpreted as the end of a subgraph. Write \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"8454\" data-fude-source-end=\"8459\">End\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"8459\" data-fude-source-end=\"8461\">, \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"8461\" data-fude-source-end=\"8466\">END\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"8466\" data-fude-source-end=\"8517\">, or use a separate identifier with a quoted label:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"flowchart LR\n  start["Start"] --> finish["End"]\" data-fude-mermaid-id=\"mermaid-9\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"212\">\u003C\u002Fdiv>\n\u003Ch3 id=\"user-content-the-diagram-type-is-misspelled\" data-fude-source-line=\"217\">\u003Cspan data-fude-source-start=\"8587\" data-fude-source-end=\"8617\">The diagram type is misspelled\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"219\">\u003Cspan data-fude-source-start=\"8619\" data-fude-source-end=\"8691\">The first Mermaid line must use a supported diagram declaration such as \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"8691\" data-fude-source-end=\"8702\">flowchart\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"8702\" data-fude-source-end=\"8704\">, \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"8704\" data-fude-source-end=\"8721\">sequenceDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"8721\" data-fude-source-end=\"8723\">, \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"8723\" data-fude-source-end=\"8737\">classDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"8737\" data-fude-source-end=\"8742\">, or \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"8742\" data-fude-source-end=\"8753\">erDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"8753\" data-fude-source-end=\"8803\">. Capitalization matters for declarations such as \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"8803\" data-fude-source-end=\"8820\">sequenceDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"8820\" data-fude-source-end=\"8821\">.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch3 id=\"user-content-a-node-label-breaks-the-grammar\" data-fude-source-line=\"221\">\u003Cspan data-fude-source-start=\"8827\" data-fude-source-end=\"8858\">A node label breaks the grammar\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"223\">\u003Cspan data-fude-source-start=\"8860\" data-fude-source-end=\"9024\">Punctuation that also has meaning in Mermaid can make an otherwise simple label ambiguous. Give the node an identifier and place its readable label inside brackets:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cdiv class=\"fude-mermaid-block\" data-fude-mermaid-source=\"flowchart LR\n  Start[Start: read the file] --> Finish[Finish: show the preview]\" data-fude-mermaid-id=\"mermaid-10\" data-fude-highlight-disabled=\"true\" data-fude-source-line=\"225\">\u003C\u002Fdiv>\n\u003Cp data-fude-source-line=\"230\">\u003Cspan data-fude-source-start=\"9122\" data-fude-source-end=\"9263\">If a complex label still fails, temporarily replace it with a single word. Add the original text back only after the diagram structure works.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch3 id=\"user-content-the-diagram-is-too-large-for-the-page\" data-fude-source-line=\"232\">\u003Cspan data-fude-source-start=\"9269\" data-fude-source-end=\"9306\">The diagram is too large for the page\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"234\">\u003Cspan data-fude-source-start=\"9308\" data-fude-source-end=\"9550\">A valid diagram may still be uncomfortable to read. Try a different direction, split one large diagram into two focused diagrams, or remove details that belong in the surrounding prose. A diagram should clarify the document, not reproduce it.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch3 id=\"user-content-two-viewers-render-slightly-differently\" data-fude-source-line=\"236\">\u003Cspan data-fude-source-start=\"9556\" data-fude-source-end=\"9595\">Two viewers render slightly differently\u003C\u002Fspan>\u003C\u002Fh3>\n\u003Cp data-fude-source-line=\"238\">\u003Cspan data-fude-source-start=\"9597\" data-fude-source-end=\"9827\">Mermaid evolves, and products do not always bundle the same version or theme. Test a diagram in the destination where people will read it. Keep the source portable, avoid depending on a very specific pixel layout, and consult the \u003C\u002Fspan>\u003Ca href=\"https:\u002F\u002Fmermaid.js.org\u002Fintro\u002F\" data-fude-link-kind=\"external\" rel=\"noopener noreferrer\">\u003Cspan data-fude-source-start=\"9828\" data-fude-source-end=\"9865\">official Mermaid syntax documentation\u003C\u002Fspan>\u003C\u002Fa>\u003Cspan data-fude-source-start=\"9897\" data-fude-source-end=\"9927\"> for the diagram type you use.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-compatibility-with-github-gitlab-and-markdown-viewers\" data-fude-source-line=\"240\">\u003Cspan data-fude-source-start=\"9932\" data-fude-source-end=\"9987\">Compatibility with GitHub, GitLab, and Markdown viewers\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"242\">\u003Ca href=\"https:\u002F\u002Fdocs.github.com\u002Fen\u002Fget-started\u002Fwriting-on-github\u002Fworking-with-advanced-formatting\u002Fcreating-diagrams\" data-fude-link-kind=\"external\" rel=\"noopener noreferrer\">\u003Cspan data-fude-source-start=\"9990\" data-fude-source-end=\"10013\">GitHub supports Mermaid\u003C\u002Fspan>\u003C\u002Fa>\u003Cspan data-fude-source-start=\"10123\" data-fude-source-end=\"10190\"> in Markdown files, issues, pull requests, discussions, and wikis. \u003C\u002Fspan>\u003Ca href=\"https:\u002F\u002Fdocs.gitlab.com\u002Fuser\u002Fmarkdown\u002F#mermaid\" data-fude-link-kind=\"external\" rel=\"noopener noreferrer\">\u003Cspan data-fude-source-start=\"10191\" data-fude-source-end=\"10226\">GitLab also supports Mermaid blocks\u003C\u002Fspan>\u003C\u002Fa>\u003Cspan data-fude-source-start=\"10275\" data-fude-source-end=\"10346\">, but each platform chooses its own Mermaid version and security rules.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cp data-fude-source-line=\"244\">\u003Cspan data-fude-source-start=\"10348\" data-fude-source-end=\"10531\">A diagram can therefore work in Fude and fail elsewhere if it uses recently added syntax, local configuration, or an interaction disabled by the destination. For the best portability:\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cul data-fude-source-line=\"246\">\n\u003Cli>\u003Cspan data-fude-source-start=\"10535\" data-fude-source-end=\"10563\">prefer stable types such as \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"10563\" data-fude-source-end=\"10574\">flowchart\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"10574\" data-fude-source-end=\"10576\">, \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"10576\" data-fude-source-end=\"10593\">sequenceDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"10593\" data-fude-source-end=\"10595\">, \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"10595\" data-fude-source-end=\"10609\">classDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"10609\" data-fude-source-end=\"10615\">, and \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"10615\" data-fude-source-end=\"10626\">erDiagram\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"10626\" data-fude-source-end=\"10627\">;\u003C\u002Fspan>\u003C\u002Fli>\n\u003Cli>\u003Cspan data-fude-source-start=\"10630\" data-fude-source-end=\"10681\">keep identifiers simple and quote displayed labels;\u003C\u002Fspan>\u003C\u002Fli>\n\u003Cli>\u003Cspan data-fude-source-start=\"10684\" data-fude-source-end=\"10782\">avoid interactive links, HTML, and theme settings that are essential to understanding the diagram;\u003C\u002Fspan>\u003C\u002Fli>\n\u003Cli>\u003Cspan data-fude-source-start=\"10785\" data-fude-source-end=\"10846\">test the document in its final destination before publishing.\u003C\u002Fspan>\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp data-fude-source-line=\"251\">\u003Cspan data-fude-source-start=\"10848\" data-fude-source-end=\"10992\">A Markdown viewer without Mermaid support will display the code block instead. The sentence before the diagram should still explain its purpose.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Ch2 id=\"user-content-mermaid-and-the-rest-of-your-markdown-document\" data-fude-source-line=\"253\">\u003Cspan data-fude-source-start=\"10997\" data-fude-source-end=\"11043\">Mermaid and the rest of your Markdown document\u003C\u002Fspan>\u003C\u002Fh2>\n\u003Cp data-fude-source-line=\"255\">\u003Cspan data-fude-source-start=\"11045\" data-fude-source-end=\"11188\">The biggest advantage of a Mermaid-aware Markdown viewer is context. A diagram can sit directly after the explanation it supports, alongside a \u003C\u002Fspan>\u003Ca href=\"\u002Fen\u002Fblog\u002Fmarkdown-table-complete-guide-with-examples\u002F\" data-fude-link-kind=\"unopenable\">\u003Cspan data-fude-source-start=\"11189\" data-fude-source-end=\"11203\">Markdown table\u003C\u002Fspan>\u003C\u002Fa>\u003Cspan data-fude-source-start=\"11259\" data-fude-source-end=\"11297\">, code samples, links, and task lists.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cp data-fude-source-line=\"257\">\u003Cspan data-fude-source-start=\"11299\" data-fude-source-end=\"11529\">Use prose to explain why a system behaves a certain way. Use the diagram to show relationships, direction, or sequence. Add a short sentence before every diagram so a reader who cannot render Mermaid still understands its purpose.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cp data-fude-source-line=\"259\">\u003Cspan data-fude-source-start=\"11531\" data-fude-source-end=\"11561\">If you received an unfamiliar \u003C\u002Fspan>\u003Ccode>\u003Cspan data-fude-source-start=\"11561\" data-fude-source-end=\"11566\">.md\u003C\u002Fspan>\u003C\u002Fcode>\u003Cspan data-fude-source-start=\"11566\" data-fude-source-end=\"11597\"> file, start with the guide to \u003C\u002Fspan>\u003Ca href=\"\u002Fen\u002Fblog\u002Fwhat-is-markdown-file-how-to-open\u002F\" data-fude-link-kind=\"unopenable\">\u003Cspan data-fude-source-start=\"11598\" data-fude-source-end=\"11632\">opening and reading Markdown files\u003C\u002Fspan>\u003C\u002Fa>\u003Cspan data-fude-source-start=\"11678\" data-fude-source-end=\"11713\">. Then paste the document into the \u003C\u002Fspan>\u003Ca href=\"\u002Fen\u002Fmarkdown-viewer\u002F\" data-fude-link-kind=\"unopenable\">\u003Cspan data-fude-source-start=\"11714\" data-fude-source-end=\"11736\">online Markdown viewer\u003C\u002Fspan>\u003C\u002Fa>\u003Cspan data-fude-source-start=\"11759\" data-fude-source-end=\"11831\"> and select the Mermaid sample whenever you need a clean starting point.\u003C\u002Fspan>\u003C\u002Fp>\n\u003Cp data-fude-source-line=\"261\">\u003Cspan data-fude-source-start=\"11833\" data-fude-source-end=\"11919\">For a local library of Markdown documents with themes, projects, and offline reading, \u003C\u002Fspan>\u003Ca href=\"\u002Fen\u002F#download\" data-fude-link-kind=\"unopenable\">\u003Cspan data-fude-source-start=\"11920\" data-fude-source-end=\"11943\">download Fude for macOS\u003C\u002Fspan>\u003C\u002Fa>\u003Cspan data-fude-source-start=\"11959\" data-fude-source-end=\"11960\">.\u003C\u002Fspan>\u003C\u002Fp>","\nAlready have a Mermaid diagram in a README or Markdown file and want to check the result before publishing? Fude's free Markdown viewer shows the source and rendered diagram side by side, directly in your browser.\n\nMermaid turns text syntax into a diagram embedded in Markdown. This guide shows you how to add a Mermaid code block, preview it with the Fude sample, test the main diagram types, and fix common rendering errors.\n\n## The shortest valid Mermaid block in Markdown\n\nMermaid source belongs in a code block marked as `mermaid`:\n\n````markdown\n```mermaid\nflowchart LR\n  Draft --> Review\n  Review --> Publish\n```\n````\n\nThe three backticks open and close the code block. The word `mermaid` tells a compatible viewer to interpret the content as a diagram instead of displaying it as ordinary code.\n\nThe first line inside the block identifies the diagram type. In this example:\n\n- `flowchart` selects a flowchart;\n- `LR` lays it out from left to right;\n- `Draft --> Review` creates two nodes and a directed connection.\n\nIf the language label is missing, a standard Markdown renderer will correctly show a code block, but it will not know that it should create a diagram.\n\n## Preview a Mermaid diagram with Fude\n\nThe [free Fude Markdown viewer](\u002Fen\u002Fmarkdown-viewer\u002F) uses the same rendering pipeline as the desktop reader and runs it locally in your browser.\n\n1. Open the viewer and choose **Mermaid sample**.\n2. Replace the sample nodes and arrows with your own Mermaid source.\n3. Watch the rendered diagram update in the preview pane.\n\nYou can also paste a complete README or `.md` document containing several diagrams. The viewer keeps headings, paragraphs, tables, highlighted code, and Mermaid blocks together, so you are checking the document that readers will actually see rather than an isolated diagram.\n\nNothing you type is uploaded by the viewer. Rendering happens in the current tab, which is useful for architecture notes, internal process maps, and diagrams that contain project names you do not want to send to a conversion service.\n\nIf the syntax is invalid, Fude keeps the source below the error message. You can fix the diagram without losing the rest of the document.\n\n## Which Mermaid diagram type should you choose?\n\nThe first line selects the diagram type. Choose it based on the information you need to communicate:\n\n| Need | First line | Common use |\n| --- | --- | --- |\n| Show a process or decision | `flowchart LR` | User journeys, pipelines, simple architecture |\n| Show messages over time | `sequenceDiagram` | API calls, authentication, events |\n| Show the states of an object | `stateDiagram-v2` | Lifecycles, state machines, workflows |\n| Show code structure | `classDiagram` | Classes, interfaces, and dependencies |\n| Show a data model | `erDiagram` | Entities, relationships, and cardinality |\n| Show a schedule | `gantt` | Phases, dependencies, and deadlines |\n| Show Git branches | `gitGraph` | Branching strategies and history |\n| Organize ideas | `mindmap` | Notes, concepts, and hierarchies |\n\nThe four types most often used in technical documentation are covered below. The others follow the same pattern: a declaration on the first line followed by the diagram source.\n\n## Flowchart example\n\nFlowcharts are useful for decision paths, build pipelines, onboarding sequences, and service interactions.\n\n```mermaid\nflowchart LR\n  Source[Markdown source] --> Parse[Parse document]\n  Parse --> HasDiagram{Mermaid block?}\n  HasDiagram -->|Yes| Render[Render diagram]\n  HasDiagram -->|No| Read[Display document]\n  Render --> Read\n```\n\nThe text inside square brackets becomes a readable node label. A shape wrapped in braces becomes a decision. Labels such as `|Yes|` describe individual connections.\n\nUse `TD` instead of `LR` when a top-to-bottom diagram fits the page better:\n\n```mermaid\nflowchart TD\n  Idea --> Draft\n  Draft --> Review\n  Review --> Release\n```\n\nWide diagrams can become difficult to read on phones, so changing direction is often more effective than adding more styling.\n\n## Sequence diagram example\n\nA sequence diagram focuses on messages exchanged over time. It works well for API calls, sign-in flows, background jobs, and interactions between an application and a database.\n\n```mermaid\nsequenceDiagram\n  participant Reader\n  participant Renderer\n  participant Mermaid\n  Reader->>Renderer: Paste Markdown\n  Renderer->>Mermaid: Send diagram source\n  Mermaid-->>Renderer: Return SVG\n  Renderer-->>Reader: Show preview\n```\n\nParticipants appear from left to right. Solid arrows usually represent a request, while dashed arrows are useful for a response. The source stays compact even when the rendered interaction contains several actors.\n\n## Class diagram example\n\nClass diagrams describe types and their relationships. They are useful in technical documentation when a short structural overview communicates more than a complete generated API reference.\n\n```mermaid\nclassDiagram\n  class MarkdownDocument {\n    +string title\n    +string body\n    +render()\n  }\n  class MermaidBlock {\n    +string source\n    +renderSvg()\n  }\n  MarkdownDocument \"1\" --> \"0..*\" MermaidBlock : contains\n```\n\nKeep these diagrams selective. Showing every property and method can turn a useful map into a second, harder-to-maintain version of the codebase.\n\n## Entity relationship diagram example\n\nEntity relationship diagrams document stored data and cardinality. They are especially helpful in architecture notes and migration plans.\n\n```mermaid\nerDiagram\n  PROJECT ||--o{ DOCUMENT : contains\n  DOCUMENT ||--o{ DIAGRAM : includes\n  PROJECT {\n    string id\n    string name\n  }\n  DOCUMENT {\n    string id\n    string path\n  }\n  DIAGRAM {\n    string id\n    string source\n  }\n```\n\nAn ER diagram is not a substitute for your real schema or migrations. It is a readable overview that helps people understand the important entities before they inspect implementation details.\n\n## Write Mermaid source that stays readable and portable\n\nA diagram can render correctly today and still become difficult to maintain after several edits. A few conventions prevent most problems.\n\n### Separate identifiers from labels\n\nUse short, stable identifiers in relationships, then put the displayed text inside brackets and quotes:\n\n```mermaid\nflowchart LR\n  draft[\"Draft ready\"] --> review[\"Technical review\"]\n  review --> publish[\"Publish\"]\n```\n\nYou can change “Technical review” later without renaming every relationship that uses `review`. Quotes also make spaces, punctuation, and Unicode text less ambiguous to the Mermaid parser.\n\n### Comment the source\n\nA line beginning with `%%` is a Mermaid comment and does not appear in the rendered diagram:\n\n```mermaid\nflowchart LR\n  %% Legal review is optional for an internal draft.\n  draft[\"Draft\"] --> review[\"Review\"] --> publish[\"Publish\"]\n```\n\nComments are useful for documenting layout constraints or the reason behind a relationship without adding more text to the visual output.\n\n### Add an accessible title and description\n\nMermaid supports `accTitle` and `accDescr`, which add a title and description to the generated SVG. They help screen-reader users and provide a textual equivalent of the diagram:\n\n```mermaid\nflowchart LR\n  accTitle: Document publishing workflow\n  accDescr: A draft goes through review before it is published.\n  draft[\"Draft\"] --> review[\"Review\"] --> publish[\"Publish\"]\n```\n\nKeep the title short. The description should communicate the useful conclusion rather than list every shape. The [Mermaid accessibility documentation](https:\u002F\u002Fmermaid.js.org\u002Fconfig\u002Faccessibility.html) also covers multi-line descriptions.\n\n### Do not rely on interactions or a specific theme\n\nFude renders diagrams in strict security mode and adapts their colors to the reader theme. Treat the result as a static visual: do not depend on a `click` action, HTML inside a label, or pixel-perfect positioning. The same rule improves compatibility with other Markdown viewers.\n\n## Why a Mermaid diagram fails to render\n\nWhen a diagram fails, keep the rest of the Markdown document intact and reduce the Mermaid block until the smallest version renders.\n\n### The code block is not marked as Mermaid\n\nThis is ordinary Markdown code, not a Mermaid diagram:\n\n````markdown\n```\nflowchart LR\n  A --> B\n```\n````\n\nAdd `mermaid` immediately after the opening backticks.\n\n### A reserved word is used as a label\n\nIn a flowchart, the lowercase word `end` can be interpreted as the end of a subgraph. Write `End`, `END`, or use a separate identifier with a quoted label:\n\n```mermaid\nflowchart LR\n  start[\"Start\"] --> finish[\"End\"]\n```\n\n### The diagram type is misspelled\n\nThe first Mermaid line must use a supported diagram declaration such as `flowchart`, `sequenceDiagram`, `classDiagram`, or `erDiagram`. Capitalization matters for declarations such as `sequenceDiagram`.\n\n### A node label breaks the grammar\n\nPunctuation that also has meaning in Mermaid can make an otherwise simple label ambiguous. Give the node an identifier and place its readable label inside brackets:\n\n```mermaid\nflowchart LR\n  Start[Start: read the file] --> Finish[Finish: show the preview]\n```\n\nIf a complex label still fails, temporarily replace it with a single word. Add the original text back only after the diagram structure works.\n\n### The diagram is too large for the page\n\nA valid diagram may still be uncomfortable to read. Try a different direction, split one large diagram into two focused diagrams, or remove details that belong in the surrounding prose. A diagram should clarify the document, not reproduce it.\n\n### Two viewers render slightly differently\n\nMermaid evolves, and products do not always bundle the same version or theme. Test a diagram in the destination where people will read it. Keep the source portable, avoid depending on a very specific pixel layout, and consult the [official Mermaid syntax documentation](https:\u002F\u002Fmermaid.js.org\u002Fintro\u002F) for the diagram type you use.\n\n## Compatibility with GitHub, GitLab, and Markdown viewers\n\n[GitHub supports Mermaid](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fget-started\u002Fwriting-on-github\u002Fworking-with-advanced-formatting\u002Fcreating-diagrams) in Markdown files, issues, pull requests, discussions, and wikis. [GitLab also supports Mermaid blocks](https:\u002F\u002Fdocs.gitlab.com\u002Fuser\u002Fmarkdown\u002F#mermaid), but each platform chooses its own Mermaid version and security rules.\n\nA diagram can therefore work in Fude and fail elsewhere if it uses recently added syntax, local configuration, or an interaction disabled by the destination. For the best portability:\n\n- prefer stable types such as `flowchart`, `sequenceDiagram`, `classDiagram`, and `erDiagram`;\n- keep identifiers simple and quote displayed labels;\n- avoid interactive links, HTML, and theme settings that are essential to understanding the diagram;\n- test the document in its final destination before publishing.\n\nA Markdown viewer without Mermaid support will display the code block instead. The sentence before the diagram should still explain its purpose.\n\n## Mermaid and the rest of your Markdown document\n\nThe biggest advantage of a Mermaid-aware Markdown viewer is context. A diagram can sit directly after the explanation it supports, alongside a [Markdown table](\u002Fen\u002Fblog\u002Fmarkdown-table-complete-guide-with-examples\u002F), code samples, links, and task lists.\n\nUse prose to explain why a system behaves a certain way. Use the diagram to show relationships, direction, or sequence. Add a short sentence before every diagram so a reader who cannot render Mermaid still understands its purpose.\n\nIf you received an unfamiliar `.md` file, start with the guide to [opening and reading Markdown files](\u002Fen\u002Fblog\u002Fwhat-is-markdown-file-how-to-open\u002F). Then paste the document into the [online Markdown viewer](\u002Fen\u002Fmarkdown-viewer\u002F) and select the Mermaid sample whenever you need a clean starting point.\n\nFor a local library of Markdown documents with themes, projects, and offline reading, [download Fude for macOS](\u002Fen\u002F#download).\n",[992,995],{"locale":993,"slug":994},"en","preview-mermaid-diagrams-in-markdown-online",{"locale":996,"slug":997},"fr","previsualiser-diagrammes-mermaid-markdown-en-ligne",{"title":999,"path":1000,"stem":1001,"description":1002,"children":-1},"Markdown Blockquotes: Syntax, Nesting, and Callouts","\u002Fen\u002Fblog\u002Fmarkdown-blockquotes-nesting-callouts","en\u002Fblog\u002F11.markdown-blockquotes-nesting-callouts","Learn how to create and nest Markdown blockquotes, cite a source, and use NOTE, TIP, IMPORTANT, WARNING, and CAUTION callouts.",1792599020615]