Markdown Integration

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

降价集成

使用标准隔离代码块将 Datro 图表直接嵌入到 Markdown 文件中。该工具链提供了一个 remark 插件（适用于 MDX、Next.js、Astro 和 Vite）和一个 markdown-it 插件（适用于 VitePress、Docusaurus 和自定义管道）。

备注插件Markdown-it 插件CLI管道SVG·PNG输出

嵌入图表

使用 datro 语言标识符标记任何受防护的代码块。该块必须以 #!DATRO 1.0 魔术头开始。该插件解析、验证该块，并将其替换为内联 SVG（或指向渲染的 PNG 的 <img>）。

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 属性

在开放栅栏后添加 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 或任何直接使用 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

💡

Vite新闻/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 管道（无捆绑器）

如果您不使用捆绑程序，请使用 datro md CLI 命令直接处理 Markdown 文件。这需要 Graphviz 来进行 SVG/PNG 输出，但 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 集成。

打开图表制作器

在浏览器中构建和预览图表，无需任何本地设置。