Published on 2026-02-22

Excalidraw Diagrams in Markdown

How to embed beautiful, hand-drawn style Excalidraw diagrams directly in your documentation.

Excalidraw is a virtual whiteboard tool that lets you easily sketch diagrams that have a hand-drawn feel to them. It is very popular for quick sketching of ideas, architectures, and layouts.

MarkdownToPrettyPDF supports rendering Excalidraw diagrams through Kroki.

Embedding Excalidraw

Excalidraw does not natively use a text-based syntax like PlantUML or Mermaid. Instead, it saves data in a JSON format. To render an Excalidraw diagram, you can paste the JSON payload into an excalidraw code block.

syntax

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    {
      "type": "rectangle",
      "version": 11,
      "versionNonce": 1055530136,
      "isDeleted": false,
      "id": "cI2a685e13xG7-T0Z30p8",
      "fillStyle": "hachure",
      "strokeWidth": 1,
      "strokeStyle": "solid",
      "roughness": 1,
      "opacity": 100,
      "angle": 0,
      "x": 250,
      "y": 150,
      "strokeColor": "#000000",
      "backgroundColor": "transparent",
      "width": 120,
      "height": 80,
      "seed": 1699042968,
      "groupIds": [],
      "boundElements": null,
      "updated": 1629739763264,
      "link": null
    },
    {
      "id": "J1c3xKqwS",
      "type": "text",
      "x": 265,
      "y": 180,
      "width": 90,
      "height": 20,
      "angle": 0,
      "strokeColor": "#000000",
      "backgroundColor": "transparent",
      "fillStyle": "hachure",
      "strokeWidth": 1,
      "strokeStyle": "solid",
      "roughness": 1,
      "opacity": 100,
      "groupIds": [],
      "seed": 1646272596,
      "version": 7,
      "versionNonce": 612660184,
      "isDeleted": false,
      "boundElements": null,
      "updated": 1629739775314,
      "link": null,
      "text": "Hello World",
      "fontSize": 20,
      "fontFamily": 1,
      "textAlign": "left",
      "verticalAlign": "top",
      "baseline": 18
    }
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

Typically, you would copy the JSON source directly from an .excalidraw file or by using the “Copy to Clipboard as JSON” feature in Excalidraw.

Why use Excalidraw?

Excalidraw is great when you want to make diagrams that look less rigid and formal. The hand-drawn style is engaging and is often perfect for presenting ideas in a work-in-progress or brainstormed state.