Markdown Integration

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

Markdown-integraatio

Laita Datro-diagrammit suoraan Markdown-tiedostoihin käyttämällä standardoituja suojattuja koodiblokkeja. Toolchain tarjoaa Mark-it-plugin (MDX, Next.js, Astro ja Vite) ja Markdown-it-plugin (VitePress, Docusaurus ja käyttäjäjärjestelmät).

Huomautus-ohjelmaMarkdown-it-pluginCLI-pyelineSVG · PNG-muoto

Kuvan sisällyttäminen

Valitse kaikki seinävartioidut koodiblokit äänen tunnistuksella datro. Pöytä pitää käyttää taikaa. #!DATRO 1.0 aloitetaan. Lisäkkeellä analysoidaan, validoidaan ja korvataan lohko inline-SVG:llä (tai <img>, joka viittaa käännetylle PNG:lle).

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.

ℹ️

Validointi rakennusaikana

Molemmat pluginit käyttävät täydellistä neljäkorttivalvontaajia rakennettaessa. Jos blokkia on diagnosoitu virheellisesti, rakenne lyö file:line:col Vihdoin puuttu.

Blokki-ID-attribuutti

Lisää id="name" lisätä avauskerroksen jälkeen, jotta blokki saa vakaan tunnuksen. CLI käyttää tätä nimittäessään tulostustietoja, ja laajennukset tarjoavat sen muuntuneen elementin tietosuojaksi.

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

Päästötiedot muuttuvat `architecture-auth-flow.svg` sen sijaan `architecture-block-1.svg`

Huomautus-ohjelma

Käytettävissä kaikissa huomautuksiin perustuvissa pipelineissä: Next.js MDX, Astro, Gatsby, Unified tai Plain Remark.

npm install datro remark remark-html

Asennetaan

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;

Seuraava.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`	Muuntunut tulosmuoto.
`failOnError`	boolean	No	`true`	Ehdotukset `false` Virheelliset blokit jäävät suojattuun koodiin sen sijaan, että rakenne epäonnistuisi.
`outDir`	string	No	—	PNG-tiedostojen luettelo (vain PNG-tila). Standardin mukaan sama luettelo kuin lähde-tiedosto.

Markdown-it-plugin

Käyttö minkä tahansa Markdown-it-pyppelin kanssa: VitePress, Docusaurus tai minkä tahansa Node.js-serverin kanssa, joka käyttää suoraan Markdown-it.

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

Suora käyttö markdown-it

💡

VitePress / Vite

Lisää VitePress-ohjelma defineConfig({ markdown: { config: md => md.use(datroPlugin) } }) lisätä. Vite kanssa vite-plugin-markdown Katso Vite-konfiguraation esimerkki alla.

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-piipeline (ei liittoja)

Jos et käytä pakettia, käytä CLI-ohjeita datro md, jotta Markdown-tiedostoja voidaan käsitellä suoraan. Tämä vaatii Graphvizia SVG/PNG-muodostukseen, mutta md check Käy ilman sitä.

# 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

Valmistautumisfaileja {markdown-basename}-{block-id}.{svg|png} nimeltään.
Käytä --no-fail, hyödyllinen siirtymäputkien käsittelyyn.
Käytä --json Ehdotukset md check rakenteellisesta liikkeeseenlaskesta CI-merkintäjärjestelmissä.

Seuraava askel

Lue Language Reference täydelliseksi .dtro-Syntaxis.
Lue CLI Reference lippuja datro md render ja CI:n integrointi.

Avaa kaavioiden tekijä

Voit luoda kaavioita selaimessasi ja näyttää ne ennakoituksessa ilman paikallista järjestelyä.