Add diagrams

Redocly projects have built-in support for three diagram types: Mermaid, PlantUML, and 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.

Use Mermaid to add flowcharts, sequence diagrams, pie charts, and other visualizations using a text-based syntax.

Add a Mermaid diagram by using a fenced code block with the mermaid language identifier:

```mermaid
graph LR;
  Design --> Lint
  Design --> Preview
  Lint --> Publish
  Preview --> Publish
```

The diagram that is produced looks like the following:

Use PlantUML for UML diagrams such as sequence diagrams, class diagrams, and activity diagrams.

Add a PlantUML diagram by using a fenced code block with the plantuml language identifier:

```plantuml
@startuml
Client -> Server: Request
Server --> Client: Response
@enduml
```

The diagram that is produced looks like the following:

Use Excalidraw for hand-drawn style diagrams and sketches.

Add an Excalidraw diagram by using a fenced code block with the excalidraw language identifier:

```excalidraw
{
  "elements": [
    {
      "type": "rectangle",
      "x": 10,
      "y": 10,
      "width": 200,
      "height": 100,
      "strokeColor": "#000000",
      "backgroundColor": "#a5d8ff",
      "label": { "text": "Hello Excalidraw" }
    }
  ]
}
```

The diagram that is produced looks like the following:

Instead of writing diagram source inline, you can store it in a separate file and reference it with the diagram Markdoc tag. File references keep your Markdown pages clean and make diagrams easier to edit independently.

{% diagram file="./architecture.mermaid" type="mermaid" /%}

{% diagram file="./sequence.puml" type="plantuml" /%}

{% diagram file="./sketch.excalidraw" type="excalidraw" /%}

The file attribute accepts a relative path (resolved from the current page) or an absolute path (resolved from the content directory root). The type attribute must be one of mermaid, plantuml, or excalidraw.

You can control diagram layout in Markdown by adding Markdoc attributes to either the fenced code block or the diagram tag.

Use standard Markdoc string attribute syntax for these options:

```mermaid {% align="center" width="60%" %}
flowchart LR
  Draft --> Review
  Review --> Publish
```

{% diagram file="./architecture.mermaid" type="mermaid" align="center" width="100%" /%}

• align supports left, center, and right.
• width accepts any CSS width value, such as 480px, 40rem, 75%, or 100%.
• When you set width, the SVG scales proportionally and its height adjusts automatically.

Diagrams are also supported in AsciiDoc (.adoc) files with the AsciiDoc plugin. Use an open block with a style that matches the diagram type:

[mermaid]
--
graph LR;
  A --> B
--

[plantuml, format="png", id="myId"]
--
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml
--

[excalidraw]
--
{ "elements": [ ... ] }
--

Realm always renders diagrams as SVG. If you include a format attribute for compatibility with Asciidoctor diagram syntax, it is ignored.

See: Use AsciiDoc content for more information about the AsciiDoc plugin.

• Content types - Explore the different types of content you can use in your project
• Mermaid documentation - Complete guide to Mermaid diagram types and syntax
• PlantUML documentation - Reference for UML and other diagram types in PlantUML
• Excalidraw documentation - Guide to creating hand-drawn style diagrams with Excalidraw