markdown is a Rust library for parsing Markdown documents.

Source code can be found at code.benbridle.com/markdown.

Syntax

The Markdown syntax defined by this library departs from the defacto standard Markdown syntax in a few areas, notably with link syntax.

Block elements

Heading

A heading block is a single line prefixed by up to three hash characters and a space. It denotes a heading for a section of the document.

# First-level heading
## Second-level heading
### Third-level heading

List

A list block is a sequence of one or more lines each prefixed by a hyphen character and a space. It denotes a bullet list.

- List item 1
- List item 2

Note

A note block is a sequence of one or more lines each prefixed by a > character and a space. It denotes a note, quote, or aside.

> This is a note.
>
> This is a continuation of the same note.

Table

A table is a sequence of lines each prefixed by a | character.

Column alignment is determined by the position of the : characters in each cell of the line dividing the header from the table body.

The table body can be split into multiple sections with a row where the cells are filled only with - characters.

| Left         | Centered | Right |
|:-------------|:--------:|------:|
| Row *one*    | 1        | 1     |
| Row *two*    | 2        | 2     |
|--------------|----------|-------|
| Row *three*  | 3        | 3     |

Math block

A math block is a single line beginning with $$ and ending with $$. The content is not parsed.

$$ I = \frac{V}{R} $$

Break

A break is a single line containing only three or more - characters. It denotes a break in a length of text.

The paragraph preceding the break.
---
The paragraph following the break.

Embedded file

An embedded file block is a single line containing only a link prefixed with a ! character. It denotes a file to be rendered inline.

!<label::path>
!<Description of the file::/path/to/the/file.mp3>
!</path/with/no/description.jpg>

Syntax fragment

A fragment of non-markdown syntax to be rendered as code or to generate a special structure.

A syntax fragment block is a sequence of unparsed lines between two marker lines. The opening marker line contains three backtick characters followed by a name. The closing marker line contains only three backtick characters.

\```language

\```

Paragraph

A paragraph is a single line that doesn’t belong to any other kind of block.

Line elements

Lines can contain sections of styled text called line elements. A line element is enclosed by a pair of delimiters that determine the element type.

There cannot be a whitespace character after the opening delimiter or before the closing delimiter, and there must be a whitespace or punctuation character before the opening delimiter and after the closing delimiter.

Bold text

Bold text is delimited by the * character.

A *bolded line element*.

Italic text

Italicised text is delimited by the _ character.

An _italicised line element_.

Monospace text

Monospaced text is delimited by the backtick character.

A `monospaced line element`.

Math expression

A math expression is delimited by the $ character.

The equation $I = \frac{V}{R}$.

Internal link

Internal links are delimited by the { and } characters.

An optional :: separator will divide the link content into a label and a path.

Go to the {Markdown} page.

Go to {this page::Markdown} for more information.

External link

External links are delimited by the < and > characters.

An optional :: separator will divide the link content into a label and a path.

Visit <http://benbridle.com>.

Visit <this website::http://benbridle.com>.

Normal text

Anything that isn’t part of another line element is normal text.