Markdown Integration

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

Markdown-Integration

Betten Sie Datro-Diagramme direkt in Markdown-Dateien ein, indem Sie standardmäßige abgeschirmte Codeblöcke verwenden. Die Toolchain bietet ein Remark-Plugin (für MDX, Next.js, Astro und Vite) und ein Markdown-it-Plugin (für VitePress, Docusaurus und benutzerdefinierte Pipelines).

Bemerkungs-PluginMarkdown-it-PluginCLI-PipelineSVG · PNG-Ausgabe

Einbetten eines Diagramms

Markieren Sie jeden eingezäunten Codeblock mit der Sprachkennung datro. Der Block muss mit dem magischen Header #!DATRO 1.0 beginnen. Das Plugin analysiert, validiert und ersetzt den Block durch ein Inline-SVG (oder <img>, das auf ein gerendertes PNG verweist).

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.

ℹ️

Validierung zur Build-Zeit

Beide Plugins führen während des Builds den vollständigen Vier-Pass-Validator aus. Wenn für einen Block eine Fehlerschwerediagnose vorliegt, schlägt der Build mit der Position file:line:col sofort fehl.

Block-ID-Attribut

Fügen Sie id="name" nach dem Öffnungszaun hinzu, um einem Block eine stabile Kennung zu geben. Die CLI verwendet dies beim Benennen von Ausgabedateien und die Plugins stellen es als Datenattribut für das gerenderte Element bereit.

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 }
```

Die Ausgabedatei wird zu `architecture-auth-flow.svg` anstelle von `architecture-block-1.svg`

Bemerkungs-Plugin

Verwendung mit jeder auf Bemerkungen basierenden Pipeline: Next.js MDX, Astro, Gatsby, Unified oder Plain Remark.

npm install datro remark remark-html

Installieren

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`	Gerendertes Ausgabeformat.
`failOnError`	boolean	No	`true`	Bei `false` bleiben fehlerhafte Blöcke als abgeschirmter Code übrig, anstatt dass der Build fehlschlägt.
`outDir`	string	No	—	Verzeichnis für PNG-Dateien (nur PNG-Modus). Standardmäßig dasselbe Verzeichnis wie die Quelldatei.

Markdown-it-Plugin

Verwendung mit jeder Markdown-it-Pipeline: VitePress, Docusaurus oder jedem Node.js-Server, der Markdown-it direkt verwendet.

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);

Direkte Nutzung mit markdown-it

💡

VitePress / Vite

Fügen Sie in VitePress das Plugin zu defineConfig({ markdown: { config: md => md.use(datroPlugin) } }) hinzu. Für Vite mit vite-plugin-markdown siehe das Vite-Konfigurationsbeispiel unten.

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 (kein Bundler)

Wenn Sie keinen Bundler verwenden, verwenden Sie die CLI-Befehle datro md, um Markdown-Dateien direkt zu verarbeiten. Dies erfordert Graphviz für die SVG/PNG-Ausgabe, aber md check läuft ohne es.

# 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

Ausgabedateien werden {markdown-basename}-{block-id}.{svg|png} genannt.
Verwenden Sie --no-fail, um alle Blöcke zu verarbeiten, auch wenn einige Fehler aufweisen – nützlich für Migrationspipelines.
Verwenden Sie --json mit md check für eine strukturierte Ausgabe in CI-Annotationssystemen.

Nächste Schritte

Lesen Sie Language Reference für die vollständige .dtro-Syntax.
Lesen Sie die CLI Reference-Flags für datro md render und die CI-Integration.

Öffnen Sie den Diagrammersteller

Erstellen Sie Diagramme im Browser und zeigen Sie sie in der Vorschau an, ohne dass eine lokale Einrichtung erforderlich ist.