Markdown Integration

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

Integración de rebajas

Incruste diagramas de Datro directamente en archivos Markdown utilizando bloques de código delimitados estándar. La cadena de herramientas proporciona un complemento de comentarios (para MDX, Next.js, Astro y Vite) y un complemento de rebajas (para VitePress, Docusaurus y canalizaciones personalizadas).

complemento de comentarioscomplemento markdown-itCanalización CLISVG · Salida PNG

Incrustar un diagrama

Marque cualquier bloque de código delimitado con el identificador de idioma datro. El bloque debe comenzar con el encabezado mágico #!DATRO 1.0. El complemento analiza, valida y reemplaza el bloque con un SVG en línea (o <img> que apunta a un PNG renderizado).

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.

ℹ️

Validación en el momento de la construcción

Ambos complementos ejecutan el validador completo de cuatro pasos durante la compilación. Si algún bloque tiene un diagnóstico de gravedad de error, la compilación falla inmediatamente con la ubicación file:line:col.

Atributo de identificación de bloque

Agregue id="name" después de la valla de apertura para darle a un bloque un identificador estable. La CLI usa esto al nombrar archivos de salida y los complementos lo exponen como un atributo de datos en el elemento renderizado.

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

El archivo de salida se convierte en `architecture-auth-flow.svg` en lugar de `architecture-block-1.svg`

complemento de comentarios

Úselo con cualquier canal basado en comentarios: Next.js MDX, Astro, Gatsby, unificado o comentario simple.

npm install datro remark remark-html

Instalar

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;

Siguiente.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 de salida renderizado.
`failOnError`	boolean	No	`true`	Cuando `false`, los bloques con errores se dejan como código protegido en lugar de fallar la compilación.
`outDir`	string	No	—	Directorio para archivos PNG (solo modo PNG). El valor predeterminado es el mismo directorio que el archivo fuente.

complemento markdown-it

Úselo con cualquier canal de Markdown-it: VitePress, Docusaurus o cualquier servidor Node.js que use Markdown-it directamente.

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

Uso directo con Markdown-it

💡

VitePress / Vite

En VitePress, agregue el complemento a defineConfig({ markdown: { config: md => md.use(datroPlugin) } }). Para Vite con vite-plugin-markdown vea el ejemplo de configuración de Vite a continuación.

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

Canalización CLI (sin paquete)

Si no está utilizando un paquete, utilice los comandos CLI datro md para procesar archivos Markdown directamente. Esto requiere Graphviz para la salida SVG/PNG, pero md check se ejecuta sin él.

# 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

Los archivos de salida se denominan {markdown-basename}-{block-id}.{svg|png}.
Utilice --no-fail para procesar todos los bloques incluso cuando algunos tengan errores, lo que resulta útil para los procesos de migración.
Utilice --json con md check para obtener resultados estructurados en sistemas de anotación de CI.

Próximos pasos

Lea el Language Reference para conocer la sintaxis completa de .dtro.
Lea CLI Reference para conocer los indicadores datro md render y la integración de CI.

Creador de diagramas abiertos

Cree y obtenga una vista previa de diagramas en el navegador sin ninguna configuración local.