🚀 Getting Started

1. Install the NuGet package

You can install the latest version from NuGet CLI:

dotnet add package LiveMarkdown.Avalonia

or use the NuGet Package Manager in your IDE.

4. (Optional) Enable LaTeX rendering

LaTeX is supported via the LiveMarkdown.Avalonia.Math package. You can install it via NuGet:

dotnet add package LiveMarkdown.Avalonia.Math

Then register both the MathInlineNode and MathBlockNode before using LaTeX in your Markdown content (e.g. App.axaml.cs):

using LiveMarkdown.Avalonia;

MarkdownNode.Register<MathInlineNode>();
MarkdownNode.Register<MathBlockNode>(); // This is also required for block-level LaTeX support, e.g. $$...$$

// Also, you can use the following code to register/unregister multiple nodes at once if needed:
MarkdownNode.Edit(builder => builder
    .Register<MathInlineNode>()
    .Register<MathBlockNode>()
    // .Unregister<SomeBuiltInNode>() // You can even unregister some built-in nodes if you want to disable certain Markdown features
);

5. (Optional) Enable SVG image rendering

SVG rendering is supported via the LiveMarkdown.Avalonia.Svg or LiveMarkdown.Avalonia.Svg.Skia package. You can install one of them via NuGet:

dotnet add package LiveMarkdown.Avalonia.Svg

or

dotnet add package LiveMarkdown.Avalonia.Svg.Skia

[!NOTE] The LiveMarkdown.Avalonia.Svg and LiveMarkdown.Avalonia.Svg.Skia packages provide two different implementations for SVG rendering. The former uses Svg.Controls.Avalonia which is more Avalonia-native, while the latter uses Svg.Skia which is more powerful and has better compatibility.

Then register the SvgImageDecoder into the AsyncImageLoader before using SVG images in your Markdown content (e.g. App.axaml.cs):

using LiveMarkdown.Avalonia;

AsyncImageLoader.DefaultDecoders =
[
    SvgImageDecoder.Shared,
    DefaultBitmapDecoder.Shared
];

You can also set the AsyncImageLoader.Decoders property on a per-renderer basis if you want different renderers to use different decoders.

6. (Optional) Enable Mermaid diagram rendering

[!WARNING] Mermaid diagram rendering is currently in early preview stage, and may have some issues. Only flowchart and state diagram are supported for now, and the rendering performance may not be optimal.

Mermaid diagram rendering is supported via the LiveMarkdown.Avalonia.Mermaid package. You can install it via NuGet:

dotnet add package LiveMarkdown.Avalonia.Mermaid

Then register the MermaidDiagramNode before using Mermaid diagrams in your Markdown content (e.g. App.axaml.cs):

using LiveMarkdown.Avalonia;

MarkdownRenderer.ConfigurePipeline += x => x.UseMermaid();
MarkdownNode.Register<MermaidBlockNode>();

7. (Optional) Configure Image cache

AsyncImageLoader uses the in-memory RamBasedAsyncImageLoaderCache.Shared by default. If you want persistent caching for remote images, enable the file-backed cache explicitly:

<Image md:AsyncImageLoader.Source="https://example.com/image.png" md:AsyncImageLoader.Cache="File"/>

Or set it globally:

AsyncImageLoader.DefaultCache = FileBasedAsyncImageLoaderCache.Shared;

FileBasedAsyncImageLoaderCache defaults to a cache directory under %LocalAppData%/LiveMarkdown.ImageCache, but you can configure it to any directory you want.

using LiveMarkdown.Avalonia;

FileBasedAsyncImageLoaderCache.CacheDirectory = Path.Combine(
    Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
    "YourApp",
    "ImageCache");
FileBasedAsyncImageLoaderCache.MaxCacheSizeBytes = 256L * 1024L * 1024L;
FileBasedAsyncImageLoaderCache.MaxEntrySizeBytes = 32L * 1024L * 1024L;
FileBasedAsyncImageLoaderCache.DefaultFreshnessLifetime = TimeSpan.FromDays(7);
HttpAsyncImageLoaderHandler.Shared.EnableConditionalRequests = true;

The file cache stores original image bytes under SHA-256 keys and uses common HTTP freshness/validation headers such as Cache-Control, Expires, ETag, and Last-Modified when available.

For advanced scenarios, you can even implement your own AsyncImageLoaderCache.

🤔 FAQ

- Q: Why some emojis not rendered correctly (rendered in single color)? - A: This is a known issue caused by Skia (the render backend of Avalonia). You can upgrade SkiaSharp version (e.g. >= 3.117.0) to fix this. Related issue

- Q: How does cross-block text selection work? - A: MarkdownRenderer uses MarkdownTextBlock to provide selection across Markdown blocks, including paragraphs, headings, tables, inline code, and code blocks. By default, the bundled style marks each MarkdownRenderer as a selection scope, so users can drag-select text across all selectable text blocks inside the same renderer.

If you need multiple renderers or custom containers to share one selection, set MarkdownTextBlock.IsSelectionScope="True" on their nearest shared visual parent:

<StackPanel md:MarkdownTextBlock.IsSelectionScope="True">
  <md:MarkdownRenderer/>
  <md:MarkdownRenderer/>
</StackPanel>

When scopes are nested, the topmost scope is used. This makes it possible to set a broad application-level selection scope, while still keeping the default renderer-level behavior for simple cases. The old MarkdownRenderer.SelectionScopeName API is kept for compatibility, but new code should use MarkdownTextBlock.IsSelectionScope.

During drag selection, moving the pointer outside a ScrollViewer automatically scrolls the nearest scrollable parent. For nested scroll viewers, the renderer follows Avalonia scroll chaining: it tries the inner ScrollViewer first and continues to outer scroll viewers only when ScrollViewer.IsScrollChainingEnabled allows it.

- Q: Why is LaTeX like \(xxx\) not rendered? - A: The default Markdig math parser supports $...$ and $$...$$. To support \(...\) and \[...\], enable the extended math parser before creating any MarkdownRenderer instances:

MarkdownRenderer.ConfigurePipeline += x => x.UseExtendedMathematics();
MarkdownNode.Edit(builder => builder
    .Register<MathInlineNode>()
    .Register<MathBlockNode>()
);