Markdown Integration

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

Merkingdown-integrering

Legg Datro diagrammer direkte inn i markdown-filer ved å bruke standard skjulte kodeblokker. Toolchain tilbyr en mark-plugin (for MDX, Next.js, Astro og Vite) og en markdown-it-plugin (for VitePress, Docusaurus og brukerdefinierte pipelines)).

Kommentar-pluginMerkdown-it-pluginCLI-pypelineSVG · PNG utgave

Inneslutte et diagram

Merk alle låste kodeblokker med språkinformasjon datro. Blokken må bruke den magiske overskriften #!DATRO 1.0 Begynn. Plug-in analyserer, validerer og erstatter blokken med en inline SVG (eller <img>, som refererer til et gjentatte 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 til byggtid

Begge pluginene utfører den fullstendige firepass-validatoren under byggingen. Hvis en blokk er diagnostisert med et feilværdighetsgrad, slår bygningen file:line:col omgående fravær.

Block-ID-attributter

Legg til id="name" legge til etter åpningsfeltet for å gi en blokk en stabil identifikasjon. CLI bruker dette til å navngi utgangsfiler, og plugins gir det som et datatributt for det returnerte 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 }
```

Utgivelsesfilen blir `architecture-auth-flow.svg` i stedet for `architecture-block-1.svg`

Kommentar-plugin

Bruk med hver kommentarbasert pipeline: Next.js MDX, Astro, Gatsby, Unified eller Plain Remark.

npm install datro remark remark-html

Installere

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;

Neste.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`	Omformet utgangsformat.
`failOnError`	boolean	No	`true`	I `false` blir feilblokker igjen som skjult koden, i stedet for at bygningen feiler.
`outDir`	string	No	—	Fortegnelse for PNG-filer (png-modus bare)). Standard for samme katalog som kildefilen.

Merkdown-it-plugin

Bruk av enhver markdown-it-pipeline: VitePress, Docusaurus eller enhver Node.js-server som bruker 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 bruk med markdown-it

💡

VitePress / Vite

Legg plugin i VitePress defineConfig({ markdown: { config: md => md.use(datroPlugin) } }) i tillegg til. For Vite med vite-plugin-markdown Se Vite-konfigurasjonseksemplet 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-pyplinje (ikke bundler))

Hvis du ikke bruker en bundler, bruk CLI-kommandoene datro md, For å behandle markdown-filer direkte. Dette krever Graphviz for SVG/PNG-utgaven, men md check kjører uten 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 utgivende filer {markdown-basename}-{block-id}.{svg|png} kalt.
Bruk --no-fail, for å behandle alle blokker, selv om det er noen feil nyttig for migrationsrør.
Bruk --json med md check for en strukturert utgave i CI-annotasjonssystemer.

Neste skritt

Les Language Reference .dtro-Syntax.
Les CLI Reference flagg for datro md render og CI-integrasjon.

Åpne diagrammakeren

Opprett diagrammer i nettleseren og vis dem i forhåndsvisningen uten at det kreves lokalinnstilling.