MarkdownSyntaxTreeEditor Class

Changes several blocks of a MarkdownSyntaxTree, and parses the new text once.

public sealed class MarkdownSyntaxTreeEditor

Remarks

Each method records a change to a block of MarkdownSyntaxTreeEditor.OriginalTree, which does what the method of the same name of MarkdownSyntaxTree does. MarkdownSyntaxTreeEditor.GetChangedTree writes all the changes into the text, and parses it once: the time to change every block of a document is proportional to the length of the document, while a loop of MarkdownSyntaxTree edits parses the whole text for each of them.

The blocks are the ones of MarkdownSyntaxTreeEditor.OriginalTree, as they were before the changes. Text inserted before or after a block, a replaced block and a removed block cannot overlap: changing a block and a block it contains throws, except that removing a block removes the blocks it contains.

Example

var options = new MarkdownParseOptions { Extensions = MarkdownExtensions.GenericAttributes | MarkdownExtensions.AutoIdentifiers };
var tree = MarkdownSyntaxTree.ParseText("# Introduction\n\nGetting started {.lead}\n===\n", options);

// Write the identifier of every heading as its id, so that the links to it keep working when its text changes. The editor
// parses the text once, after all the changes: the headings are the ones of the original tree.
var editor = new MarkdownSyntaxTreeEditor(tree);
foreach (var heading in tree.GetRoot().DescendantNodes().OfType<MarkdownHeadingSyntax>())
{
    editor.SetGenericAttributes(heading, heading.GetGenericAttributes() with { Id = heading.Identifier });
}

tree = editor.GetChangedTree();

Assert.Equal("# Introduction {#introduction}\n\nGetting started {#getting-started .lead}\n===\n", tree.GetRoot().ToFullString());

Constructors

NameDescription
MarkdownSyntaxTreeEditor(MarkdownSyntaxTree)Initializes a new instance of the MarkdownSyntaxTreeEditor class, without changes.

MarkdownSyntaxTreeEditor(MarkdownSyntaxTree)

MarkdownSyntaxTreeEditor.cs

Initializes a new instance of the MarkdownSyntaxTreeEditor class, without changes.

public MarkdownSyntaxTreeEditor(MarkdownSyntaxTree tree)

Parameters

tree MarkdownSyntaxTree
The tree whose blocks are changed.

Exceptions

ArgumentNullException
tree is null.

Properties

NameDescription
OriginalTreeGets the tree whose blocks are changed, which the changes do not modify.

Gets the tree whose blocks are changed, which the changes do not modify.

public MarkdownSyntaxTree OriginalTree { get; }

Property value

MarkdownSyntaxTree

Methods

NameDescription
GetChangedTree()Gets a tree parsed from the text of MarkdownSyntaxTreeEditor.OriginalTree with the changes.
InsertBlocksAfter(MarkdownBlockSyntax, string)Inserts blocks after block, in its container.
InsertBlocksBefore(MarkdownBlockSyntax, string)Inserts blocks before block, in its container.
RemoveBlock(MarkdownBlockSyntax)Removes block and its lines.
ReplaceBlock(MarkdownBlockSyntax, string)Replaces block with other blocks, in its container.
SetGenericAttributes(MarkdownBlockSyntax, MarkdownGenericAttributes?)Replaces the generic attributes of block.

Gets a tree parsed from the text of MarkdownSyntaxTreeEditor.OriginalTree with the changes.

public MarkdownSyntaxTree GetChangedTree()

Returns

MarkdownSyntaxTree The new tree, or MarkdownSyntaxTreeEditor.OriginalTree when there is no change.

Exceptions

InvalidOperationException
Changes overlap, such as the replacements of a block and of a block it contains, or a block cannot have the attributes it is given, such as an HTML block, a list item or a footnote definition, which Markdig gives no attributes to.

InsertBlocksAfter(MarkdownBlockSyntax, string)

MarkdownSyntaxTreeEditor.cs

Inserts blocks after block, in its container.

public void InsertBlocksAfter(MarkdownBlockSyntax block, string markdown)

Parameters

block MarkdownBlockSyntax
The block of MarkdownSyntaxTreeEditor.OriginalTree to insert after.
markdown string
The blocks to insert, as Markdown that is not in a container: the markers of the containers of block are added to each of its lines.

Exceptions

ArgumentNullException
block or markdown is null.
ArgumentException
block is not a block of MarkdownSyntaxTreeEditor.OriginalTree.

Remarks

InsertBlocksBefore(MarkdownBlockSyntax, string)

MarkdownSyntaxTreeEditor.cs

Inserts blocks before block, in its container.

public void InsertBlocksBefore(MarkdownBlockSyntax block, string markdown)

Parameters

block MarkdownBlockSyntax
The block of MarkdownSyntaxTreeEditor.OriginalTree to insert before.
markdown string
The blocks to insert, as Markdown that is not in a container: the markers of the containers of block are added to each of its lines.

Exceptions

ArgumentNullException
block or markdown is null.
ArgumentException
block is not a block of MarkdownSyntaxTreeEditor.OriginalTree.

Remarks

RemoveBlock(MarkdownBlockSyntax)

MarkdownSyntaxTreeEditor.cs

Removes block and its lines.

public void RemoveBlock(MarkdownBlockSyntax block)

Parameters

block MarkdownBlockSyntax
The block of MarkdownSyntaxTreeEditor.OriginalTree to remove.

Exceptions

ArgumentNullException
block is null.
ArgumentException
block is not a block of MarkdownSyntaxTreeEditor.OriginalTree.

Remarks

See MarkdownSyntaxTree.RemoveBlock. Removing blocks that follow each other removes their lines together.

ReplaceBlock(MarkdownBlockSyntax, string)

MarkdownSyntaxTreeEditor.cs

Replaces block with other blocks, in its container.

public void ReplaceBlock(MarkdownBlockSyntax block, string markdown)

Parameters

block MarkdownBlockSyntax
The block of MarkdownSyntaxTreeEditor.OriginalTree to replace.
markdown string
The blocks that replace it, as Markdown that is not in a container: the markers of the containers of block are added to each of its lines.

Exceptions

ArgumentNullException
block or markdown is null.
ArgumentException
block is not a block of MarkdownSyntaxTreeEditor.OriginalTree.

Remarks

SetGenericAttributes(MarkdownBlockSyntax, MarkdownGenericAttributes?)

MarkdownSyntaxTreeEditor.cs

Replaces the generic attributes of block.

public void SetGenericAttributes(MarkdownBlockSyntax block, MarkdownGenericAttributes? attributes)

Parameters

block MarkdownBlockSyntax
The block of MarkdownSyntaxTreeEditor.OriginalTree whose attributes are replaced.
attributes MarkdownGenericAttributes?
The attributes of the block, or null to remove them.

Exceptions

ArgumentNullException
block is null.
ArgumentException
block is not a block of MarkdownSyntaxTreeEditor.OriginalTree, or attributes cannot be written, such as a class with whitespace or an attribute name that starts with a digit.
InvalidOperationException
The tree is parsed without MarkdownExtensions.GenericAttributes.

Remarks

See MarkdownSyntaxTree.WithGenericAttributes. MarkdownSyntaxTreeEditor.GetChangedTree checks that the block has the attributes in the new tree, and throws when it does not.