Markdown Integration

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

Markdown-integration

Indlej Datro diagrammer direkte i Markdown-filer ved hjælp af standard omhyllede kodeblokker. Værktøjslisten giver et remarks plugin (for MDX, Next.js, Astro og Vite) og et markdown-it plugin (for VitePress, Docusaurus og brugerdefinerede rørledninger).

bemærkning pluginmarkdown- det pluginCLI-rørledningenSVG · PNG udgang

Indlejring af et diagram

Markér enhver baggrænset kodeblokke med datro sprogidentifikatoren. Blocket skal starte med #!DATRO 1.0 magisk overskrift. Plugin analyserer, validerer og erstatter blokken med en inline SVG (eller <img>, der peger på en renderet PNG).

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.

ℹ️

Validering ved konstruktionstidspunktet

Begge plugins kører den fulde fire-pass validator under opbygningen. Hvis en blok har en fejl alvorlighed diagnosticering byggingen fejler straks med file:line:col placering.

Block id-attribut

Tilføj id="name" efter åbningssædet for at give et blok en stabil identifikator. CLI bruger dette ved navngivelse af outputfiler, og plugins udstiller det som et datatribut på det renderede element.

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

Udgangsfil bliver `architecture-auth-flow.svg` i stedet for `architecture-block-1.svg`

bemærkning plugin

Brug med enhver bemærkningbaseret rørledning: Next.js MDX, Astro, Gatsby, unificeret eller almindelig bemærkning.

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`	Udgangsformat.
`failOnError`	boolean	No	`true`	Når `false`, blokke med fejl bliver efterladt som hegnet kode i stedet for at fejle opbygningen.
`outDir`	string	No	—	Forretningsregister til PNG-filer (kun i PNG-modus). Standardregister til samme katalog som kildestand.

markdown- det plugin

Brug med enhver markdown-it-pipeline: VitePress, Docusaurus eller en hvilken som helst Node.js-server, der bruger markdown-it direkte.

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 brug med markdown-it

💡

VitePress / Vite

I VitePress tilføj plug-in til defineConfig({ markdown: { config: md => md.use(datroPlugin) } }). For Vite med vite-plugin-markdown se Vite konfigurationseksemplet nedenfor.

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-rørledningen (ingen bundler)

Hvis du ikke bruger en bundler, kan du bruge datro md CLI-kommandoen til at behandle Markdown-filer direkte. Dette kræver Graphviz for SVG/PNG-udgang, men md check kører uden det.

# 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

Udgangsfiler er opkaldt {markdown-basename}-{block-id}.{svg|png}.
Brug --no-fail til at behandle alle blokke, selv når nogle har fejl nyttige for migrationsrørledninger.
Brug --json med md check til struktureret udgang i CI-anotationssystemer.

Næste trin

Læs Talsreference for den fuldstændige .dtro syntax.
Læs CLI Reference for datro md render flag og CI integration.

Åben diagrammaker

Opbyg og forhåndsvisning diagrammer i browseren uden nogen lokal indstilling.