Markdown Integration

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

Integracja z markdownem

Wkładać wykresy datro bezpośrednio do plików Markdown za pomocą standardowych zabezpieczonych bloków kodu. Łączna łańcuch narzędzi oferuje wtyczkę "Remark" (dla MDX, Next.js, Astro i Vite) oraz wtyczkę "Markdown-it" (dla VitePress, Docusaurus i custom pipelines)).

Plugin do komentarzyMarkdown-it-pluginCLI-PipelineSVG · PNG wydawnictwo

Wkładanie wykresu

Znajdź każdy blok kodu zamknięty z identyfikacją języka datro. Blok musi użyć magicznego nagłówka #!DATRO 1.0 rozpocząć. Plugin analizuje, weryfikuje i zastępuje blok za pomocą wewnętrznego SVG (lub <img>, który odnosi się do zwrotnego PNG).

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.

ℹ️

Validacja na czas budowy

Obie wtyczki wypełniają pełny potwierdzacz czterech pasów podczas budowy. W przypadku wykrycia ciężkości błędu dla bloku, konstrukcja uderza pozycją: file:line:col natychmiast zaginąć.

Atrybut identyfikacji bloku

Dodaj id="name" dodaje się po otwarciu, aby zapewnić stabilną identyfikację bloku. CLI używa tego w nazwach plików wydajnych, a wtyczki dostarczają je jako atrybut danych dla elementów zwróconych.

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

Wpływ plików wyjściowych `architecture-auth-flow.svg` zamiast: `architecture-block-1.svg`

Plugin do komentarzy

Wykorzystanie z dowolnego rurociągu opartego na komentarzach: Next.js MDX, Astro, Gatsby, Unified lub Plain Remark.

npm install datro remark remark-html

Zainstalowanie

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;

Następny.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`	Zmieniony format wydania.
`failOnError`	boolean	No	`true`	W przypadku `false` pozostają błędne bloki jako zabezpieczony kod zamiast niepowodzenia budowy.
`outDir`	string	No	—	Składnik do plików PNG (tylko w trybie PNG)). Standardowo ten sam katalog jak plik źródłowy.

Markdown-it-plugin

Wykorzystanie z dowolnego rurociągu Markdown-it: VitePress, Docusaurus lub dowolnego serwera Node.js wykorzystującego bezpośrednio 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);

Bezpośrednie korzystanie z markdown-it

💡

VitePress / Vite

Dodaj wtyczkę do VitePress defineConfig({ markdown: { config: md => md.use(datroPlugin) } }) dołączone. Dla Vite z vite-plugin-markdown Zobacz przykład konfiguracji Vite poniżej.

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-pipelina (nie złożona))

Jeśli nie używasz zestawu, użyj poleceń CLI datro md, do bezpośredniego przetwarzania plików markdown. Wymaga to graphviz dla wydawnictwa SVG/PNG, ale md check bez niego.

# 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

Wystąpienie w plików wydajnych {markdown-basename}-{block-id}.{svg|png} nazwa.
Wykorzystaj --no-fail, do przetwarzania wszystkich bloków, nawet jeśli mają pewne błędy użyteczne dla rurociągów migracji.
Wykorzystaj --json z md check dla strukturyzowanej emisji w systemach notyfikacji CI.

Następne kroki

Przeczytaj Language Reference .dtro-Syntaksa.
Przeczytaj flagę CLI reference datro md render i integracja CI.

Otwórz twórcę diagramów

Tworzyć wykresy w przeglądarce i wyświetlać je w przeglądarce bez konieczności lokalnego ustawienia.