Markdown Integration

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

Intégration de démarque

Intégrez des diagrammes Datro directement dans des fichiers Markdown à l'aide de blocs de code clôturés standard. La chaîne d'outils fournit un plugin de remarque (pour MDX, Next.js, Astro et Vite) et un plugin markdown-it (pour VitePress, Docusaurus et les pipelines personnalisés).

plugin de remarquesplugin markdown-itPipeline CLISortie SVG · PNG

Incorporer un diagramme

Marquez tout bloc de code clôturé avec l'identifiant de langue datro. Le bloc doit commencer par l'en-tête magique #!DATRO 1.0. Le plugin analyse, valide et remplace le bloc par un SVG en ligne (ou <img> pointant vers un PNG rendu).

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 au moment de la construction

Les deux plugins exécutent le validateur complet en quatre passes pendant la construction. Si un bloc présente un diagnostic de gravité d'erreur, la construction échoue immédiatement avec l'emplacement file:line:col.

Attribut d'identifiant de bloc

Ajoutez id="name" après la clôture d'ouverture pour donner à un bloc un identifiant stable. La CLI l'utilise pour nommer les fichiers de sortie, et les plugins l'exposent en tant qu'attribut de données sur l'élément rendu.

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

Le fichier de sortie devient `architecture-auth-flow.svg` au lieu de `architecture-block-1.svg`

plugin de remarques

À utiliser avec n'importe quel pipeline basé sur des remarques : Next.js MDX, Astro, Gatsby, remarque unifiée ou simple.

npm install datro remark remark-html

Installer

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`	Format de sortie rendu.
`failOnError`	boolean	No	`true`	Lorsque `false`, les blocs contenant des erreurs sont laissés sous forme de code clôturé au lieu d'échouer la construction.
`outDir`	string	No	—	Répertoire des fichiers PNG (mode PNG uniquement). La valeur par défaut est le même répertoire que le fichier source.

plugin markdown-it

À utiliser avec n'importe quel pipeline markdown-it : VitePress, Docusaurus ou tout serveur Node.js qui utilise directement markdown-it.

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

Utilisation directe avec markdown-it

💡

VitePress / Vite

Dans VitePress, ajoutez le plugin à defineConfig({ markdown: { config: md => md.use(datroPlugin) } }). Pour Vite avec vite-plugin-markdown, voir l'exemple de configuration Vite ci-dessous.

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" }]],
    }),
  ],
});

Pipeline CLI (pas de bundler)

Si vous n'utilisez pas de bundler, utilisez les commandes CLI datro md pour traiter directement les fichiers Markdown. Cela nécessite Graphviz pour la sortie SVG/PNG, mais md check s'exécute sans lui.

# 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

Les fichiers de sortie sont nommés {markdown-basename}-{block-id}.{svg|png}.
Utilisez --no-fail pour traiter tous les blocs même lorsque certains comportent des erreurs – utile pour les pipelines de migration.
Utilisez --json avec md check pour une sortie structurée dans les systèmes d'annotation CI.

Prochaines étapes

Lisez le Language Reference pour connaître la syntaxe complète de .dtro.
Lisez le CLI Reference pour les indicateurs datro md render et l'intégration CI.

Ouvrir le créateur de diagrammes

Créez et prévisualisez des diagrammes dans le navigateur sans aucune configuration locale.