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 RMarkdown syntax. In addition to CommonMark, MyST also implements and extends mdast, which is a standard abstract syntax tree for Markdown. mdast is part of the unifiedjs community and has many utilities for exporting and transforming your content.

Block Markup¶

Headings¶

type: string, (“heading”): See also Node
depth: integer: No description for this property.
enumerated: boolean, optional: count this heading for numbering based on kind, e.g. Section 2.4.1
enumerator: string, optional: resolved enumerated value for this heading
children: array, (PhrasingContent): See also Parent
identifier: string, optional: See also OptionalAssociation
label: string, optional: See also OptionalAssociation
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

### Heading!

Lists¶

type: string, (“list”): See also Node
ordered: boolean, optional: Is item order important or not?
start: integer, optional: Starting number of ordered list
spread: boolean, optional: One or more children are separated with a blank line from others
children: array, (ListContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

1. quotes
2. breaks
3. links

type: root
children:
  - type: list
    ordered: true
    start: 1
    spread: false
    children:
      - type: listItem
        spread: true
        children:
          - type: text
            value: quotes
      - type: listItem
        spread: true
        children:
          - type: text
            value: breaks
      - type: listItem
        spread: true
        children:
          - type: text
            value: links

Code¶

Block of preformatted text

type: string, (“code”): See also Node
lang: string, optional: language of the code
meta: string, optional: custom information relating to the node
class: string, optional: user-defined class for code block
showLineNumbers: boolean, optional: No description for this property.
startingLineNumber: integer, optional: No description for this property.
emphasizeLines: array, optional, (integer): No description for this property.
identifier: string, optional: See also OptionalAssociation
label: string, optional: See also OptionalAssociation
value: string: See also Literal
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

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

Blockquotes¶

type: string, (“blockquote”): See also Node
children: array, (FlowContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

> To be or not to be

Thematic Break¶

Line break

type: string, (“break”): See also Node
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

thematic

---

break

Link Definitions¶

Reference to a url resource

type: string, (“definition”): See also Node
identifier: string: See also OptionalAssociation
label: string, optional: See also OptionalAssociation
url: string: See also Resource
title: string, optional: See also Resource
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Paragraph¶

type: string, (“paragraph”): See also Node
children: array, (PhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

Something

Valid HTML¶

Fragment of raw HTML - does not need to be valid or complete

type: string, (“html”): See also Node
value: string: See also Literal
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

<div><p>*some text*</p></div>

Inline Markup¶

Inline links¶

Hyperlink

type: string, (“link”): See also Node
children: array, (StaticPhrasingContent): See also Parent
url: string: See also Resource
title: string, optional: See also Resource
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

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

type: root
children:
  - type: paragraph
    children:
      - type: link
        url: https://www.google.com
        title: Google
        children:
          - type: text
            value: search engine

Inline images¶

Image hyperlink

type: string, (“image”): See also Node
class: string, optional: user-defined class for image
width: string, optional: image width in pixels or percentage
align: string, optional, (“left” | “center” | “right”): No description for this property.
url: string: See also Resource
title: string, optional: See also Resource
alt: string, optional: See also Alternative
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

![fishy](fun-fish.png)

Text formatting¶

Emphasis¶

Stressed, italicized content

type: string, (“emphasis”): See also Node
children: array, (PhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Strong¶

Important, serious, urgent, bold content

type: string, (“strong”): See also Node
children: array, (PhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Inline Code¶

Fragment of code

type: string, (“inlineCode”): See also Node
value: string: See also Literal
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Markup

AST

Render

**strong**, _emphasis_, `literal text`, \*escaped symbols\*

type: root
children:
  - type: paragraph
    children:
      - type: strong
        children:
          - type: text
            value: strong
      - type: text
        value: ', '
      - type: emphasis
        children:
          - type: text
            value: emphasis
      - type: text
        value: ', '
      - type: inlineCode
        value: literal text
      - type: text
        value: ', *escaped symbols*'