🚀 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.

5. (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
);

6. (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.

7. (Optional) Enable Mermaid diagram rendering

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 MermaidBlockNode before using Mermaid diagrams in your Markdown content (e.g. App.axaml.cs):

using LiveMarkdown.Avalonia;

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

You can also include the default Mermaid styles and override them from your application styles:

<StyleInclude Source="avares://LiveMarkdown.Avalonia.Mermaid/Styles.axaml"/>

Mermaider options

MermaidPresenter.RenderOptions lets the native renderer use the same Mermaider options for the parts of rendering that are still owned by Mermaider: parsing constraints, layout spacing, custom layout providers, strict mode, and rounded-edge routing.

using LiveMarkdown.Avalonia;
using Mermaider.Models;

var presenter = new MermaidPresenter
{
    RenderOptions = new RenderOptions
    {
        Padding = 56,
        NodeSpacing = 48,
        LayerSpacing = 72,
        RoundedEdges = false,
        Strict = new StrictModeOptions
        {
            // Add pre-approved classes here when strict mode is enabled.
            AllowedClasses = []
        }
    }
};

The native renderer intentionally does not map RenderOptions color, font, or theme values back into Avalonia properties. Use Avalonia styles for visual appearance instead, for example md|MermaidPresenter.MermaidBlock for the presenter and renderer-part selectors such as md|MermaidPresenter md|DefaultRenderer for diagram-specific tokens.

For Markdown Mermaid blocks, complex RenderOptions objects are usually easiest to configure in C# in one central place. You can also assign a shared options object from a style:

<Style Selector="md|MermaidPresenter.MermaidBlock">
  <Setter Property="RenderOptions" Value="{StaticResource MermaidRenderOptions}"/>
</Style>

Current native synchronization scope:

• Flowchart and state diagrams pass Padding, NodeSpacing, LayerSpacing, LayoutProvider, Strict, and RoundedEdges to Mermaider layout.
• Class and ER diagrams use RenderOptions.LayoutProvider when supplied.
• Sequence diagrams use Mermaider's sequence layout, which currently does not accept RenderOptions.
• Colors, fonts, and Mermaid theme variables remain Avalonia style concerns in native rendering.

8. (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: Wait, I just want to render a single Markdown string. Why do I need ObservableStringBuilder?
• A: You do not need to manage an ObservableStringBuilder yourself just to bind one string. Use the built-in value converter:

  <md:MarkdownRenderer MarkdownBuilder="{Binding MarkdownString, Converter={x:Static md:ValueConverters.ToObservableStringBuilder}}"/>
  

  MarkdownRenderer.MarkdownBuilder = new ObservableStringBuilder(MarkdownString);
  

ObservableStringBuilder becomes valuable when content is arriving or may continue to change. It preserves incremental change information and is the most efficient path for streaming output.

For completed, immutable content that may be realized repeatedly—such as conversation history in a virtualized list—parse it once and keep the resulting MarkdownDocumentUpdate in the model. This trades memory for faster realization because the renderer can reuse the parsed MarkdownDocument whenever the item comes back on screen.

  public sealed class ChatMessage
  {
      public required string Content { get; init; }

      public MarkdownDocumentUpdate? CachedDocumentUpdate { get; private set; }

      public async Task PrepareDocumentAsync()
      {
          if (CachedDocumentUpdate is not null) return;

          var content = Content;
          CachedDocumentUpdate = await Task.Run(() =>
          {
              var document = Markdown.Parse(content, MarkdownUpdateProducer.DefaultPipeline);
              return new MarkdownDocumentUpdate.Full(document);
          });
      }
  }

  await message.PrepareDocumentAsync();

  // DocumentUpdate must be assigned on the Avalonia UI thread.
  MarkdownRenderer.DocumentUpdate = message.CachedDocumentUpdate;
  

DocumentUpdate can also be bound directly from a view model:

  <md:MarkdownRenderer DocumentUpdate="{Binding CachedDocumentUpdate}" />
  

Assigning it synchronously updates the visual children even before the renderer is attached, so its first measure sees the complete document. Treat every published MarkdownDocument as immutable. Release the cached update when reclaiming memory is more valuable than avoiding a later reparse.

- Q: How can I use a custom Markdown pipeline or own the update lifetime? - A: Assign an application-owned MarkdownUpdateProducer. MarkdownBuilder is a convenience proxy to the renderer's lazily created producer, but it does not prevent replacing that producer:

  renderer.UpdateProducer = new MarkdownUpdateProducer
  {
      Pipeline = customPipeline,
      MarkdownBuilder = markdownBuilder,
  };
  

The producer observes and parses its source while it has subscribers and synchronously replays its latest valid update to a new subscriber. The renderer owns only its subscription. Custom producers can implement IMarkdownUpdateProducer and publish MarkdownDocumentUpdate values from another source.

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

- 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>()
  );