Markdown Integration

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

Integrasi Penurunan Harga

Sematkan diagram Datro langsung di file Markdown menggunakan blok kode berpagar standar. Toolchain ini menyediakan plugin komentar (untuk MDX, Next.js, Astro, dan Vite) dan plugin markdown-it (untuk VitePress, Docusaurus, dan pipeline khusus).

plugin komentarplugin penurunan harga-ituPipa CLISVG · keluaran PNG

Menyematkan diagram

Tandai setiap blok kode yang dipagari dengan pengidentifikasi bahasa datro. Blok harus dimulai dengan header ajaib #!DATRO 1.0. Plugin mem-parsing, memvalidasi, dan mengganti blok dengan SVG inline (atau <img> yang menunjuk ke PNG yang dirender).

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.

ℹ️

Validasi pada waktu pembuatan

Kedua plugin menjalankan validator empat jalur penuh selama pembuatan. Jika ada blok yang memiliki diagnostik tingkat kesalahan, pembangunan akan langsung gagal dengan lokasi file:line:col.

Blokir atribut id

Tambahkan id="name" setelah pagar pembuka untuk memberi blok pengidentifikasi yang stabil. CLI menggunakan ini saat memberi nama file keluaran, dan plugin mengeksposnya sebagai atribut data pada elemen yang dirender.

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

File keluaran menjadi `architecture-auth-flow.svg` bukannya `architecture-block-1.svg`

plugin komentar

Gunakan dengan saluran berbasis komentar apa pun: Next.js MDX, Astro, Gatsby, komentar terpadu, atau biasa.

npm install datro remark remark-html

Instal

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;

Berikutnya.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`	Format keluaran yang diberikan.
`failOnError`	boolean	No	`true`	Ketika `false`, blok dengan kesalahan dibiarkan sebagai kode berpagar alih-alih gagal dalam pembangunan.
`outDir`	string	No	—	Direktori untuk file PNG (hanya mode PNG). Defaultnya ke direktori yang sama dengan file sumber.

plugin penurunan harga-itu

Gunakan dengan pipeline markdown-it apa pun: VitePress, Docusaurus, atau server Node.js apa pun yang menggunakan markdown-it secara langsung.

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);

Penggunaan langsung dengan penurunan harga

💡

VitePress / Vite

Di VitePress, tambahkan plugin ke defineConfig({ markdown: { config: md => md.use(datroPlugin) } }). Untuk Vite dengan vite-plugin-markdown lihat contoh konfigurasi Vite di bawah.

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" }]],
    }),
  ],
});

Pipa CLI (tanpa bundler)

Jika Anda tidak menggunakan bundler, gunakan perintah CLI datro md untuk memproses file Markdown secara langsung. Ini memerlukan Graphviz untuk keluaran SVG/PNG, tetapi md check berjalan tanpanya.

# 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

File keluaran diberi nama {markdown-basename}-{block-id}.{svg|png}.
Gunakan --no-fail untuk memproses semua blok meskipun beberapa blok mengalami kesalahan — berguna untuk alur migrasi.
Gunakan --json dengan md check untuk keluaran terstruktur dalam sistem anotasi CI.

Langkah selanjutnya

Baca Language Reference untuk sintaks .dtro selengkapnya.
Baca tanda CLI Reference untuk datro md render dan integrasi CI.

Buka Pembuat Diagram

Buat dan pratinjau diagram di browser tanpa pengaturan lokal apa pun.