Markdown Integration

Embed diagrams in .md files with remark or markdown-it

Markdown Integration

Embed Datro diagrams directly in Markdown files using standard fenced code blocks. The toolchain provides a remark plugin (for MDX, Next.js, Astro, and Vite) and a markdown-it plugin (for VitePress, Docusaurus, and custom pipelines).

remark pluginmarkdown-it pluginCLI pipelineSVG · PNG output

Embedding a diagram

Mark any fenced code block with the datro language identifier. The block must start with the #!DATRO 1.0 magic header. The plugin parses, validates, and replaces the block with an inline SVG (or <img> pointing to a rendered PNG).

docs/architecture.md

# System Architecture

The diagram below is generated automatically from source:

```datro
#!DATRO 1.0

meta { title: "Auth Service" }

node client  { type: web      label: "Browser" }
node api_gw  { type: gateway  label: "API Gateway" }
node auth    { type: service  label: "Auth Service" }
node user_db { type: database label: "User DB" }

edge client -> api_gw  { kind: http  label: "POST /login" }
edge api_gw -> auth    { kind: http }
edge auth   -> user_db { kind: query }

layout { direction: LR  algo: dagre }

theme {
  palette { gateway: "#FFD0D0"  service: "#D0E8FF"  database: "#FFE8C0" }
  accessibility { min_contrast: AA }
}
```

> Rendered inline by the datro remark plugin.

ℹ️

Validation at build time

Both plugins run the full four-pass validator during the build. If any block has an error-severity diagnostic the build fails immediately with the file:line:col location.

Block id attribute

Add id="name" after the opening fence to give a block a stable identifier. The CLI uses this when naming output files, and the plugins expose it as a data attribute on the rendered element.

Markdown

```datro id="auth-flow"
#!DATRO 1.0
node a { type: service label: "A" }
node b { type: service label: "B" }
edge a -> b { kind: http }
```

Output file becomes `architecture-auth-flow.svg` instead of `architecture-block-1.svg`

remark plugin

Use with any remark-based pipeline: Next.js MDX, Astro, Gatsby, unified, or plain remark.

npm install datro remark remark-html

Install

remark.config.mjs

// remark.config.mjs
import remarkDatro from "datro/remark";

const config = {
  plugins: [
    // Transforms ```datro blocks to inline SVG
    [remarkDatro, { format: "svg" }],
  ],
};

export default config;

Next.js MDX

next.config.mjs

// next.config.mjs
import remarkDatro from "datro/remark";
import createMDX from "@next/mdx";

const withMDX = createMDX({
  options: {
    remarkPlugins: [[remarkDatro, { format: "svg" }]],
  },
});

export default withMDX({
  pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
});

Field	Type	Required	Default	Description
`format`	string "svg""png"	No	`svg`	Rendered output format.
`failOnError`	boolean	No	`true`	When `false`, blocks with errors are left as fenced code instead of failing the build.
`outDir`	string	No	—	Directory for PNG files (PNG mode only). Defaults to the same directory as the source file.

markdown-it plugin

Use with any markdown-it pipeline: VitePress, Docusaurus, or any Node.js server that uses markdown-it directly.

JavaScript

import MarkdownIt from "markdown-it";
import datroPLugin from "datro/markdown-it";

const md = new MarkdownIt();
md.use(datroPLugin, { format: "svg" });

const html = md.render(source);

Direct usage with markdown-it

💡

VitePress / Vite

In VitePress, add the plugin to defineConfig({ markdown: { config: md => md.use(datroPlugin) } }). For Vite with vite-plugin-markdown see the Vite config example below.

vite.config.ts

// vite.config.ts
import { defineConfig } from "vite";
import mdPlugin from "vite-plugin-markdown";
import remarkDatro from "datro/remark";

export default defineConfig({
  plugins: [
    mdPlugin({
      remarkPlugins: [[remarkDatro, { format: "svg" }]],
    }),
  ],
});

CLI pipeline (no bundler)

If you are not using a bundler, use the datro md CLI commands to process Markdown files directly. This requires Graphviz for SVG/PNG output, but md check runs without it.

# Render all datro blocks in a markdown file to SVG
datro md render docs/architecture.md --out-dir public/diagrams

# Validate all blocks without rendering (fast, no Graphviz needed)
datro md check docs/architecture.md

Output files are named {markdown-basename}-{block-id}.{svg|png}.
Use --no-fail to process all blocks even when some have errors — useful for migration pipelines.
Use --json with md check for structured output in CI annotation systems.

Next steps

Read the Language Reference for the complete .dtro syntax.
Read the CLI Reference for datro md render flags and CI integration.

Open Diagram Maker

Build and preview diagrams in the browser without any local setup.