Files
markdig/site/docs/commonmark.md
Alexandre Mutel d33c703de0 Fix CommonMark inline HTML declarations
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>
2026-10-16 06:33:14 +02:00

5.6 KiB
Raw Permalink Blame History

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
[Link text](https://example.com)
[Link with title](https://example.com "Example Title")
[Link text][ref]
[Another link][ref]

[ref]: https://example.com "Optional Title"

Angle brackets around a URL or email:

<https://example.com>
<user@example.com>

Images

![Alt text](https://example.com/image.png)
![Alt text](https://example.com/image.png "Title")

![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
  1. First item
  2. Second item
  3. 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:

&copy; &amp; &lt; &gt; &nbsp;
&#169; &#x00A9;

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