MarkdownSerializer Class

Definition

Namespace:Avalonia.Controls.Documents.Serialization.Markdown

Assembly:Avalonia.Controls.Markdown

Package:Avalonia.Controls.Markdown

Avalonia.Controls.Documents.Serialization.IDocumentSerializer for Markdown files. Parses Markdown text into a Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot via Markdig, and writes snapshots back to markdown text.

public class MarkdownSerializer

Inheritance: object -> MarkdownSerializer

Implements:IDocumentSerializer

Remarks

Round-trip contract: documents whose content came from markdown (or was authored with the markdown-specific elements) re-parse to an equivalent snapshot after writing; discrete authoring data (heading levels, code languages, alert kinds, checked states, URLs, titles, alt text, footnote labels, table alignment) is preserved exactly, while syntax spellings the model does not store (emphasis delimiters, bullet chars, fence chars) are written in the canonical form configured by Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializer.Options. Foreign documents (RTF-loaded, arbitrary FlowDocuments) serialize as canonical markdown of whatever structure maps; unmappable formatting is dropped.

This serializer is thread-safe for concurrent operations: its options and pipeline are fixed at construction.

Cancellation is observed per block while a document is rendered or written. The Markdig parse that precedes rendering runs to completion once entered, so a token cancelled during it takes effect at the next block.

Constructors

Name	Description
MarkdownSerializer (2 overloads)	Initializes a new instance with the default options and no highlighter.

MarkdownSerializer overloads

MarkdownSerializer Constructor

Initializes a new instance with the default options and no highlighter.

public MarkdownSerializer()

MarkdownSerializer Constructor

Initializes a new instance of Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializer.

public MarkdownSerializer(Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializerOptions options, Avalonia.Controls.CodeHighlighter codeHighlighter)

Parameters

options Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializerOptions

Formatting choices for markdown output; defaults are used when .

codeHighlighter Avalonia.Controls.CodeHighlighter

Optional code highlighter applied to fenced blocks on read.

Methods

Name	Description
CanDeserialize	Checks if a stream appears to contain this format.
Deserialize (2 overloads)	Deserializes a document from a stream on the calling thread.
DeserializeAsync	Runs Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializer.Deserialize(System.IO.Stream,System.Threading.CancellationToken) on a pool thread.
Serialize (2 overloads)	Serializes a snapshot to a markdown string. Convenience overload for callers that do not need a stream.
SerializeAsync	Runs Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializer.Serialize(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot,System.IO.Stream,System.Threading.CancellationToken) on a pool thread.

CanDeserialize Method

Checks if a stream appears to contain this format.

public bool CanDeserialize(System.IO.Stream stream)

Parameters

stream System.IO.Stream

The stream to check. Must be readable and seekable.

Returns

bool

True if the stream likely contains this format; otherwise, false.

Remarks

This method does not consume the stream; it restores the original position after checking.

Deserialize overloads

Deserialize Method

Deserializes a document from a stream on the calling thread.

public Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot Deserialize(System.IO.Stream stream, System.Threading.CancellationToken cancellationToken)

Parameters

stream System.IO.Stream

The stream to read from. Must be readable.

cancellationToken System.Threading.CancellationToken

Cancellation token.

Returns

Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot

The deserialized Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot.

Remarks

Defaults to blocking on Avalonia.Controls.Documents.Serialization.IDocumentSerializer.DeserializeAsync(System.IO.Stream,System.Threading.CancellationToken), so a serializer written against the released interface keeps working. Implement this member instead: no format here performs asynchronous I/O, so the asynchronous pair only moves processor-bound work onto a pool thread.

Exceptions

• `stream` is null.
• `stream` is not readable.
• This serializer cannot read; see [Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanRead](xref:Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanRead).
• The stream content is invalid for this format.

Deserialize Method

Deserializes a snapshot from a markdown string. Convenience overload for callers that do not need a stream.

public Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot Deserialize(string markdown)

Parameters

markdown string

The markdown source text.

Returns

Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot

The parsed Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot.

DeserializeAsync Method

Runs Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializer.Deserialize(System.IO.Stream,System.Threading.CancellationToken) on a pool thread.

public System.Threading.Tasks.Task<Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot> DeserializeAsync(System.IO.Stream stream, System.Threading.CancellationToken cancellationToken)

Parameters

stream System.IO.Stream

The stream to read from.

cancellationToken System.Threading.CancellationToken

Cancellation token.

Returns

System.Threading.Tasks.Task<Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot>

The deserialized snapshot.

Remarks

A thread-offload convenience, not asynchronous I/O: no format here reads asynchronously. Where you are already off the UI thread, call Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializer.Deserialize(System.IO.Stream,System.Threading.CancellationToken) and keep the thread you are on.

Serialize overloads

Serialize Method

Serializes a snapshot to a markdown string. Convenience overload for callers that do not need a stream.

public string Serialize(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot snapshot)

Parameters

snapshot Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot

The snapshot to write.

Returns

string

The markdown source text.

Serialize Method

Serializes a document snapshot to a stream on the calling thread.

public void Serialize(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot snapshot, System.IO.Stream stream, System.Threading.CancellationToken cancellationToken)

Parameters

snapshot Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot

The document snapshot to serialize.

stream System.IO.Stream

The stream to write to. Must be writable.

cancellationToken System.Threading.CancellationToken

Cancellation token.

Remarks

Defaults to blocking on Avalonia.Controls.Documents.Serialization.IDocumentSerializer.SerializeAsync(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot,System.IO.Stream,System.Threading.CancellationToken), so a serializer written against the released interface keeps working. Implement this member instead.

Exceptions

• `snapshot` or `stream` is null.
• `stream` is not writable.
• This serializer cannot write; see [Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanWrite](xref:Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanWrite).

SerializeAsync Method

Runs Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializer.Serialize(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot,System.IO.Stream,System.Threading.CancellationToken) on a pool thread.

public System.Threading.Tasks.Task SerializeAsync(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot snapshot, System.IO.Stream stream, System.Threading.CancellationToken cancellationToken)

Parameters

snapshot Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot

The snapshot to serialize.

stream System.IO.Stream

The stream to write to.

cancellationToken System.Threading.CancellationToken

Cancellation token.

Returns

System.Threading.Tasks.Task

Remarks

A thread-offload convenience, not asynchronous I/O. The snapshot is already detached from the document, so the work needs no UI thread either way.

Properties

Name	Description
CanRead	Whether this serializer supports reading. Read-only UIs can filter serializer lists on this instead of catching NotSupportedException from Avalonia.Controls.Documents.Serialization.IDocumentSerializer.Deserialize(System.IO.Stream,System.Threading.CancellationToken).
CanWrite	Whether this serializer supports writing documents.
CodeHighlighter	Gets or sets the optional code highlighter used during deserialization.
FileExtension	Gets the file extension including the dot (e.g., ".rtf").
FormatName	Gets the format name this serializer handles (e.g., "Rtf", "Docx", "PlainText").
MimeType	Gets the MIME type for the format (e.g., "application/rtf").
Options	Gets the formatting choices for markdown output.

CanRead Property

Whether this serializer supports reading. Read-only UIs can filter serializer lists on this instead of catching NotSupportedException from Avalonia.Controls.Documents.Serialization.IDocumentSerializer.Deserialize(System.IO.Stream,System.Threading.CancellationToken).

public bool CanRead { get; set; }

Remarks

Defaults to so a serializer written before this member existed still compiles. A serializer that cannot read says so.

CanWrite Property

Whether this serializer supports writing documents.

public bool CanWrite { get; set; }

Remarks

Defaults to so a serializer written before this member existed still compiles. A serializer that cannot write says so.

CodeHighlighter Property

Gets or sets the optional code highlighter used during deserialization.

public Avalonia.Controls.CodeHighlighter CodeHighlighter { get; set; }

Remarks

Pass the highlighter to the constructor. A serializer handed to a background read and reconfigured through this setter changes the highlighter mid-read.

FileExtension Property

Gets the file extension including the dot (e.g., ".rtf").

public string FileExtension { get; set; }

FormatName Property

Gets the format name this serializer handles (e.g., "Rtf", "Docx", "PlainText").

public string FormatName { get; set; }

MimeType Property

Gets the MIME type for the format (e.g., "application/rtf").

public string MimeType { get; set; }

Options Property

Gets the formatting choices for markdown output.

public Avalonia.Controls.Documents.Serialization.Markdown.MarkdownSerializerOptions Options { get; set; }