Markdown Integration

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

Markdown интеграциясы

Стандартты қоршалған код блоктарын пайдаланып, Datro диаграммаларын тікелей Markdown файлдарына ендіріңіз. Құралдар тізбегі ескерту плагинін (MDX, Next.js, Astro және Vite үшін) және markdown-it плагинін (VitePress, Docusaurus және реттелетін құбырлар үшін) қамтамасыз етеді.

ескерту плагиніmarkdown-it плагиніCLI құбырыSVG · PNG шығысы

Диаграмманы енгізу

Кез келген қоршалған код блогын datro тіл идентификаторымен белгілеңіз. Блок #!DATRO 1.0 сиқырлы тақырыбынан басталуы керек. Плагин талдайды, тексереді және блокты кірістірілген SVG (немесе <img> көрсетілген 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.

ℹ️

Құру уақытындағы валидация

Екі плагин де құрастыру кезінде толық төрт жолды валидаторды іске қосады. Кез келген блокта қатенің ауырлық диагностикасы болса, құрастыру file:line:col орнымен бірден сәтсіз аяқталады.

Блок идентификаторы төлсипаты

Блокқа тұрақты идентификатор беру үшін ашылатын қоршаудан кейін id="name" қосыңыз. CLI мұны шығыс файлдарын атау кезінде пайдаланады және плагиндер оны көрсетілетін элементте деректер төлсипаты ретінде көрсетеді.

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

Шығару файлы `architecture-block-1.svg` орнына `architecture-auth-flow.svg` болады

ескерту плагині

Кез келген ескертуге негізделген құбыр желісімен пайдаланыңыз: Next.js MDX, Astro, Gatsby, біріктірілген немесе қарапайым ескерту.

npm install datro remark remark-html

Орнату

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`	Көрсетілген шығыс пішімі.
`failOnError`	boolean	No	`true`	`false` кезінде қателері бар блоктар құрастыру сәтсіздігінің орнына қоршалған код ретінде қалдырылады.
`outDir`	string	No	—	PNG файлдарына арналған каталог (тек PNG режимі). Бастапқы файл сияқты бірдей каталогқа әдепкі мәндер.

markdown-it плагині

Кез келген markdown-it құбырымен пайдаланыңыз: VitePress, Docusaurus немесе markdown-it тікелей пайдаланатын кез келген Node.js сервері.

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

Markdown-it арқылы тікелей пайдалану

💡

VitePress / Vite

VitePress қолданбасында плагинді defineConfig({ markdown: { config: md => md.use(datroPlugin) } }) ішіне қосыңыз. vite-plugin-markdown бар Vite үшін төмендегі Vite конфигурациясының мысалын қараңыз.

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 құбыры (байланыссыз)

Топтаманы пайдаланбасаңыз, Markdown файлдарын тікелей өңдеу үшін datro md CLI пәрмендерін пайдаланыңыз. Бұл SVG/PNG шығысы үшін Graphviz бағдарламасын қажет етеді, бірақ md check онсыз жұмыс істейді.

# 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

Шығару файлдары {markdown-basename}-{block-id}.{svg|png} деп аталады.
Кейбіреулерінде қателер болса да, барлық блоктарды өңдеу үшін --no-fail пайдаланыңыз — тасымалдау құбырлары үшін пайдалы.
CI аннотация жүйелеріндегі құрылымдық шығыс үшін --json параметрін md check көмегімен пайдаланыңыз.

Келесі қадамдар

Толық .dtro синтаксисі үшін Language Reference оқыңыз.
CLI Reference жалаушалары мен CI интеграциясы үшін CLI Reference оқыңыз.

Диаграмма жасау құралын ашыңыз

Ешбір жергілікті орнатусыз браузерде диаграммаларды құрастырыңыз және алдын ала қараңыз.