Markdown Integration

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

마크다운 통합

표준 분리 코드 블록을 사용하여 Markdown 파일에 Datro 다이어그램을 직접 삽입하세요. 툴체인은 설명 플러그인(MDX, Next.js, Astro 및 Vite용)과 markdown-it 플러그인(VitePress, Docusaurus 및 사용자 정의 파이프라인용)을 제공합니다.

댓글 플러그인마크다운잇 플러그인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.

ℹ️

빌드 시 유효성 검사

두 플러그인 모두 빌드 중에 전체 4단계 유효성 검사기를 실행합니다. 블록에 오류 심각도 진단이 있는 경우 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-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 모드에만 해당). 기본값은 소스 파일과 동일한 디렉터리입니다.

마크다운잇 플러그인

VitePress, Docusaurus 또는 markdown-it을 직접 사용하는 모든 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 / 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 파일을 직접 처리하세요. SVG/PNG 출력을 위해서는 Graphviz가 필요하지만 md check는 Graphviz 없이 실행됩니다.

# 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을 읽어보세요.
datro md render 플래그 및 CI 통합에 대해서는 CLI Reference를 읽어보세요.

오픈 다이어그램 메이커

로컬 설정 없이 브라우저에서 다이어그램을 작성하고 미리 볼 수 있습니다.