Markdown Integration

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

Markdown-integratie

Datro-diagrammen direct in markdown-bestanden plaatsen met behulp van standaard gesloten codeblokken. De toolchain biedt een mark-plugin (voor MDX, Next.js, Astro en Vite) en een markdown-it-plugin (voor VitePress, Docusaurus en custom pipelines)).

Opmerking-pluginMarkdown-it-pluginCLI-pipelineSVG · PNG-uitgave

Het inzetten van een diagram

Merk elke ingekoppelde codeblock met de taalherkenning datro. Het blok moet met de magische header #!DATRO 1.0 Beginnen. De plugin analyseert, valideert en vervangt het blok door een inline-SVG (of <img>, die verwijst naar een gerendereerde 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.

ℹ️

Gevalideerd op de bouwtijd

Beide plugins voeren tijdens het bouwen de volledige vierpass-validator uit. Als er een foutgewicht is vastgesteld voor een blok, slaat de bouw met de positie: file:line:col onmiddellijk ontbreken.

Block-ID-attribut

Voeg toe id="name" na de openingszaal toevoegen om een blok een stabiele identificatie te geven. De CLI gebruikt dit bij het benoemen van uitgavebestanden en de plugins maken het beschikbaar als dataattribut voor het gerendereerde 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 }
```

Het output-bestand wordt `architecture-auth-flow.svg` In plaats van `architecture-block-1.svg`

Opmerking-plugin

Gebruik met elke opmerkingsgebaseerde pipeline: Next.js MDX, Astro, Gatsby, Unified of Plain Remark.

npm install datro remark remark-html

Installatie

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`	Gewijzigd uitgaveformaat.
`failOnError`	boolean	No	`true`	Bij `false` gebrekkige blokken blijven als beschermde code, in plaats van dat de bouw mislukt.
`outDir`	string	No	—	Directory voor PNG-bestanden (Png-mode alleen)). Standard dezelfde lijst als het bronbestand.

Markdown-it-plugin

Gebruik met elke markdown-it-pipeline: VitePress, Docusaurus of elke Node.js-server die Markdown-it rechtstreeks gebruikt.

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

Direct gebruik met markdown-it

💡

VitePress / Vite

Voeg de plugin toe in VitePress defineConfig({ markdown: { config: md => md.use(datroPlugin) } }) tot en met. Voor Vite met vite-plugin-markdown Zie het Vite-configuratie voorbeeld hieronder.

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-pipeline (geen bundel))

Als je geen bundler gebruikt, gebruik de CLI-opdrachten datro md, om markdown-bestanden direct te verwerken. Dit vereist Graphviz voor de SVG/PNG-uitgave, maar md check loopt zonder.

# 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

Wordt uitgebracht {markdown-basename}-{block-id}.{svg|png} genoemd.
Gebruik --no-fail, om alle blokken te verwerken, ook als er fouten zijn nuttig voor migratiepipelines.
Gebruik --json met md check voor een gestructureerde uitgave in CI-notatiesystemen.

Volgende stappen

Lees Language Reference voor de volledige tekst .dtro-Syntax.
Lees de CLI Reference vlag voor datro md render en de integratie van CI.

Maak de diagrammaker open

Maak grafieken in de browser en laat ze zien in het voorbeeld zonder dat een lokaal apparaat nodig is.