Specification

MyST

Node Type Index

FlowContent¶

ListContent¶

Only ListItem

PhrasingContent¶

StaticPhrasingContent¶

BlockBreak¶

Top-level break in the myst document, breaking it into Blocks

type: string, ("blockBreak"): See also Node
meta: string, optional: Block metadata. Conventionally this is a stringified JSON dictionary but it may be any arbitrary string.
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Block¶

Top-level content blocks or cells the myst document, delimited by BlockBreaks

type: string, ("block"): See also Node
meta: string, optional: block metadata from preceding break; conventionally, a stringified JSON dictionary but may be any arbitrary string
children: array, optional, (FlowContent | ListContent | PhrasingContent): Top-level children of myst document
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Role¶

Custom in-line behavior

type: string, ("mystRole"): See also Node
name: string: No description for this property.
value: string, optional: content of the directive
children: array, optional, (PhrasingContent): parsed role content
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Directive¶

Content block with predefined behavior

type: string, ("mystDirective"): See also Node
name: string: No description for this property.
args: string, optional: No description for this property.
options: object, optional: No description for this property.
value: string, optional: body of the directive, excluding options
children: array, optional, (FlowContent | PhrasingContent): parsed directive content
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Target¶

Target node - provides identifier/label for the following node

type: string, ("mystTarget"): See also Node
label: string, optional: unresolved target label
position: object, optional, (Position): See also Node
data: object, optional: See also Node

CrossReference¶

In-line reference to an associated node

type: string, ("crossReference"): See also Node
kind: string, optional, ("eq" | "numref" | "ref"): Indicates if the references should be numbered.
Warning
The kind was based on docutils and is subject to change as we improve the crossReference experience.
children: array, optional, (StaticPhrasingContent): Children of the crossReference, can include text with "%s" or "{number}" and enumerated references will be filled in.
identifier: string: See also OptionalAssociation
label: string, optional: See also OptionalAssociation
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Abbreviation¶

Abbreviation node described by title

type: string, ("abbreviation"): See also Node
children: array, (StaticPhrasingContent): abbreviated value; See also Parent
title: string, optional: advisory information for the abbreviation
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Admonition¶

Admonition node for drawing attention to text, separate from the neighboring content

type: string, ("admonition"): See also Node
kind: string, optional, ("attention" | "caution" | "danger" | "error" | "hint" | "important" | "note" | "seealso" | "tip" | "warning"): kind of admonition, to determine styling
class: string, optional: admonition class info to override kind
children: array, optional, (AdmonitionTitle | FlowContent): An optional admonitionTitle followed by the admonitions content.
position: object, optional, (Position): See also Node
data: object, optional: See also Node

AdmonitionTitle¶

Custom title for admonition, replaces kind as title

type: string, ("admonitionTitle"): See also Node
children: array, (PhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Container¶

Top-level container node to provide association and numbering to child content

type: string, ("container"): See also Node
kind: string, ("figure" | "table"): kind of container contents
class: string, optional: any custom class information
enumerated: boolean, optional: count this container for numbering based on kind, e.g. Figure 1a
enumerator: string, optional: resolved enumerated value for this container
children: array, (Caption | Legend | Image | Table): 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

Caption¶

Caption for container content

type: string, ("caption"): See also Node
children: array, (FlowContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Legend¶

Legend for container content

type: string, ("legend"): See also Node
children: array, (FlowContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

FootnoteReference¶

Inline reference to footnote

type: string, ("footnoteReference"): See also Node
identifier: string: See also OptionalAssociation
label: string, optional: See also OptionalAssociation
position: object, optional, (Position): See also Node
data: object, optional: See also Node

FootnoteDefinition¶

Rich footnote content associated with footnote reference

type: string, ("footnoteDefinition"): See also Node
children: array, (FlowContent): See also Parent
identifier: string: See also OptionalAssociation
label: string, optional: See also OptionalAssociation
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Math¶

Math node for presenting numbered equations

type: string, ("math"): See also Node
enumerated: boolean, optional: count this math block for numbering based on kind, e.g. See equation (1a)
enumerator: string, optional: resolved enumerated value for this math block
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

InlineMath¶

Fragment of math, similar to InlineCode, using role {math}

type: string, ("inlineMath"): See also Node
value: string: See also Literal
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Table¶

Two-dimensional table data

type: string, ("table"): See also Node
align: string, optional, ("left" | "center" | "right"): No description for this property.
children: array, (TableRow): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

TableRow¶

One row of table containing cells

type: string, ("tableRow"): See also Node
children: array, (TableCell): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

TableCell¶

One cell of table

type: string, ("tableCell"): See also Node
header: boolean, optional: No description for this property.
align: string, optional, ("left" | "center" | "right"): alignment of content within cell
children: array, (PhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Subscript¶

Subscript content, using role {subscript}

type: string, ("subscript"): See also Node
children: array, (PhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

SubscriptStatic¶

Subscript content, with static children; used when parent node requires static content

type: string, ("subscript"): See also Node
children: array, (StaticPhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Superscript¶

Superscript content, using role {superscript}

type: string, ("superscript"): See also Node
children: array, (PhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

SuperscriptStatic¶

Superscript content, with static children; used when parent node requires static content

type: string, ("superscript"): See also Node
children: array, (StaticPhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Underline¶

Underline content, using role {underline}

type: string, ("underline"): See also Node
children: array, (PhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

UnderlineStatic¶

Underline content, with static children; used when parent node requires static content

type: string, ("underline"): See also Node
children: array, (StaticPhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Comment¶

Comment nodes for comments present in myst but ingnored upon render

type: string, ("mystComment"): See also Node
value: string: See also Literal
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

Heading¶

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

ThematicBreak¶

type: string, ("thematicBreak"): See also Node
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Blockquote¶

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

List¶

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

ListItem¶

type: string, ("listItem"): See also Node
spread: boolean, optional: One or more children are separated with a blank line from others
children: array, (PhrasingContent | FlowContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

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

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

Definition¶

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

Text¶

type: string, ("text"): See also Node
value: string: See also Literal
position: object, optional, (Position): See also Node
data: object, optional: See also Node

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

EmphasisStatic¶

Stressed, italicized content, with static children; used when parent node requires static content

type: string, ("emphasis"): See also Node
children: array, (StaticPhrasingContent): 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

StrongStatic¶

Important, serious, urgent, bold content, with static children; used when parent node requires static content

type: string, ("strong"): See also Node
children: array, (StaticPhrasingContent): See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

InlineCode¶

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

Break¶

Line break

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

Link¶

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

Image¶

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

LinkReference¶

Hyperlink through association

type: string, ("linkReference"): See also Node
children: array, (StaticPhrasingContent): See also Parent
referenceType: string, ("shortcut" | "collapsed" | "full"): See also Reference
identifier: string: See also OptionalAssociation
label: string, optional: See also OptionalAssociation
position: object, optional, (Position): See also Node
data: object, optional: See also Node

ImageReference¶

Image through association

type: string, ("imageReference"): See also Node
referenceType: string, ("shortcut" | "collapsed" | "full"): See also Reference
identifier: string: See also OptionalAssociation
label: string, optional: See also OptionalAssociation
alt: string, optional: See also Alternative
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Resource¶

Reference to external resource

url: string: A Uniform Resource Locator (URL) to an external resource or link.
title: string, optional: advisory information, e.g. for a tooltip

OptionalAssociation¶

Internal relation from one node to another; not required by node

identifier: string, optional: identifier that may match another node; value is unparsed and must be normalized such that whitespace is collapsed to single space, initial/final space is trimmed, and case is folded
label: string, optional: node label; character escapes and references are parsed; may be normalized to a unique identifier

Association¶

Internal relation from one node to another

identifier: string: See also OptionalAssociation
label: string, optional: node label; character escapes and references are parsed; may be normalized to a unique identifier; See also OptionalAssociation

Alternative¶

Alternative description of image

alt: string, optional: field describing the image

Reference¶

Marker associated to another node

referenceType: string, ("shortcut" | "collapsed" | "full"): explicitness of the reference: shortcut - reference is implicit, identifier inferred collapsed - reference explicit, identifier inferred full - reference explicit, identifier explicit

Node¶

Base node object, based on the unist syntax tree.

type: string: identifier for node variant
data: object, optional: information associated by the ecosystem with the node; never specified by mdast
position: object, optional, (Position): location of node in source file; must not be present for generated nodes

Literal¶

Basic node with required string value

value: string: The value of the node
type: string: identifier for node variant; See also Node
data: object, optional: information associated by the ecosystem with the node; never specified by mdast; See also Node
position: object, optional, (Position): location of node in source file; must not be present for generated nodes; See also Node

Parent¶

Basic node with required node children

children: array, (Node): List of children nodes
type: string: identifier for node variant; See also Node
data: object, optional: information associated by the ecosystem with the node; never specified by mdast; See also Node
position: object, optional, (Position): location of node in source file; must not be present for generated nodes; See also Node

Point¶

One place in a source file

line: integer: line in the source file, 1-indexed
column: integer: column in the source file, 1-indexed
offset: integer, optional: offset character in the source file, 0-indexed

Position¶

Location of a node in a source file

start: object, (Point): place of first character of parsed source region
end: object, (Point): place of first character after parsed source region, whether it exists or not
indent: array, optional, (integer): start column at each index in the source region, for elements that span multiple lines

Root¶

Myst syntax tree built on existing mdast schemas

type: string, ("root"): See also Node
children: array, (Block | BlockBreak | FlowContent): Top-level children of myst document; See also Parent
position: object, optional, (Position): See also Node
data: object, optional: See also Node

MyST Spec

Blocks & Comments