{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"add-diagrams","__idx":0},"children":["Add diagrams"]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly projects have built-in support for three diagram types: ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://mermaid.js.org/"},"children":["Mermaid"]},", ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://plantuml.com/"},"children":["PlantUML"]},", and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://excalidraw.com/"},"children":["Excalidraw"]},"."," ","Use diagrams to help your users quickly grasp the structure or concept that your content conveys."," ","It's good practice to use diagrams alongside explanatory text to make sure that all users can access the information."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"mermaid","__idx":1},"children":["Mermaid"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Mermaid to add flowcharts, sequence diagrams, pie charts, and other visualizations using a text-based syntax."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a Mermaid diagram by using a fenced code block with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mermaid"]}," language identifier:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"```mermaid\ngraph LR;\n Design --> Lint\n Design --> Preview\n Lint --> Publish\n Preview --> Publish\n```\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The diagram that is produced looks like the following:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR;\n Design --> Lint\n Design --> Preview\n Lint --> Publish\n Preview --> Publish\n","diagramHtml":"

Design

Lint

Preview

Publish

","diagramHtmlDark":"

Design

Lint

Preview

Publish

"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"plantuml","__idx":2},"children":["PlantUML"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use PlantUML for UML diagrams such as sequence diagrams, class diagrams, and activity diagrams."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a PlantUML diagram by using a fenced code block with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plantuml"]}," language identifier:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"```plantuml\n@startuml\nClient -> Server: Request\nServer --> Client: Response\n@enduml\n```\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The diagram that is produced looks like the following:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"plantuml","diagramType":"plantuml","diagramSource":"@startuml\nClient -> Server: Request\nServer --> Client: Response\n@enduml\n","diagramHtml":"ClientServerClientClientServerServerRequestResponse","diagramHtmlDark":"ClientServerClientClientServerServerRequestResponse"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"excalidraw","__idx":3},"children":["Excalidraw"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Excalidraw for hand-drawn style diagrams and sketches."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add an Excalidraw diagram by using a fenced code block with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["excalidraw"]}," language identifier:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"```excalidraw\n{\n \"elements\": [\n {\n \"id\": \"rect-container-1\",\n \"type\": \"rectangle\",\n \"x\": 10,\n \"y\": 10,\n \"width\": 200,\n \"height\": 100,\n \"strokeColor\": \"#000000\",\n \"backgroundColor\": \"#a5d8ff\",\n \"boundElements\": [\n {\n \"type\": \"text\",\n \"id\": \"Wb2WmAHFObZ7zjOcBk5Dz\"\n }\n ]\n },\n {\n \"id\": \"Wb2WmAHFObZ7zjOcBk5Dz\",\n \"type\": \"text\",\n \"containerId\": \"rect-container-1\",\n \"strokeColor\": \"#1971c2\",\n \"text\": \"Hello Excalidraw!\",\n \"fontSize\": 20,\n \"fontFamily\": 5,\n \"textAlign\": \"center\",\n \"verticalAlign\": \"middle\",\n \"lineHeight\": 1.25,\n \"strokeWidth\": 2,\n \"x\": 20,\n \"y\": 47.5,\n \"width\": 180,\n \"height\": 25,\n \"autoResize\": false\n }\n ]\n}\n```\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The diagram that is produced looks like the following:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"excalidraw","diagramType":"excalidraw","diagramSource":"{\n \"elements\": [\n {\n \"id\": \"rect-container-1\",\n \"type\": \"rectangle\",\n \"x\": 10,\n \"y\": 10,\n \"width\": 200,\n \"height\": 100,\n \"strokeColor\": \"#000000\",\n \"backgroundColor\": \"#a5d8ff\",\n \"boundElements\": [\n {\n \"type\": \"text\",\n \"id\": \"Wb2WmAHFObZ7zjOcBk5Dz\"\n }\n ]\n },\n {\n \"id\": \"Wb2WmAHFObZ7zjOcBk5Dz\",\n \"type\": \"text\",\n \"containerId\": \"rect-container-1\",\n \"strokeColor\": \"#1971c2\",\n \"text\": \"Hello Excalidraw!\",\n \"fontSize\": 20,\n \"fontFamily\": 5,\n \"textAlign\": \"center\",\n \"verticalAlign\": \"middle\",\n \"lineHeight\": 1.25,\n \"strokeWidth\": 2,\n \"x\": 20,\n \"y\": 47.5,\n \"width\": 180,\n \"height\": 25,\n \"autoResize\": false\n }\n ]\n}\n","diagramHtml":"Hello Excalidraw!","diagramHtmlDark":"Hello Excalidraw!"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-diagrams-from-files","__idx":4},"children":["Use diagrams from files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead of writing diagram source inline, you can store it in a separate file and reference it with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["diagram"]}," Markdoc tag."," ","File references keep your Markdown pages clean and make diagrams easier to edit independently."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% diagram file=\"./architecture.mermaid\" type=\"mermaid\" /%}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% diagram file=\"./sequence.puml\" type=\"plantuml\" /%}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% diagram file=\"./sketch.excalidraw\" type=\"excalidraw\" /%}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]}," attribute accepts a relative path (resolved from the current page) or an absolute path (resolved from the content directory root)."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," attribute must be one of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mermaid"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plantuml"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["excalidraw"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"control-alignment-and-width","__idx":5},"children":["Control alignment and width"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can control diagram layout in Markdown by adding Markdoc attributes to either the fenced code block or the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["diagram"]}," tag."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use standard Markdoc string attribute syntax for these options:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"```mermaid {% align=\"center\" width=\"60%\" %}\nflowchart LR\n Draft --> Review\n Review --> Publish\n```\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","align":"center","width":"60%","diagramType":"mermaid","diagramSource":"flowchart LR\n Draft --> Review\n Review --> Publish\n","diagramHtml":"

Draft

Review

Publish

","diagramHtmlDark":"

Draft

Review

Publish

"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% diagram file=\"./architecture.mermaid\" type=\"mermaid\" align=\"center\" width=\"100%\" /%}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["align"]}," supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["left"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["center"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["right"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["width"]}," accepts any CSS width value, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["480px"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["40rem"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["75%"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["100%"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When you set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["width"]},", the SVG scales proportionally and its height adjusts automatically."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To place multiple diagrams horizontally (side-by-side) you can use ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/branding/customize-styles#use-css-utility-classes-for-layout"},"children":["CSS utility classes"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"asciidoc","__idx":6},"children":["AsciiDoc"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Diagrams are also supported in AsciiDoc (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".adoc"]},") files with the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/asciidoc"},"children":["AsciiDoc plugin"]},"."," ","Use an open block with a style that matches the diagram type:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"adoc","header":{"controls":{"copy":{}}},"source":"[mermaid]\n--\ngraph LR;\n A --> B\n--\n","lang":"adoc"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"adoc","header":{"controls":{"copy":{}}},"source":"[plantuml, format=\"png\", id=\"myId\"]\n--\n@startuml\nAlice -> Bob: Hello\nBob --> Alice: Hi\n@enduml\n--\n","lang":"adoc"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"adoc","header":{"controls":{"copy":{}}},"source":"[excalidraw]\n--\n{ \"elements\": [ ... ] }\n--\n","lang":"adoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Realm always renders diagrams as SVG."," ","If you include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["format"]}," attribute for compatibility with Asciidoctor diagram syntax, it is ignored."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See: ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/asciidoc"},"children":["Add AsciiDoc content"]}," for more information about the AsciiDoc plugin."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":7},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content"},"children":["Create content"]}]}," - Explore the different types of content you can use in your project"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://mermaid.js.org/intro/#diagram-types"},"children":["Mermaid documentation"]}]}," - Complete guide to Mermaid diagram types and syntax"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://plantuml.com/"},"children":["PlantUML documentation"]}]}," - Reference for UML and other diagram types in PlantUML"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://docs.excalidraw.com/"},"children":["Excalidraw documentation"]}]}," - Guide to creating hand-drawn style diagrams with Excalidraw"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/branding/customize-styles"},"children":["Customize styles"]}]}," - Learn how to add custom CSS to your project"]}]}]},"frontmatter":{"products":["Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"],"keywords":{"includes":["mermaid","plantuml","excalidraw"]}},"tagList":["configOptionRequirements"],"title":"Add diagrams","lastModified":"2026-10-01T23:00:57.000Z"}