Markdown Integration

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

Markdown Entegrasyonu

Standart çitlerle çevrili kod bloklarını kullanarak Datro diyagramlarını doğrudan Markdown dosyalarına ekleyin. Araç zinciri bir açıklama eklentisi (MDX, Next.js, Astro ve Vite için) ve bir markdown-it eklentisi (VitePress, Docusaurus ve özel işlem hatları için) sağlar.

açıklama eklentisiişaretleme eklentisiCLI ardışık düzeniSVG · PNG çıktısı

Diyagram yerleştirme

Herhangi bir çitle çevrili kod bloğunu datro dil tanımlayıcıyla işaretleyin. Blok, #!DATRO 1.0 sihirli başlığıyla başlamalıdır. Eklenti, bloğu satır içi bir SVG (veya işlenmiş bir PNG'ye işaret eden <img> ile ayrıştırır, doğrular ve değiştirir.

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.

ℹ️

Derleme sırasında doğrulama

Her iki eklenti de derleme sırasında tam dört geçişli doğrulayıcıyı çalıştırır. Herhangi bir blokta hata şiddeti tanısı varsa derleme file:line:col konumuyla hemen başarısız olur.

Blok kimliği özelliği

Bir bloğa kararlı bir tanımlayıcı vermek için açılış çitinden sonra id="name" ekleyin. CLI bunu çıktı dosyalarını adlandırırken kullanır ve eklentiler bunu oluşturulan öğede bir veri niteliği olarak gösterir.

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

Çıkış dosyası `architecture-block-1.svg` yerine `architecture-auth-flow.svg` olur

açıklama eklentisi

Açıklamaya dayalı herhangi bir ardışık düzen ile kullanın: Next.js MDX, Astro, Gatsby, birleştirilmiş veya sade açıklama.

npm install datro remark remark-html

Yükle

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`	İşlenen çıktı biçimi.
`failOnError`	boolean	No	`true`	`false` olduğunda, hatalı bloklar derlemede başarısız olmak yerine korumalı kod olarak bırakılır.
`outDir`	string	No	—	PNG dosyaları için dizin (yalnızca PNG modu). Varsayılan olarak kaynak dosyayla aynı dizine ayarlanır.

işaretleme eklentisi

Herhangi bir markdown-it işlem hattıyla kullanın: VitePress, Docusaurus veya markdown-it'i doğrudan kullanan herhangi bir Node.js sunucusu.

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 ile doğrudan kullanım

💡

VitePress / Vite

VitePress'te eklentiyi defineConfig({ markdown: { config: md => md.use(datroPlugin) } })'a ekleyin. vite-plugin-markdown içeren Vite için aşağıdaki Vite yapılandırma örneğine bakın.

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 ardışık düzeni (paketleyici yok)

Paketleyici kullanmıyorsanız Markdown dosyalarını doğrudan işlemek için datro md CLI komutlarını kullanın. Bu, SVG/PNG çıktısı için Graphviz'i gerektirir, ancak md check onsuz çalışır.

# 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

Çıkış dosyaları {markdown-basename}-{block-id}.{svg|png} olarak adlandırılır.
Bazılarında hatalar olsa bile tüm blokları işlemek için --no-fail kullanın; geçiş ardışık düzenleri için kullanışlıdır.
CI açıklama sistemlerinde yapılandırılmış çıktı için --json'ı md check ile birlikte kullanın.

Sonraki adımlar

.dtro sözdiziminin tamamı için Language Reference dosyasını okuyun.
datro md render işaretleri ve CI entegrasyonu için CLI Reference'i okuyun.

Diyagram Oluşturucuyu Aç

Herhangi bir yerel kurulum gerekmeden tarayıcıda diyagramlar oluşturun ve önizleyin.