Avalonia.Controls.Markdown.Mermaid 12.4.0

Avalonia.Controls.Markdown.Mermaid

Mermaid diagrams for Avalonia.Controls.Markdown. A ```mermaid fence in a Markdown control is drawn as a native diagram: no browser, no JavaScript and no SVG.

Quick Start

Call UseMermaid() on the app builder:

public static AppBuilder BuildAvaloniaApp() => AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .UseMermaid();

Every Markdown control in the app then draws closed ```mermaid fences as diagrams:

```mermaid
flowchart LR
    A[Request] --> B{Cached?}
    B -->|yes| C[Serve cache]
    B -->|no| D[Render page]
```

To draw diagrams in one control only, add the extension to that control instead of calling UseMermaid() at startup; a control without it shows the fences as code:

markdown.Extensions.Add(new MermaidExtension());

MarkdownSerializer does not follow the app setting: new MarkdownSerializer(options, highlighter, [new MermaidExtension()]) reads fences into diagram blocks. UseMermaid() on a MarkdownPipelineBuilder adds the extension to a pipeline you configure yourself.

What is drawn

• Flowcharts (flowchart / graph): every node shape, subgraphs, edge labels, solid, dotted, thick and invisible edges, all four directions, and the style, classDef/class and linkStyle properties fill, stroke, stroke-width, color and stroke-dasharray.
• State diagrams (stateDiagram / stateDiagram-v2): states, start and end markers, choice, fork and join, composite states and notes.
• Class diagrams (classDiagram): classes with attribute and method compartments, annotations such as <<interface>>, visibility, static (underlined) and abstract (italic) members, every relationship kind with its UML marker, cardinalities, labels, namespaces and notes.
• Entity relationship diagrams (erDiagram): entities with attribute rows (type, name, keys, comment), crow's foot cardinalities, identifying and non-identifying relationships, and labels.
• Requirement diagrams (requirementDiagram): every requirement kind with its id, text, risk and verification method, elements with their type and document reference, every relationship kind, direction, and style, classDef, class and :::class.
• Quadrant charts (quadrantChart): the four captioned quadrants, axis captions, labelled points with their own or a classDef's radius, colour and stroke, and the chartWidth / chartHeight settings.
• Packet diagrams (packet): bit-range, single-bit and +N fields in rows, fields split across row breaks, bit numbers, and the bitsPerRow / showBits settings.
• Kanban boards (kanban): columns and cards with wrapped text, each card's ticket and assignee, and its priority as a coloured stripe. Ticket links (ticketBaseUrl) are not clickable.
• User journeys (journey): sections as coloured bands, task cards, a face per task placed by its score, actor dots with a legend, and the timeline arrow.
• Git graphs (gitGraph, gitGraph TB: / BT:): branches as coloured lanes in order, commits, merges, cherry-picks, HIGHLIGHT and REVERSE commits, ids and tags, and the showBranches, showCommitLabel, rotateCommitLabel, mainBranchName and mainBranchOrder settings. Commits without an id show none, where mermaid.js invents one.
• Gantt charts (gantt): sections, tasks with dates, durations, after and until, done / active / crit colours, milestones, vert markers, excludes (weekends, weekdays, dates) and weekend friday, axisFormat, tickInterval and weekday, dateFormat including Unix time, compact display mode, and a marker for today unless todayMarker off. The today marker is placed when the diagram is laid out, so a document left open past midnight shows yesterday until it is laid out again.
• Block diagrams (block): grids with columns, spans and spaces, nested block … end groups with their own grid, every flowchart shape, block arrows, links with labels and line kinds, and style, classDef and class.
• Sequence diagrams (sequenceDiagram): participants and actors, every arrow kind (->>, -->>, ->, -->, -x, -) and bidirectional), self messages, activations by +/- or activate/deactivate, notes left of, right of and over lifelines, loop, alt/else, opt, par/and, critical and break fragments, rect highlights, boxes, and created and destroyed participants.
• Pie charts (pie): slices with their share, a legend, showData and title.
• XY charts (xychart-beta, also horizontal): bar series side by side and line series, named or numeric x axis, y-axis title and range, grid lines at round values, and a legend for named series.

Box series are not drawn yet. They, other diagram types, and source that does not parse, show as text. A failed block carries the :visualizationFailed pseudo-class. A fence that is still streaming in shows as text until its closing fence arrives, so a diagram is not redrawn on every token.

A diagram's title, from its own title statement or else from title: in its frontmatter or init directive, is drawn above it.

The document does not change: a diagram is still a fenced code block, so it serializes, copies and searches as its source.

Theming

Diagrams follow the theme variant through ordinary resources. The package carries a light and a dark colour scheme of its own (softly tinted, rounded boxes with a light shadow, rounded edge bends, and labels on pills), so nothing has to be included. Any colour is overridden by a resource of the same key anywhere from the diagram up to the application, including in ThemeDictionaries, and a resource changed while the app runs is drawn with at once:

<Application.Resources>
  <ResourceDictionary>
    <ResourceDictionary.ThemeDictionaries>
      <ResourceDictionary x:Key="Light">
        <SolidColorBrush x:Key="MarkdownMermaidNodeBackground" Color="#EEF6FF" />
      </ResourceDictionary>
      <ResourceDictionary x:Key="Dark">
        <SolidColorBrush x:Key="MarkdownMermaidNodeBackground" Color="#1C2633" />
      </ResourceDictionary>
    </ResourceDictionary.ThemeDictionaries>
  </ResourceDictionary>
</Application.Resources>

A variant based on Dark (new ThemeVariant("Dim", ThemeVariant.Dark)) takes the dark scheme; any other variant takes the light one unless the application gives it colours. A resource of the wrong type, such as a Color under a brush key, is passed over.

Styles in the diagram source take precedence over the theme. A sequence box or rect colour that is fully opaque is drawn as a translucent tint, so the theme's lines and text stay readable on it.

Requirements

• .NET 8 or .NET 10
• Avalonia.Controls.Markdown

Dependencies

• Avalonia.Controls.Markdown

The Mermaid parsers and the Sugiyama graph layout engine are compiled into the package from the Mermaider fork, with their types internal, so they add no package references and do not clash with an app's own Mermaider or Sugiyama reference. See NOTICE.md for their licences.