Add a Diagram to a Slide

A diagram in OPF is text. You write Mermaid source in a slide's diagram field, and the engines draw it in the deck's own fonts and colors. A flowchart on a slide with the classic theme looks like the rest of that deck; the same source on a dark variant redraws itself for the dark background. There is no picture to export, recolor or keep in sync.

Browse the Diagrams gallery for a sample of each family, from a flowchart to a Sankey or an Ishikawa diagram, each with its copyable OPF JSON and Markdown.

When a diagram is the right content kind

Choose the content kind by what the content is:

• Steps, decisions, systems and how they connect, messages between parties, states, hierarchies, entity models are diagrams.
• Numbers that should stay editable data belong in a chart. A Mermaid pie is a quick picture; a chart payload keeps the values as data with the chart design.
• Dated milestones with a status read best as a timeline payload, which has a status design.

In JSON

The shortest form is a string of Mermaid source. Its first word names the family (flowchart, sequenceDiagram, mindmap, timeline and so on):

{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Sales pipeline",
  "slides": [
    {
      "title": "Every qualified lead gets a discovery call",
      "diagram": "flowchart LR\n  A[New lead] --> B{Qualified?}\n  B -->|yes| C[Discovery call]\n  B -->|no| D[Nurture]\n  C --> E[Proposal]"
    }
  ]
}

The object form adds alt, the text alternative, and syntax, which is "mermaid" (the default and the only value today):

{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Order flow",
  "slides": [
    {
      "title": "Payment is authorized before the order is confirmed",
      "diagram": {
        "source": "sequenceDiagram\n  Customer->>Store: Place order\n  Store->>Payments: Authorize card\n  Payments-->>Store: Approved\n  Store-->>Customer: Order confirmed",
        "alt": "The store asks payments to authorize the card and confirms the order once it is approved."
      },
      "caption": "Figure 1. Checkout"
    }
  ]
}

A diagram can also be a block, so it can sit beside text. Give the slide blocks, and the diagram takes its own cell:

{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Review loop",
  "slides": [
    {
      "title": "A rejected brief returns to its author",
      "blocks": [
        { "bullets": ["Every brief is reviewed within two days", "Approved work goes straight to the build"] },
        { "diagram": "flowchart TB\n  A[Brief] --> B{Approved?}\n  B -->|yes| C[Build]\n  B -->|no| A" }
      ]
    }
  ]
}

In YAML

A block scalar keeps the source readable, with one line per Mermaid statement:

name: Strategy
slides:
  - title: Three themes carry the 2027 plan
    diagram:
      alt: The strategy has three themes, growth, efficiency and people, each with two initiatives.
      source: |-
        mindmap
          root((2027 Strategy))
            Growth
              New regions
              Partners
            Efficiency
              Automation
              Shared services
            People
              Hiring
              Training

In Markdown

In OPF Markdown, a fenced block whose info word is mermaid is a diagram, and an optional alt="..." after the word is its text alternative. Converting the deck to Markdown writes a diagram back the same way, so the round trip is lossless:

# Every request is reviewed before it ships

```mermaid alt="A request is approved or revised, then built."
flowchart LR
  A[Request] --> B{Approved?}
  B -->|yes| C[Build]
  B -->|no| D[Revise]
  D --> A
```

Each page in the Diagrams gallery shows its sample as this fence, ready to paste.

Write alt text that says what it shows

alt is what a screen reader reads and what the PowerPoint export writes as the picture's description. Say what the diagram shows, not that it is a diagram: "A brief goes to review; approved work is built, rejected work returns to the brief." Without alt, engines derive one from the diagram type and its labels, which names the parts but not the point.

Which layouts take a diagram

A slide with no layout composes a diagram on its own. To place one in a layout region, use a layout whose region accepts the diagram kind. In the default catalog these regions do:

Each layout lists the kinds its regions accept on its page. A slide that pins a diagram to a region that does not accept it gets a warning, and the diagram is bound by kind instead.

How the deck styles it

You do not pick colors or fonts for a diagram; the slide does:

• Node fills are tints of the first accent of the color scheme, in the slide variant's order, over the surface the diagram sits on.
• Data series, such as pie slices, timeline sections and mind map branches, use the same series palette as the slide's charts.
• Labels use the font scheme's body font and keep 4.5:1 contrast against their fill.
• Dark slides redraw the same source from the dark surface, so design.variant: "dark1" needs no change to the diagram.

Mermaid's own theming (%%{init}%%, themes) is ignored. Authored style and classDef colors are kept, but a shape with an authored color stops following the deck, so leave them out and let the theme decide.

Keep it readable

A diagram is laid out for the space it has, with labels no smaller than the deck's readability floor. When it does not fit, the slide reports it rather than shrinking the text. Fix it in the content:

• give the diagram a slide or a region of its own;
• turn its direction (flowchart TB instead of LR, or the reverse);
• split it into two diagrams, or shorten the labels.

In a PowerPoint export the diagram is a crisp picture with its alt as the description. To change it, edit the source and export again.