Markdown Integration

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

Markdown-integrering

Lägg in datoriteringar direkt i markdown-filer genom att använda standardskyddade kodblock. Toolchain erbjuder en mark-plugin (för MDX, Next.js, Astro och Vite) och en markdown-it-plugin (för VitePress, Docusaurus och kunddefinierade pipelines).

AnmärkningspluginMarkdown-it-pluginCLI-PipelineSVG · PNG-utgåva

Inläggning av en diagram

Markera varje instängd kodblock med språkkännandet datro. Blokken måste börja med den magiska header #!DATRO 1.0. Plug-in analyserar, validerar och ersätter blocket med en inline-SVG (eller <img>, som påpekar en renderad 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 vid byggtid

Båda plugins utföra den fullständiga fyrapass valideraren under byggandet. Om ett block har en felgrad diagnostiserad misslyckas omedelbart den här bilden med positionen file:line:col.

Block-ID-attribut

Lägg till id="name" efter öppningsfältet för att ge en block ett stabilt identifiering. CLI använder detta för att namnge utgångsfiler och plugins ger det som en datatribut för det omrenderade elementet.

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

Utgångsfilen kommer att gå till `architecture-auth-flow.svg` istället för `architecture-block-1.svg`

Anmärkningsplugin

Användning med varje kommentarbaserad pipeline: Next.js MDX, Astro, Gatsby, Unified eller Plain Remark.

npm install datro remark remark-html

Installation

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;

Nästa.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`	Omställd utgåva.
`failOnError`	boolean	No	`true`	Om `false` kvarstår felaktiga block som skyddad kod, istället för att byggan misslyckas.
`outDir`	string	No	—	Förteckning för PNG-filer ( PNG-modus). Samma register som källan standard.

Markdown-it-plugin

Användning med alla markdown-it-pipeliner: VitePress, Docusaurus eller alla Node.js-servrar som använder markdown-it direkt.

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

Direkt användning med markdown-it

💡

VitePress / Vite

Lägga till plugin i VitePress för att defineConfig({ markdown: { config: md => md.use(datroPlugin) } }) tillägg. För Vite med vite-plugin markdown se Vite-konfigurationsexemplet nedan.

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-pipelin (ingen bandel)

Om du inte använder en bindare, använd CLI-kommandoen datro md för att behandla markdownfiler direkt. Detta kräver graphviz för SVG/PNG-utgåvan, men md check går utan 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

Bli utgivna filer {markdown-basename}-{block-id}.{svg|png} kallad.
Använd --no-fail för att behandla alla block, även om det finns några fel användbart för migrationspipeliner.
Använd --json med md check för en strukturerad utgåva i CI-annotationssystem.

Nästa steg

Läs Language Reference för den fullständiga .dtro-syntaxen.
Läs CLI Reference flaggan för datro md render och CI-integrationen.

Öppna diagramtillverkaren

Skapa diagram i webbläsaren och visa dem i förhandsvisningen utan att det behövs någon lokal inställning.