Markdown Integration

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

Integração de redução

Incorpore diagramas Datro diretamente em arquivos Markdown usando blocos de código protegidos padrão. A cadeia de ferramentas fornece um plugin de observação (para MDX, Next.js, Astro e Vite) e um plugin markdown-it (para VitePress, Docusaurus e pipelines personalizados).

plugin de observaçãoplugin markdown-itPipeline CLISVG · Saída PNG

Incorporando um diagrama

Marque qualquer bloco de código protegido com o identificador de idioma datro. O bloco deve começar com o cabeçalho mágico #!DATRO 1.0. O plugin analisa, valida e substitui o bloco por um SVG embutido (ou <img> apontando para um 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.

ℹ️

Validação em tempo de construção

Ambos os plug-ins executam o validador completo de quatro passagens durante a construção. Se algum bloco tiver um diagnóstico de gravidade de erro, a compilação falhará imediatamente com o local file:line:col.

Atributo de ID de bloco

Adicione id="name" após a cerca de abertura para dar ao bloco um identificador estável. A CLI usa isso ao nomear arquivos de saída, e os plug-ins expõem isso como um atributo de dados no 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 }
```

O arquivo de saída se torna `architecture-auth-flow.svg` em vez de `architecture-block-1.svg`

plugin de observação

Use com qualquer pipeline baseado em comentários: Next.js MDX, Astro, Gatsby, observação unificada ou simples.

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;

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 de saída renderizado.
`failOnError`	boolean	No	`true`	Quando `false`, os blocos com erros são deixados como código protegido em vez de falharem na construção.
`outDir`	string	No	—	Diretório para arquivos PNG (somente modo PNG). O padrão é o mesmo diretório do arquivo de origem.

plugin markdown-it

Use com qualquer pipeline de markdown-it: VitePress, Docusaurus ou qualquer servidor Node.js que use markdown-it diretamente.

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 direto com markdown-it

💡

VitePress / Vite

No VitePress, adicione o plugin a defineConfig({ markdown: { config: md => md.use(datroPlugin) } }). Para Vite com vite-plugin-markdown veja o exemplo de configuração do Vite abaixo.

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 (sem empacotador)

Se você não estiver usando um bundler, use os comandos CLI datro md para processar arquivos Markdown diretamente. Isso requer Graphviz para saída SVG/PNG, mas md check funciona sem ele.

# 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

Os arquivos de saída são nomeados {markdown-basename}-{block-id}.{svg|png}.
Use --no-fail para processar todos os blocos mesmo quando alguns apresentam erros — útil para pipelines de migração.
Use --json com md check para saída estruturada em sistemas de anotação de CI.

Próximas etapas

Leia o Language Reference para obter a sintaxe completa do .dtro.
Leia o CLI Reference para sinalizadores datro md render e integração de CI.

Abra o Criador de Diagramas

Crie e visualize diagramas no navegador sem qualquer configuração local.