An inline declaration is `<!`, an ASCII letter, any characters other than `>`, and `>` (CommonMark 0.31.2). Lowercase names such as `<!doctype html>` and declarations without whitespace such as `<!x>` were escaped as text, unlike the matching declaration blocks. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.6 KiB
title
| title |
|---|
| CommonMark syntax |
CommonMark syntax
Markdig is fully compliant with the CommonMark specification (v0.31.2), passing 600+ spec tests. This page is a reference for all core Markdown syntax supported out of the box — no extensions required.
Headings
ATX headings
Use # characters (1–6) followed by a space:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
Setext headings
Underline text with = (level 1) or - (level 2):
Heading 1
=========
Heading 2
---------
Paragraphs
Paragraphs are separated by one or more blank lines. A single newline within a paragraph does not create a line break — it's treated as a space.
This is the first paragraph.
This is the second paragraph. This sentence
continues on the next line but renders inline.
Line breaks
To create a hard line break within a paragraph, end a line with two or more spaces or a backslash \:
First line
Second line (two trailing spaces above)
First line\
Second line (backslash above)
Emphasis and strong emphasis
*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic*** or ___bold and italic___
Renders as:
- italic text
- bold text
- bold and italic
Links
Inline links
[Link text](https://example.com)
[Link with title](https://example.com "Example Title")
Reference links
[Link text][ref]
[Another link][ref]
[ref]: https://example.com "Optional Title"
Autolinks
Angle brackets around a URL or email:
<https://example.com>
<user@example.com>
Images


![Alt text][imgref]
[imgref]: https://example.com/image.png "Title"
Code
Inline code
Use the `Markdown.ToHtml()` method.
Use the Markdown.ToHtml() method.
Fenced code blocks
Use triple backticks or triple tildes, optionally with a language identifier:
```csharp
var html = Markdown.ToHtml("Hello **world**!");
```
Or with tildes:
~~~python
print("Hello, world!")
~~~
Indented code blocks
Indent every line by 4 spaces or 1 tab:
var x = 42;
Console.WriteLine(x);
Blockquotes
Prefix lines with >:
> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > And be nested.
This is a blockquote.
It can span multiple paragraphs.
And be nested.
Lists
Unordered lists
Use -, *, or + as markers:
- Item one
- Item two
- Nested item
- Item three
- Item one
- Item two
- Nested item
- Item three
Ordered lists
Use numbers followed by . or ):
1. First item
2. Second item
3. Third item
1) Also valid
2) With parentheses
- First item
- Second item
- Third item
A nonempty list item can interrupt a paragraph without a blank line; an ordered
list must start at 1 to do so. An empty list item cannot interrupt an open
paragraph, but it can start a list after a blank line or after leaving a blockquote
container. After a blank line, an ordered list may start with any valid number.
List continuation
Indent content to align with the list item text:
1. First paragraph of item.
Second paragraph of the same item.
2. Another item.
Thematic breaks
Three or more -, *, or _ on a line (optionally with spaces):
---
***
___
HTML blocks
Raw HTML can be included directly:
<div class="custom">
This is raw HTML.
</div>
HTML blocks that end at a blank line, such as <div> blocks and complete tags
on their own line, also end at a line containing only spaces or tabs. Markdown
after that line is parsed normally. Blocks such as <script> and HTML comments
instead continue until their matching end condition.
Declaration blocks start with <! followed by an uppercase or lowercase ASCII
letter. Whitespace separators after known block tag names, and trailing whitespace
after complete standalone tags, must be spaces or tabs. Nonbreaking spaces and
other Unicode whitespace do not satisfy these start conditions.
For known block tag names, /> is a valid block-start boundary even after a
closing prefix, as in </div/>; this rule does not require a well-formed HTML tag.
Complete closing tags allow spaces, tabs, and at most one line ending before >.
They can span lines in inline HTML, but a block opened by a standalone complete
tag still requires the tag to be complete on its opening line.
Inline HTML
HTML tags can appear within inline content:
This is <em>inline HTML</em> in a paragraph.
Inline declarations follow the same rule as declaration blocks: <! followed by an
uppercase or lowercase ASCII letter, any characters other than >, and a closing >,
as in <!doctype html>.
Escaping
Use a backslash \ to escape special characters:
\*Not italic\*
\# Not a heading
\[Not a link\]
The following characters can be escaped: \ ` * _ { } [ ] ( ) # + - . ! |
Entities
HTML entities are supported:
© & < >
© ©
Blank lines
Blank lines separate block elements. Multiple consecutive blank lines are treated the same as a single blank line.
Next steps
- Extensions — Enable tables, task lists, math, footnotes, and 20+ more features
- Getting started — Install and configure Markdig