MarkdownEscaper Class

Provides methods to write text into Markdown, so that it is parsed back to the same text instead of being interpreted as Markdown syntax.

public static class MarkdownEscaper

Example

// Escape the text so that Markdown displays it as is: every ASCII punctuation character is escaped
Assert.Equal(@"\*Note\* \[docs\]\!", MarkdownEscaper.Escape("*Note* [docs]!"));

// The delimiters of code are longer than the runs of backticks of the content
Assert.Equal("``a`b``", MarkdownEscaper.CreateCodeSpan("a`b"));
Assert.Equal("`` `code` ``", MarkdownEscaper.CreateCodeSpan("`code`"));
Assert.Equal("```csharp\nvar a = 1;\n```\n", MarkdownEscaper.CreateFencedCodeBlock("var a = 1;", "csharp"));

// Build a link from untrusted parts
var text = MarkdownEscaper.Escape("Docs [v2]");
var destination = MarkdownEscaper.EscapeLinkDestination("https://example.com/a b");
var title = MarkdownEscaper.EscapeLinkTitle("Say \"hi\"");
Assert.Equal("<https://example.com/a b>", destination);
Assert.Equal("\"Say \\\"hi\\\"\"", title);

var html = MarkdownHtmlRenderer.ToHtml(MarkdownSyntaxTree.ParseText($"[{text}]({destination} {title})"));
Assert.Equal("<p><a href=\"https://example.com/a%20b\" title=\"Say &quot;hi&quot;\">Docs [v2]</a></p>\n", html);

// The label of a reference link
Assert.Equal(@"see \[1\]", MarkdownEscaper.EscapeLinkLabel("see [1]"));

// A cell of a pipe table cannot contain a pipe or a line ending
Assert.Equal(@"a \| b c", MarkdownEscaper.EscapeTableCell("a | b\nc"));

Methods

NameDescription
CreateCodeSpan(string)Creates an inline code span that contains the specified text.
CreateFencedCodeBlock(string, string?)Creates a fenced code block that contains the specified code.
Escape(string)Escapes every ASCII punctuation character with a backslash, so that the text is displayed as is.
Escape(string, MarkdownParseOptions)Escapes the text, as MarkdownEscaper.Escape does, and the characters where the extensions of the parse options would start a construct, so that the text is displayed as is when it is parsed with these options.
EscapeLinkDestination(string)Escapes a URL, so that it can be used as the destination of a link or an image: [text](destination).
EscapeLinkLabel(string)Escapes a link label, so that it can be used in a reference link and its link reference definition: [text][label] and [label]: destination.
EscapeLinkTitle(string)Escapes a link title and encloses it in double quotes, so that it can be used as the title of a link, an image, or a link reference definition: [text](destination "title").
EscapeTableCell(string)Escapes the text of a cell of a pipe table, so that it is displayed as is.

CreateCodeSpan(string)

MarkdownEscaper.cs

Creates an inline code span that contains the specified text.

public static string CreateCodeSpan(string content)

Parameters

content string
The content of the code span.

Returns

string The code span, including its backtick delimiters.

Exceptions

ArgumentException
content is empty: a code span cannot be empty.

Remarks

The delimiters are one backtick longer than the longest run of backticks of the content. The line endings of the content are replaced with spaces, as the parser converts them: a line of the code span could start a block, such as # a, and a blank line would end the paragraph.

CreateFencedCodeBlock(string, string?)

MarkdownEscaper.cs

Creates a fenced code block that contains the specified code.

public static string CreateFencedCodeBlock(string code, string? infoString = null)

Parameters

code string
The code. The lines are written as is.
infoString string?
The info string, such as the language of the code (csharp), or null for none.

Returns

string The fenced code block, ending with a line ending.

Exceptions

ArgumentException
infoString contains a line ending.

Remarks

The fence is at least three backticks, and longer than any line of the code that would close it. A line ending at the end of code is optional: it does not add an empty line to the block.

Escape overloads

Escape(string)

MarkdownEscaper.cs

Escapes every ASCII punctuation character with a backslash, so that the text is displayed as is.

public static string Escape(string text)
Parameters
text string
The text to escape.
Returns

string The escaped text.

Remarks

The spaces and the tabs that start or end a line are written as entities, such as &#32;: the parser would strip them, and they would start an indented code block or end the line with a hard line break. So the text stays text whatever its whitespace, and the parser decodes the entities to the same text. An empty line still ends the paragraph, and the parser replaces U+0000 with U+FFFD.

The extensions and the syntax extensions of the parse options are not taken into account: use MarkdownEscaper.Escape when the text is parsed with them.

Escape(string, MarkdownParseOptions)

MarkdownEscaper.cs

Escapes the text, as MarkdownEscaper.Escape does, and the characters where the extensions of the parse options would start a construct, so that the text is displayed as is when it is parsed with these options.

public static string Escape(string text, MarkdownParseOptions options)
Parameters
text string
The text to escape.
options MarkdownParseOptions
The options that parse the Markdown the text is written into.
Returns

string The escaped text.

Exceptions
ArgumentNullException
options is null.
Remarks

In addition to what MarkdownEscaper.Escape escapes, the trigger characters of the inline extensions of MarkdownParseOptions.SyntaxExtensions, the trigger characters of the fenced block extensions that start a line, and the first character of the shortcodes and the smileys of MarkdownParseOptions.EmojiMapping that the text contains when MarkdownExtensions.Emoji is enabled, are written as entities, such as &#167;, when they are not ASCII punctuation, which is escaped with a backslash.

The text is not protected from what the escaper cannot know or change: the abbreviations of MarkdownExtensions.Abbreviations are defined elsewhere in the document and match the words of the text, the paragraph extensions read the lines of the paragraph that contains the text, and an inline extension whose trigger character is & is tried on the entities.

EscapeLinkDestination(string)

MarkdownEscaper.cs

Escapes a URL, so that it can be used as the destination of a link or an image: [text](destination).

public static string EscapeLinkDestination(string url)

Parameters

url string
The URL.

Returns

string The escaped destination. It is enclosed in angle brackets when the URL is empty or contains spaces.

EscapeLinkLabel(string)

MarkdownEscaper.cs

Escapes a link label, so that it can be used in a reference link and its link reference definition: [text][label] and [label]: destination.

public static string EscapeLinkLabel(string label)

Parameters

label string
The label.

Returns

string The escaped label, without the brackets.

Exceptions

ArgumentException
label is blank, or longer than 999 characters once escaped.

Remarks

The parser matches the labels case-insensitively, and collapses consecutive whitespace, so the line endings of the label are replaced with spaces: a line of the label could start a block, such as # a, and a label cannot contain a blank line. A ^ that starts the label, after its spaces, is escaped, as [^label] is a footnote when MarkdownExtensions.Footnotes is enabled.

EscapeLinkTitle(string)

MarkdownEscaper.cs

Escapes a link title and encloses it in double quotes, so that it can be used as the title of a link, an image, or a link reference definition: [text](destination "title").

public static string EscapeLinkTitle(string title)

Parameters

title string
The title.

Returns

string The escaped title, enclosed in double quotes.

EscapeTableCell(string)

MarkdownEscaper.cs

Escapes the text of a cell of a pipe table, so that it is displayed as is.

public static string EscapeTableCell(string text)

Parameters

text string
The text of the cell.

Returns

string The escaped text.

Remarks

A row of a pipe table cannot span several lines, so the line endings are replaced by spaces. Then the text is escaped as with MarkdownEscaper.Escape, which also escapes the pipes. To write a code span in a cell, replace the pipes of the result of MarkdownEscaper.CreateCodeSpan with \|.