DiagramForge 1.0.0-rc.1

DiagramForge

Text in, SVG out. A .NET library and CLI that turns plain-text diagram descriptions into clean, self-contained SVG — no browser, no JavaScript runtime, no headless Chrome.

Representative snapshot fixtures from the E2E suite. Click any thumbnail to open the full-size SVG.

<h3>Diagram Types</h3>

DiagramForge currently supports more than a dozen diagram types across Mermaid and the conceptual DSL. This gallery is representative, not complete. See Supported syntax and Conceptual DSL below for the full set and syntax details.

<table cellpadding="12" width="100%"> <tr> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-edge-labels.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-edge-labels.expected.svg" alt="Flowchart" height="96" /> </a> <br /> _Flowchart </td> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-block.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-block.expected.svg" alt="Block diagram" height="96" /> </a> <br /> _Block </td> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-sequence.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-sequence.expected.svg" alt="Sequence" height="96" /> </a> <br /> _Sequence </td> </tr> <tr> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-architecture.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-architecture.expected.svg" alt="Architecture" height="96" /> </a> <br /> _Architecture </td> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-mindmap.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-mindmap.expected.svg" alt="Mindmap" height="96" /> </a> <br /> _Mindmap </td> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-timeline.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-timeline.expected.svg" alt="Timeline" height="96" /> </a> <br /> _Timeline </td> </tr> <tr> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-venn-two-set.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-venn-two-set.expected.svg" alt="Venn diagram" height="96" /> </a> <br /> _Venn </td> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-xychart.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-xychart.expected.svg" alt="XY chart" height="96" /> </a> <br /> _{XY Chart} </td> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-cycle.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-cycle.expected.svg" alt="Conceptual cycle" height="96" /> </a> <br /> _{Conceptual Cycle} </td> </tr> <tr> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-matrix.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-matrix.expected.svg" alt="Conceptual matrix" height="96" /> </a> <br /> _{Conceptual Matrix} </td> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-pillars.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-pillars.expected.svg" alt="Conceptual pillars" height="96" /> </a> <br /> _{Conceptual Pillars} </td> <td align="center" valign="top" width="33%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-pyramid.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-pyramid.expected.svg" alt="Conceptual pyramid" height="96" /> </a> <br /> _{Conceptual Pyramid} </td> </tr> </table>

<h3>Built-in Themes</h3>

This theme gallery is also a representative sample rather than the full catalog. DiagramForge ships with 23 built-in themes: default, zinc-light, zinc-dark, dark, neutral, forest, presentation, prism, angled-light, angled-dark, github-light, github-dark, nord, nord-light, dracula, tokyo-night, tokyo-night-storm, tokyo-night-light, catppuccin-latte, catppuccin-mocha, solarized-light, solarized-dark, and one-dark. See With a custom theme, doc/theming.md, and doc/frontmatter.md for the full styling surface.

<table cellpadding="16" width="100%"> <tr> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-default.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-default.expected.svg" alt="Default theme" width="400" /> </a> <br /> _Default </td> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-forest.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-forest.expected.svg" alt="Forest theme" width="400" /> </a> <br /> _Forest </td> </tr> <tr> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-neutral.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-neutral.expected.svg" alt="Neutral theme" width="400" /> </a> <br /> _Neutral </td> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-dracula.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-dracula.expected.svg" alt="Dracula theme" width="400" /> </a> <br /> _Dracula </td> </tr> <tr> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-github-dark.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-github-dark.expected.svg" alt="GitHub Dark theme" width="400" /> </a> <br /> _{GitHub Dark} </td> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-github-light.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-github-light.expected.svg" alt="GitHub Light theme" width="400" /> </a> <br /> _{GitHub Light} </td> </tr> <tr> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-catppuccin-latte.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-catppuccin-latte.expected.svg" alt="Catppuccin Latte theme" width="400" /> </a> <br /> _{Catppuccin Latte} </td> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-catppuccin-mocha.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-catppuccin-mocha.expected.svg" alt="Catppuccin Mocha theme" width="400" /> </a> <br /> _{Catppuccin Mocha} </td> </tr> <tr> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-presentation.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-presentation.expected.svg" alt="Presentation theme" width="400" /> </a> <br /> _Presentation </td> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-tokyo-night.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-tokyo-night.expected.svg" alt="Tokyo Night theme" width="400" /> </a> <br /> _{Tokyo Night} </td> </tr> <tr> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-one-dark.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-one-dark.expected.svg" alt="One Dark theme" width="400" /> </a> <br /> _{One Dark} </td> <td align="center" valign="top" width="50%"> <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-zinc-light.expected.svg"> <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/mermaid-theme-zinc-light.expected.svg" alt="Zinc Light theme" width="400" /> </a> <br /> _{Zinc Light} </td> </tr> </table>

var renderer = new DiagramRenderer();
string svg = renderer.Render("""
    flowchart LR
      A[Write] --> B[Build]
      B --> C{Tests pass?}
      C -->|yes| D[Ship]
      C -->|no| A
    """);

That's the whole API.

Why

Most diagram-as-code tools assume a browser. Mermaid.js needs a JavaScript engine to run at all — and even once you've stood up headless Chrome and extracted the SVG, you find that it renders text via <foreignObject> wrapping HTML <div>s instead of native <text> elements. That's fine in a web page. It's a blank box in Inkscape, a parse error in Illustrator, and a mess when you try to drop it into a PowerPoint slide. See mermaid-js/mermaid #2688, #1845, #1923, #2169.

DiagramForge aims lower and hits harder: a subset of Mermaid, rendered to actual SVG. Flowcharts, block diagrams, sequence diagrams, state diagrams, mindmaps, timelines, Venn diagrams, architecture diagrams, and XY charts — the output opens anywhere.

• Real SVG. Native <text> elements. No <foreignObject>, no embedded HTML, no CSS-in-SVG. Opens in Inkscape, imports into PowerPoint and Keynote, renders with librsvg.
• Pure .NET. net10.0, zero native dependencies, zero runtime package dependencies. No headless browser, no Node, no shelling out.
• Deterministic. Same input → byte-identical output. Safe to snapshot-test.
• Theme-able. Colors, fonts, spacing, corner radius — all overridable.
• Pluggable. Drop in your own IDiagramParser for custom syntaxes.

Install

DiagramForge targets .NET 10. For local development and the CLI tool, use SDK/runtime 10.0.100 or later.

Library

dotnet add package DiagramForge

CLI (.NET tool)

dotnet tool install -g DiagramForge.Tool

Library usage

Basic

using DiagramForge;

var renderer = new DiagramRenderer();
string svg = renderer.Render(diagramText);
File.WriteAllText("out.svg", svg);

The renderer auto-detects the syntax from the input. No need to tell it whether it's Mermaid or Conceptual DSL.

With a custom theme

using DiagramForge;
using DiagramForge.Models;

var theme = new Theme
{
    NodeFillColor   = "#1F2937",
    NodeStrokeColor = "#6366F1",
    TextColor       = "#F9FAFB",
    FontFamily      = "Inter, sans-serif",
    BorderRadius    = 12,
  TransparentBackground = true,
};

string svg = new DiagramRenderer().Render(diagramText, theme);

Theme precedence: frontmatter theme → parser-assigned Diagram.Theme → argument theme → Theme.Default.

See doc/theming.md for the full Theme property surface and doc/frontmatter.md for diagram-embedded styling.

With diagram frontmatter

Diagram files can embed a small frontmatter block ahead of Mermaid or Conceptual DSL content:

---
theme: dracula
palette: ["#FFB86C", "#8BE9FD", "#50FA7B"]
borderStyle: rainbow
fillStyle: diagonal-strong
shadowStyle: soft
transparent: true
---
flowchart LR
  A[Plan] --> B[Build]
  B --> C[Ship]

Supported frontmatter keys today: theme, palette, borderStyle / border-style, fillStyle / fill-style, shadowStyle / shadow-style, and transparent / transparentBackground / transparent-background.

With a custom parser

using DiagramForge;
using DiagramForge.Abstractions;

var renderer = new DiagramRenderer()
    .RegisterParser(new MyDotParser());   // tried before built-in parsers

// See what's registered
foreach (var id in renderer.RegisteredSyntaxes)
    Console.WriteLine(id);   // mydot, mermaid, conceptual

Implement IDiagramParser. You get two methods: CanParse(string) for sniffing the input, and Parse(string) which produces the unified Diagram model. Layout and rendering are handled for you.

CLI usage

diagramforge <input-file> [options]

Exit codes: 0 success · 1 bad arguments / file not found · 2 parse error · 3 unexpected failure.

CLI precedence mirrors the library API: frontmatter can define theme and styling inside the diagram source, while explicit CLI flags win for --palette and --transparent.

# write to file
diagramforge diagram.mmd -o diagram.svg

# render for overlay on an existing page background
diagramforge diagram.mmd --theme dracula --transparent -o overlay.svg

# pipe to something else
diagramforge diagram.txt | rsvg-convert -o diagram.png

Supported syntax

Mermaid (subset)

DiagramForge intentionally implements a focused Mermaid subset rather than full Mermaid parity. The first non-frontmatter line must start with one of the supported keywords below.

Flowchart

Keywords: flowchart or graph (+ optional direction suffix).

• Directions — LR, RL, TB, BT, TD
• Node shapes — A[rect], B(rounded), C{diamond}, D((circle))
• Edges — --> arrow, --- line, -.-> dotted, ==> thick
• Edge labels — A -->|label| B
• Subgraphs — subgraph title / end
• Comments — %% ignored

flowchart LR
  A[Rectangle] --> B(Rounded)
  B --> C{Decision}
  C -->|yes| D((Circle))
  C -.->|no| A

Block diagram

Keywords: block or block-beta.

• Columns — columns 3 (or columns auto)
• Column spans — b:2 makes a block span 2 columns
• Space gaps — space or space:N
• Arrow blocks — api<["HTTP"]>(right)
• Edges — A --> B, A -- "label" --> B

block-beta
  columns 3
  Frontend api<["HTTP"]>(right) Backend
  space queue<["async"]>(down) space
  Storage:3
  Frontend --> Backend
  Storage -- "events" --> Backend

Sequence diagram

Keyword: sequenceDiagram.

• Participants — participant A, participant A as Alice
• Messages — A->>B: Hello, B-->>A: Hi back
• Auto-created participants — undeclared participants are created on first use

sequenceDiagram
  participant A as Alice
  participant B as Bob
  A->>B: Hello
  B-->>A: Hi back
  A->>B: Done

State diagram

Keywords: stateDiagram or stateDiagram-v2.

stateDiagram-v2
  [*] --> Idle
  Idle --> Processing
  Processing --> Done
  Done --> [*]

Mindmap

Keyword: mindmap. Uses indentation for hierarchy.

mindmap
  root(Project)
    Planning
    Development
      Frontend
      Backend
    Testing

Timeline

Keyword: timeline.

• Title — title Product Roadmap
• Periods and entries — Q1 : Research

timeline
  title Product Roadmap
  Q1 : Research
     : Prototype
  Q2 : Beta
  Q3 : GA
     : Scale

Venn diagram

Keyword: venn-beta.

• Sets — set A["Alpha"]
• Unions — union A,B[Shared]
• Nested text — text Label["Detail"]

venn-beta
  set A["Alpha"]
  set B["Beta"]
  union A,B["Shared"]

Architecture diagram

Keyword: architecture-beta.

• Groups — group api(cloud)[API]
• Services — service db(database)[Database] in api
• Junctions — junction center
• Port-aware edges — db:L -- R:server

architecture-beta
  group api(cloud)[API]
  service db(database)[Database] in api
  service server(server)[Server] in api
  db:L -- R:server

XY chart

Keyword: xychart-beta.

• Title — title "Revenue"
• X axis — x-axis [Q1, Q2, Q3]
• Y axis — y-axis "USD" 0 --> 100
• Series — bar [...], line [...]

xychart-beta
  title "Revenue"
  x-axis [Q1, Q2, Q3]
  y-axis "USD" 0 --> 100
  bar [25, 50, 75]
  line [20, 55, 80]

Not yet supported: class diagrams, ER diagrams, gantt, git graphs, requirement diagrams, C4, sankey, click directives, ELK flowchart layout, and full Mermaid feature parity within every supported diagram family.

Conceptual DSL

A small YAML-ish format for presentation-native layouts that are awkward to express cleanly in Mermaid. First line is always diagram: <type>.

Rule of thumb: if the diagram is already easy to describe as Mermaid, use Mermaid. Use the Conceptual DSL when the primary value is a slide-style visual form such as a matrix, segmented pyramid, or circular cycle.

If You Want This, Use This

Planned conceptual additions are aimed at presentation-native graphics that Mermaid does not cover idiomatically, such as funnel, chevron process, and radial / hub-and-spoke.

matrix

diagram: matrix
rows:
  - Important
  - Not Important
columns:
  - Urgent
  - Not Urgent

pyramid

diagram: pyramid
levels:
  - Vision
  - Strategy
  - Tactics

cycle

Circular diagram for iterative processes and feedback loops. Accepts 3–6 steps arranged in a balanced radial layout with directional connectors.

diagram: cycle
steps:
  - Plan
  - Build
  - Measure
  - Learn

pillars

diagram: pillars
pillars:
  - title: People
    segments:
      - Skills
      - Roles
  - title: Process
    segments:
      - Intake
      - Delivery
  - title: Technology
    segments:
      - Platform
      - Tooling

Supported: 2-5 pillars, optional stacked segments per pillar. Segments are optional; a pillar with no segments: block renders as a single title block.

Architecture

flowchart LR
  A[Text Input] --> B[IDiagramParser]
  B --> C[Diagram Model]
  C --> D[ILayoutEngine]
  D --> E[ISvgRenderer]
  E --> F[SVG Output]

  B -.- B1(pluggable)
  C -.- C1(unified)
  D -.- D1(positions)
  E -.- E1(drawing)

Parsers produce a syntax-independent Diagram (nodes, edges, groups, labels, layout hints). The layout engine assigns coordinates. The SVG renderer draws. Every stage is replaceable via the DI constructor on DiagramRenderer.

Known limitations

• Mermaid support is intentionally incremental. If you need broad Mermaid.js feature coverage, DiagramForge is not a drop-in replacement.
• Frontmatter is recognized when the raw source starts with --- and contains a closing --- fence. Do not begin diagram content with a YAML-style fence unless you intend to use frontmatter.
• Snapshot tests compare canonicalized XML, so whitespace and attribute ordering are not significant in E2E baseline files.

Roadmap

See doc/prd.md for the full plan. Short version: more Mermaid diagram types, more conceptual layouts, theme packs, eventually D2 and DOT parsers.

Contributing

See CONTRIBUTING.md.

License

MIT