![mdast][logo]

Markdown Abstract Syntax Tree.

---

mdast is a specification for representing markdown in a [syntax tree][syntax-tree]. It implements [unist][]. It can represent several flavours of [markdown][], such as [CommonMark][] and [GitHub Flavored Markdown][gfm].

This document may not be released. See [releases][] for released documents. The latest released version is [5.0.0][latest].

Contents

• Introduction
  • Where this specification fits
• Types
• Nodes (abstract)
  • Literal
  • Parent
• Nodes
  • Blockquote
  • Break
  • Code
  • Definition
  • Emphasis
  • Heading
  • Html
  • Image
  • ImageReference
  • InlineCode
  • Link
  • LinkReference
  • List
  • ListItem
  • Paragraph
  • Root
  • Strong
  • Text
  • ThematicBreak
• Mixin
  • Alternative
  • Association
  • Reference
  • Resource
• Enumeration
  • referenceType
• Content model
  • Content
  • FlowContent
  • ListContent
  • PhrasingContent
• Extensions
  • GFM
  • Frontmatter
  • MDX
• Glossary
• List of utilities
• References
• Security
• Related
• Contribute
• Acknowledgments
• License

Introduction

This document defines a format for representing [markdown][] as an [abstract syntax tree][syntax-tree]. Development of mdast started in July 2014, in [remark][], before [unist][] existed. This specification is written in a [Web IDL][webidl]-like grammar.

Where this specification fits

mdast extends [unist][], a format for syntax trees, to benefit from its [ecosystem of utilities][utilities].

mdast relates to [JavaScript][] in that it has a rich [ecosystem of utilities][list-of-utilities] for working with compliant syntax trees in JavaScript. However, mdast is not limited to JavaScript and can be used in other programming languages.

mdast relates to the [unified][] and [remark][] projects in that mdast syntax trees are used throughout their ecosystems.

Types

If you are using TypeScript, you can use the unist types by installing them with npm:

npm install @types/mdast

Nodes (abstract)

Literal

interface Literal <: UnistLiteral {
  value: string
}

Literal ([UnistLiteral][dfn-unist-literal]) represents an abstract interface in mdast containing a value.

Its value field is a string.

Parent

interface Parent <: UnistParent {
  children: [MdastContent]
}

Parent ([UnistParent][dfn-unist-parent]) represents an abstract interface in mdast containing other nodes (said to be [children][term-child]).

Its content is limited to only other [mdast content][dfn-mdast-content].

Nodes

Blockquote

interface Blockquote <: Parent {
  type: 'blockquote'
  children: [FlowContent]
}

Blockquote ([Parent][dfn-parent]) represents a section quoted from somewhere else.

Blockquote can be used where [flow][dfn-flow-content] content is expected. Its content model is also [flow][dfn-flow-content] content.

For example, the following markdown:

> Alpha bravo charlie.

Yields:

{
  type: 'blockquote',
  children: [{
    type: 'paragraph',
    children: [{type: 'text', value: 'Alpha bravo charlie.'}]
  }]
}

Break

interface Break <: Node {
  type: 'break'
}

Break ([Node][dfn-node]) represents a line break, such as in poems or addresses.

Break can be used where [phrasing][dfn-phrasing-content] content is expected. It has no content model.

For example, the following markdown:

foo··
bar

Yields:

{
  type: 'paragraph',
  children: [
    {type: 'text', value: 'foo'},
    {type: 'break'},
    {type: 'text', value: 'bar'}
  ]
}

Code

interface Code <: Literal {
  type: 'code'
  lang: string?
  meta: string?
}

Code ([Literal][dfn-literal]) represents a block of preformatted text, such as ASCII art or computer code.

Code can be used where [flow][dfn-flow-content] content is expected. Its content is represented by its value field.

This node relates to the [phrasing][dfn-phrasing-content] content concept [InlineCode][dfn-inline-code].

A lang field can be present. It represents the language of computer code being marked up.

If the lang field is present, a meta field can be present. It represents custom information relating to the node.

For example, the following markdown:

    foo()

Yields:

{
  type: 'code',
  lang: null,
  meta: null,
  value: 'foo()'
}

And the following markdown:

```js highlight-line="2"
foo()
bar()
baz()
```

Yields:

{
  type: 'code',
  lang: 'js',
  meta: 'highlight-line="2"',
  value: 'foo()\nbar()\nbaz()'
}

Definition

interface Definition <: Node {
  type: 'definition'
}

Definition includes Association
Definition includes Resource

Definition ([Node][dfn-node]) represents a resource.

Definition can be used where [content][dfn-content] is expected. It has no content model.

Definition includes the mixins [Association][dfn-mxn-association] and [Resource][dfn-mxn-resource].

Definition should be associated with [LinkReferences][dfn-link-reference] and [ImageReferences][dfn-image-reference].

For example, the following markdown:

[Alpha]: https://example.com

Yields:

{
  type: 'definition',
  identifier: 'alpha',
  label: 'Alpha',
  url: 'https://example.com',
  title: null
}

Emphasis

interface Emphasis <: Parent {
  type: 'emphasis'
  children: [PhrasingContent]
}

Emphasis ([Parent][dfn-parent]) represents stress emphasis of its contents.

Emphasis can be used where [phrasing][dfn-phrasing-content] content is expected. Its content model is [phrasing][dfn-phrasing-content] content.

For example, the following markdown:

*alpha* _bravo_

Yields:

{
  type: 'paragraph',
  children: [
    {
      type: 'emphasis',
      children: [{type: 'text', value: 'alpha'}]
    },
    {type: 'text', value: ' '},
    {
      type: 'emphasis',
      children: [{type: 'text', value: 'bravo'}]
    }
  ]
}

Heading

interface Heading <: Parent {
  type: 'heading'
  depth: 1 <= number <= 6
  children: [PhrasingContent]
}

Heading ([Parent][dfn-parent]) represents a heading of a section.

Heading can be used where [flow][dfn-flow-content] content is expected. Its content model is [phrasing][dfn-phrasing-content] content.

A depth field must be present. A value of 1 is said to be the highest rank and 6 the lowest.

For example, the following markdown:

# Alpha

Yields:

{
  type: 'heading',
  depth: 1,
  children: [{type: 'text', value: 'Alpha'}]
}

Html

interface Html <: Literal {
  type: 'html'
}

Html ([Literal][dfn-literal]) represents a fragment of raw [HTML][].

Html can be used where [flow][dfn-flow-content] or [phrasing][dfn-phrasing-content] content is expected. Its content is represented by its value field.

Html nodes do not have the restriction of being valid or complete HTML ([[HTML]][html]) constructs.

For example, the following markdown:

<div>

Yields:

{type: 'html', value: '<div>'}

Image

interface Image <: Node {
  type: 'image'
}

Image includes Resource
Image includes Alternative

Image ([Node][dfn-node]) represents an image.

Image can be used where [phrasing][dfn-phrasing-content] content is expected. It has no content model, but is described by its alt field.

Image includes the mixins [Resource][dfn-mxn-resource] and [Alternative][dfn-mxn-alternative].

For example, the following markdown:

![alpha](https://example.com/favicon.ico "bravo")

Yields:

{
  type: 'image',
  url: 'https://example.com/favicon.ico',
  title: 'bravo',
  alt: 'alpha'
}

ImageReference

interface ImageReference <: Node {
  type: 'imageReference'
}

ImageReference includes Reference
ImageReference includes Alternative

ImageReference ([Node][dfn-node]) represents an image through association, or its original source if there is no association.

ImageReference can be used where [phrasing][dfn-phrasing-content] content is expected. It has no content model, but is described by its alt field.

ImageReference includes the mixins [Reference][dfn-mxn-reference] and [Alternative][dfn-mxn-alternative].

ImageReference should be associated with a [Definition][dfn-definition].

For example, the following markdown:

![alpha][bravo]

Yields:

{
  type: 'imageReference',
  identifier: 'bravo',
  label: 'bravo',
  referenceType: 'full',
  alt: 'alpha'
}

InlineCode

interface InlineCode <: Literal {
  type: 'inlineCode'
}

InlineCode ([Literal][dfn-literal]) represents a fragment of computer code, such as a file name, computer program, or anything a computer could parse.

InlineCode can be used where [phrasing][dfn-phrasing-content] content is expected. Its content is represented by its value field.

T