Markdown Integration

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

Integrazione del ribasso

Incorpora i diagrammi Datro direttamente nei file Markdown utilizzando blocchi di codice recintati standard. La toolchain fornisce un plugin di commento (per MDX, Next.js, Astro e Vite) e un plugin markdown-it (per VitePress, Docusaurus e pipeline personalizzate).

plugin per le osservazioniplugin markdown-itpipeline della CLIUscita SVG · PNG

Incorporamento di un diagramma

Contrassegna qualsiasi blocco di codice protetto con l'identificatore della lingua datro. Il blocco deve iniziare con l'intestazione magica #!DATRO 1.0. Il plugin analizza, convalida e sostituisce il blocco con un SVG in linea (o <img> che punta a un PNG renderizzato).

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.

ℹ️

Convalida in fase di compilazione

Entrambi i plugin eseguono il validatore completo a quattro passaggi durante la compilazione. Se un blocco presenta una diagnostica sulla gravità dell'errore, la compilazione fallisce immediatamente con la posizione file:line:col.

Attributo ID blocco

Aggiungi id="name" dopo la recinzione di apertura per dare a un blocco un identificatore stabile. La CLI lo utilizza quando denomina i file di output e i plugin lo espongono come attributo dati sull'elemento renderizzato.

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

Il file di output diventa `architecture-auth-flow.svg` invece di `architecture-block-1.svg`

plugin per le osservazioni

Utilizzare con qualsiasi pipeline basata su commenti: Next.js MDX, Astro, Gatsby, commento unificato o semplice.

npm install datro remark remark-html

Installa

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`	Formato di output renderizzato.
`failOnError`	boolean	No	`true`	Quando `false`, i blocchi con errori vengono lasciati come codice protetto invece di fallire la compilazione.
`outDir`	string	No	—	Directory per file PNG (solo modalità PNG). Il valore predefinito è la stessa directory del file di origine.

plugin markdown-it

Utilizzalo con qualsiasi pipeline markdown-it: VitePress, Docusaurus o qualsiasi server Node.js che utilizza direttamente 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);

Utilizzo diretto con markdown-it

💡

VitePress / Vite

In VitePress, aggiungi il plugin a defineConfig({ markdown: { config: md => md.use(datroPlugin) } }). Per Vite con vite-plugin-markdown vedere l'esempio di configurazione di Vite di seguito.

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 (nessun bundler)

Se non utilizzi un bundler, utilizza i comandi CLI datro md per elaborare direttamente i file Markdown. Ciò richiede Graphviz per l'output SVG/PNG, ma md check funziona senza di esso.

# 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

I file di output sono denominati {markdown-basename}-{block-id}.{svg|png}.
Utilizza --no-fail per elaborare tutti i blocchi anche quando alcuni presentano errori: utile per le pipeline di migrazione.
Utilizzare --json con md check per l'output strutturato nei sistemi di annotazione CI.

Prossimi passi

Leggere il Language Reference per la sintassi completa del .dtro.
Leggere il CLI Reference per i flag datro md render e l'integrazione CI.

Apri Creatore di diagrammi

Crea e visualizza in anteprima i diagrammi nel browser senza alcuna configurazione locale.