MyST Markdown

CommonMark

This page provides an overview of the types of block and inline markup features supported by CommonMark and MyST, with pointers to additional content of interest. For full details on all the nuance of these features, please look at the CommonMark Spec documentation.

MyST (Markedly Structured Text) was designed to make it easier to create publishable computational documents written with Markdown notation. It is a superset of CommonMark Markdown and draws heavy inspiration from ReStructuredText and pandoc. In addition to CommonMark, MyST also implements and extends unist and mdast, which are standard abstract syntax trees for Markdown. unist is part of the unifiedjs community and has many utilities for analyzing, exporting and transforming your content.

#Block Markup

#Headings

Markdown syntax denotes headers starting with between 1 to 6 #. For example, a level 3 header looks like:

### Heading Level 3 Try changing the number of `#`s to change the `depth`.

#Setext Headings

An alternative syntax (called setext) is also supported for level 1 and 2 headers, by underlining using multiple === or ---. For example:

Heading 1 ========= Heading 2 ---------

#Lists

Bullet points:

- headings - lists - bullets - numbers - code blocks

Numbered items:

1. quotes 2. breaks 3. links

#Code

Code blocks are enclosed in 3 or more ` or ~ with an optional language name.

```python print('this is python') ```

Indented paragraphs are also treated as literal text. This may be used for code or other preformatted text.

Some JSON: { 'literal': '*text*' }

#Quotes

Quote blocks are prepended with >:

> Super profound quote

#Thematic Break

Create a horizontal line in the output

Section 1 --- Section 2

#Link Definitions

Links may be defined outside of text with a reference target (no spaces) and an optional title.

[This is a link defined elsewhere!][key] [key]: https://www.google.com 'a title'

#Paragraph

Any text that does not belong to another block is simply a paragraph:

any _text_

#Valid HTML

Any valid HTML may also be included in a MyST document and rendered to HTML. However, you must set the option allowDangerousHtml: true in the MyST parser.

#Inline Markup

#Inline links

Auto-link where link itself is shown in final output:

Search engine: <https://www.google.com>

Link with alternative text and optional title:

[search engine](https://www.google.com "Google")

#Inline images

Link to an image can be done similar to other inline links, or you may use HTML syntax to include image size, etc.

![alt](https://source.unsplash.com/random/500x200/?fruit "title")

#Text formatting

Standard inline formatting including bold, italic, code, as well as escaped symbols and line breaks:

**strong**, _emphasis_, `literal text`, \*escaped symbols\*, a hard\ break