Markdown Integration

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

Интеграция уценки

Встраивайте диаграммы Datro непосредственно в файлы Markdown, используя стандартные изолированные блоки кода. В набор инструментов входит плагин примечаний (для MDX, Next.js, Astro и Vite) и плагин markdown-it (для VitePress, Docusaurus и пользовательских конвейеров).

плагин примечанийплагин markdown-itКонвейер CLISVG · Выход в формате 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-auth-flow.svg` вместо `architecture-block-1.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 или любым сервером Node.js, который напрямую использует 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);

Прямое использование с помощью markdown-it

💡

ВитеПресс / Вите

В VitePress добавьте плагин в defineConfig({ markdown: { config: md => md.use(datroPlugin) } }). Для Vite с vite-plugin-markdown см. пример конфигурации 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 (без упаковщика)

Если вы не используете сборщик, используйте команды CLI datro md для прямой обработки файлов Markdown. Для вывода 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 для обработки всех блоков, даже если в некоторых есть ошибки — это полезно для конвейеров миграции.
Используйте --json с md check для структурированного вывода в системах аннотаций CI.

Следующие шаги

Прочтите Language Reference для получения полного синтаксиса .dtro.
Прочтите CLI Reference для флагов datro md render и интеграции CI.

Открыть конструктор диаграмм

Создавайте и просматривайте диаграммы в браузере без какой-либо локальной настройки.