mdd
DocsUse CasesGitHubOpen App

One diagram that renders everywhere your docs go

Technical writers and DevRel teams publish the same explanation to a docs site, a README, a PDF, and a support thread — and every medium breaks images and Mermaid differently. mdd output is plain aligned Unicode inside the Markdown, so the diagram survives every downstream format unchanged.

Open AppRead the Docs

A concept diagram in a Git tutorial

The classic Git data-flow explanation as it appears in a tutorial. Paste the Markdown anywhere — the diagram is the text.

<!-- mdd:begin id=git-flow src=docs/git-flow.diagram.json -->
```

  ┌──────────────┐
  │ Working Tree │
  └───────┬──────┘
       git add
          │
  ┌───────▼───────┐
  │ Staging Index │
  └───────┬───────┘
     git commit
          │
   ┌──────▼─────┐
   │ Local Repo │
   └──────┬─────┘
      git push
          │
 ┌────────▼────────┐
 │ origin (remote) │
 └─────────────────┘

```
[diagram source](docs/git-flow.diagram.json)
<!-- mdd:end -->

The model your agent edits

{
  "version": 1,
  "boxes": [
    {
      "id": "working",
      "label": "Working Tree",
      "row": 0,
      "connections": [
        {
          "to": "index",
          "arrow": "to",
          "label": "git add"
        }
      ]
    },
    {
      "id": "index",
      "label": "Staging Index",
      "row": 1,
      "connections": [
        {
          "to": "local",
          "arrow": "to",
          "label": "git commit"
        }
      ]
    },
    {
      "id": "local",
      "label": "Local Repo",
      "row": 2,
      "connections": [
        {
          "to": "remote",
          "arrow": "to",
          "label": "git push"
        }
      ]
    },
    {
      "id": "remote",
      "label": "origin (remote)",
      "row": 3
    }
  ]
}

Your agent draws it, you review it

  1. Model the concept as JSON — or draw it in the mdd editor and export.
  2. Splice it into the tutorial with mdd render.
  3. Publish the same Markdown to the docs site, README, PDF, or chat — the diagram needs no renderer.
  4. When the product changes, your agent updates the JSON and every copy of the ASCII regenerates from one source.

A prompt to hand your agent

This tutorial's diagrams are maintained with mdd. To change one, edit its .diagram.json source (e.g. docs/git-flow.diagram.json), then run: npx mdd render --json docs/git-flow.diagram.json --file docs/tutorial.md --id git-flow.

Why mdd here

Every other diagram format makes the tutorial hostage to a renderer: Mermaid needs a plugin, images need a build step and break in dark mode, and both are invisible in terminals and chat. mdd's diagram is the Markdown — it renders wherever text renders, and the JSON source keeps it editable without redrawing.

More use cases