Markdown Integration

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

マークダウン統合

標準のフェンスで囲まれたコードブロックを使用して、Datro 図を Markdown ファイルに直接埋め込みます。ツールチェーンは、remark プラグイン (MDX、Next.js、Astro、および Vite 用) と markdown-it プラグイン (VitePress、Docusaurus、およびカスタムパイプライン用) を提供します。

コメントプラグインマークダウン 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.

ℹ️

ビルド時の検証

どちらのプラグインも、ビルド中に完全な 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 モードのみ)。デフォルトはソースファイルと同じディレクトリです。

マークダウン IT プラグイン

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 はそれなしで実行されます。

# 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 を参照してください。

ダイアグラムメーカーを開く

ローカル設定を行わずに、ブラウザで図を作成してプレビューします。