MarkView.Avalonia 12.0.3

MarkView.Avalonia

A Markdig-powered markdown viewer control for Avalonia UI v12. Drop MarkdownViewer into any Avalonia window or panel to render rich markdown — headings, code blocks, tables, task lists, links, images, and more — using native Avalonia controls with a fully customizable theme.

Installation

dotnet add package MarkView.Avalonia

Quick Start

Include the default theme and add MarkdownViewer to your XAML:

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:mv="using:MarkView.Avalonia">
  <Window.Styles>
    <StyleInclude Source="avares://MarkView.Avalonia/Themes/MarkdownTheme.axaml" />
  </Window.Styles>

  <mv:MarkdownViewer Markdown="# Hello, MarkView!" />
</Window>

Setting a base URI for relative links and images

viewer.BaseUri = new Uri("https://raw.githubusercontent.com/Kryptos-FR/MarkView.Avalonia/main/");
viewer.Markdown = markdownText; // relative image paths resolved against BaseUri

Handling link clicks

viewer.LinkClicked += (_, e) =>
{
    // e.Url contains the clicked URL
    Process.Start(new ProcessStartInfo(e.Url) { UseShellExecute = true });
};

LinkClickedEvent is an Avalonia routed event (bubbles up) — subscribe globally once at app startup to handle all viewers:

// App.axaml.cs — applies to every MarkdownViewer in the application
MarkdownViewer.LinkClickedEvent.AddClassHandler<MarkdownViewer>((_, e) =>
    Process.Start(new ProcessStartInfo(e.Url) { UseShellExecute = true }));

Navigating to an anchor

viewer.ScrollToAnchor("my-heading");  // scrolls to the heading's anchor position

Using a custom Markdig pipeline

viewer.Pipeline = new MarkdownPipelineBuilder()
    .UseSupportedExtensions()
    .UseAlertBlocks()
    .UseFootnotes()
    .Build();

Extension Methods

Convenience methods configure a pipeline with a single opt-in feature:

viewer.UseFootnotes();
viewer.UseAlertBlocks();
viewer.UseAbbreviations();
viewer.UseFigures();
viewer.UseMediaLinks();

To combine several opt-in features, build the pipeline explicitly (see above).

Application-Wide Defaults

MarkdownViewerDefaults lets you set a pipeline and/or extensions once so that every MarkdownViewer in the application inherits them automatically — no need to configure each instance:

// App.axaml.cs
MarkdownViewerDefaults.Pipeline = new MarkdownPipelineBuilder()
    .UseSupportedExtensions()
    .UseFootnotes()
    .UseAlertBlocks()
    .Build();

MarkdownViewerDefaults.Extensions.AddTextMateHighlighting();
MarkdownViewerDefaults.Extensions.AddSvg();
MarkdownViewerDefaults.Extensions.AddMermaid();

Per-instance Pipeline and Extensions take precedence over the defaults; an extension object shared between the defaults list and an instance list is only registered once per render.

Supported Markdown Features

CommonMark baseline (always on)

Extensions (enabled by UseSupportedExtensions())

Opt-in extensions

These require adding .UseXxx() to the pipeline (see Extension Methods below):

Extension Packages

MarkView.Avalonia ships optional NuGet packages that add richer rendering capabilities. Each package implements IMarkViewExtension and is activated via a convenience method on MarkdownViewer, or globally via MarkdownViewerDefaults.Extensions.AddXxx().

Syntax Highlighting (MarkView.Avalonia.SyntaxHighlighting)

Adds TextMate grammar-based syntax highlighting to fenced code blocks.

dotnet add package MarkView.Avalonia.SyntaxHighlighting

viewer.UseTextMateHighlighting(); // DarkPlus / LightPlus by default
// or with custom themes:
viewer.UseTextMateHighlighting(darkTheme: ThemeName.Monokai, lightTheme: ThemeName.QuietLight);

The extension replaces the built-in CodeBlockRenderer with TextMateCodeBlockRenderer, which tokenises each line and emits coloured Run elements. Unsupported languages fall back to the default monochrome rendering automatically.

Colours update in-place when the user switches between light and dark themes — no document rebuild or scroll reset.

Available ThemeName values are defined by TextMateSharp.Grammars: DarkPlus, LightPlus, Monokai, SolarizedDark, SolarizedLight, and more.

SVG Images (MarkView.Avalonia.Svg)

Renders SVG images embedded in markdown (![desc](path/to/image.svg)), including data:image/svg+xml data URIs and badge-service URLs that return SVG without a .svg extension.

dotnet add package MarkView.Avalonia.Svg

viewer.UseSvg();

The extension inserts SvgImageLoader at the front of the image loader chain. Regular raster images continue to load via the built-in HTTP fallback.

Mermaid Diagrams (MarkView.Avalonia.Mermaid)

Renders fenced mermaid code blocks as SVG diagrams using the Mermaider library (pure .NET, no browser required). Works on all platforms including Linux. Diagrams re-render automatically when the user switches between light and dark themes.

dotnet add package MarkView.Avalonia.Mermaid

viewer.UseMermaid();

Markdown syntax:

```mermaid
graph TD
  A[Start] --> B{Decision}
  B -- Yes --> C[End]
  B -- No  --> A
```

Combining extensions

All three can be stacked:

viewer
    .UseTextMateHighlighting()
    .UseSvg()
    .UseMermaid();

Extensions are applied in the order they are added to viewer.Extensions. Each extension's Register method is called once per render pass, before the Markdig pipeline is set up.

Writing your own extension

Implement IMarkViewExtension from the core package:

using MarkView.Avalonia.Extensions;
using MarkView.Avalonia.Rendering;

public class MyExtension : IMarkViewExtension
{
    public void Register(AvaloniaRenderer renderer)
    {
        // swap a renderer, add an image loader, or set a code highlighter
        renderer.ObjectRenderers.ReplaceOrAdd<CodeBlockRenderer>(new MyCodeBlockRenderer());
    }
}

viewer.Extensions.Add(new MyExtension());

Theming / Customization

Include MarkdownTheme.axaml for default styles. Override any style class in your own Styles to customise appearance:

Example — increase heading size and add a bottom border:

<Style Selector="TextBlock.markdown-h1">
  <Setter Property="FontSize" Value="36" />
  <Setter Property="Foreground" Value="#1A1A2E" />
  <Setter Property="Margin" Value="0,12,0,6" />
</Style>

Text Selection

MarkdownViewer supports full document-wide text selection:

• Click + drag to select a range.
• Ctrl+A to select all text.
• Ctrl+C to copy the selection to the clipboard.

Programmatic API:

viewer.SelectAll();
viewer.ClearSelection();
string text = viewer.GetSelectedText();
await viewer.CopyToClipboardAsync();

Images and task-list checkboxes are skipped during selection (same behaviour as all reference libraries).

Known Limitations

License

MIT © Nicolas Musset