Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/syntax-tree/mdast
Markdown Abstract Syntax Tree format
https://github.com/syntax-tree/mdast
ast markdown syntax-tree unist
Last synced: about 2 months ago
JSON representation
Markdown Abstract Syntax Tree format
- Host: GitHub
- URL: https://github.com/syntax-tree/mdast
- Owner: syntax-tree
- Created: 2015-12-24T23:12:36.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2023-06-28T15:52:36.000Z (about 1 year ago)
- Last Synced: 2024-07-23T05:08:05.312Z (about 2 months ago)
- Topics: ast, markdown, syntax-tree, unist
- Homepage: https://unifiedjs.com
- Size: 214 KB
- Stars: 1,038
- Watchers: 18
- Forks: 44
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
- awesome-syntax-tree - Find more utilities »
- awesome-remark - mdast - Abstract syntax tree specification. (Official)
README
# ![mdast][logo]
**M**ark**d**own **A**bstract **S**yntax **T**ree.
***
**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](#introduction)
* [Where this specification fits](#where-this-specification-fits)
* [Types](#types)
* [Nodes (abstract)](#nodes-abstract)
* [`Literal`](#literal)
* [`Parent`](#parent)
* [Nodes](#nodes)
* [`Blockquote`](#blockquote)
* [`Break`](#break)
* [`Code`](#code)
* [`Definition`](#definition)
* [`Emphasis`](#emphasis)
* [`Heading`](#heading)
* [`Html`](#html)
* [`Image`](#image)
* [`ImageReference`](#imagereference)
* [`InlineCode`](#inlinecode)
* [`Link`](#link)
* [`LinkReference`](#linkreference)
* [`List`](#list)
* [`ListItem`](#listitem)
* [`Paragraph`](#paragraph)
* [`Root`](#root)
* [`Strong`](#strong)
* [`Text`](#text)
* [`ThematicBreak`](#thematicbreak)
* [Mixin](#mixin)
* [`Alternative`](#alternative)
* [`Association`](#association)
* [`Reference`](#reference)
* [`Resource`](#resource)
* [Enumeration](#enumeration)
* [`referenceType`](#referencetype)
* [Content model](#content-model)
* [`Content`](#content)
* [`FlowContent`](#flowcontent)
* [`ListContent`](#listcontent)
* [`PhrasingContent`](#phrasingcontent)
* [Extensions](#extensions)
* [GFM](#gfm)
* [Frontmatter](#frontmatter)
* [MDX](#mdx)
* [Glossary](#glossary)
* [List of utilities](#list-of-utilities)
* [References](#references)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [Acknowledgments](#acknowledgments)
* [License](#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:
```sh
npm install @types/mdast
```
## Nodes (abstract)
### `Literal`
```idl
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`
```idl
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`
```idl
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:
```markdown
> Alpha bravo charlie.
```
Yields:
```js
{
type: 'blockquote',
children: [{
type: 'paragraph',
children: [{type: 'text', value: 'Alpha bravo charlie.'}]
}]
}
```
### `Break`
```idl
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:
```markdown
foo··
bar
```
Yields:
```js
{
type: 'paragraph',
children: [
{type: 'text', value: 'foo'},
{type: 'break'},
{type: 'text', value: 'bar'}
]
}
```
### `Code`
```idl
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:
```markdown
foo()
```
Yields:
```js
{
type: 'code',
lang: null,
meta: null,
value: 'foo()'
}
```
And the following markdown:
````markdown
```js highlight-line="2"
foo()
bar()
baz()
```
````
Yields:
```js
{
type: 'code',
lang: 'javascript',
meta: 'highlight-line="2"',
value: 'foo()\nbar()\nbaz()'
}
```
### `Definition`
```idl
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:
```markdown
[Alpha]: https://example.com
```
Yields:
```js
{
type: 'definition',
identifier: 'alpha',
label: 'Alpha',
url: 'https://example.com',
title: null
}
```
### `Emphasis`
```idl
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:
```markdown
*alpha* _bravo_
```
Yields:
```js
{
type: 'paragraph',
children: [
{
type: 'emphasis',
children: [{type: 'text', value: 'alpha'}]
},
{type: 'text', value: ' '},
{
type: 'emphasis',
children: [{type: 'text', value: 'bravo'}]
}
]
}
```
### `Heading`
```idl
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:
```markdown
# Alpha
```
Yields:
```js
{
type: 'heading',
depth: 1,
children: [{type: 'text', value: 'Alpha'}]
}
```
### `Html`
```idl
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:
```markdown
```
Yields:
```js
{type: 'html', value: '
'}
```
### `Image`
```idl
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:
```markdown
```
Yields:
```js
{
type: 'image',
url: 'https://example.com/favicon.ico',
title: 'bravo',
alt: 'alpha'
}
```
### `ImageReference`
```idl
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:
```markdown
![alpha][bravo]
```
Yields:
```js
{
type: 'imageReference',
identifier: 'bravo',
label: 'bravo',
referenceType: 'full',
alt: 'alpha'
}
```
### `InlineCode`
```idl
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.
This node relates to the [**flow**][dfn-flow-content] content concept
[**Code**][dfn-code].
For example, the following markdown:
```markdown
`foo()`
```
Yields:
```js
{type: 'inlineCode', value: 'foo()'}
```
### `Link`
```idl
interface Link <: Parent {
type: 'link'
children: [PhrasingContent]
}
Link includes Resource
```
**Link** ([**Parent**][dfn-parent]) represents a hyperlink.
**Link** can be used where [**phrasing**][dfn-phrasing-content] content is
expected.
Its content model is also [**phrasing**][dfn-phrasing-content] content.
**Link** includes the mixin [**Resource**][dfn-mxn-resource].
For example, the following markdown:
```markdown
[alpha](https://example.com "bravo")
```
Yields:
```js
{
type: 'link',
url: 'https://example.com',
title: 'bravo',
children: [{type: 'text', value: 'alpha'}]
}
```
### `LinkReference`
```idl
interface LinkReference <: Parent {
type: 'linkReference'
children: [PhrasingContent]
}
LinkReference includes Reference
```
**LinkReference** ([**Parent**][dfn-parent]) represents a hyperlink through
association, or its original source if there is no association.
**LinkReference** can be used where [**phrasing**][dfn-phrasing-content] content
is expected.
Its content model is also [**phrasing**][dfn-phrasing-content] content.
**LinkReference** includes the mixin [**Reference**][dfn-mxn-reference].
**LinkReferences** should be associated with a [**Definition**][dfn-definition].
For example, the following markdown:
```markdown
[alpha][Bravo]
```
Yields:
```js
{
type: 'linkReference',
identifier: 'bravo',
label: 'Bravo',
referenceType: 'full',
children: [{type: 'text', value: 'alpha'}]
}
```
### `List`
```idl
interface List <: Parent {
type: 'list'
ordered: boolean?
start: number?
spread: boolean?
children: [ListContent]
}
```
**List** ([**Parent**][dfn-parent]) represents a list of items.
**List** can be used where [**flow**][dfn-flow-content] content is expected.
Its content model is [**list**][dfn-list-content] content.
An `ordered` field can be present.
It represents that the items have been intentionally ordered (when `true`), or
that the order of items is not important (when `false` or not present).
A `start` field can be present.
It represents, when the `ordered` field is `true`, the starting number of the
list.
A `spread` field can be present.
It represents that one or more of its children are separated with a blank line
from its [siblings][term-sibling] (when `true`), or not (when `false` or not
present).
For example, the following markdown:
```markdown
1. foo
```
Yields:
```js
{
type: 'list',
ordered: true,
start: 1,
spread: false,
children: [{
type: 'listItem',
spread: false,
children: [{
type: 'paragraph',
children: [{type: 'text', value: 'foo'}]
}]
}]
}
```
### `ListItem`
```idl
interface ListItem <: Parent {
type: 'listItem'
spread: boolean?
children: [FlowContent]
}
```
**ListItem** ([**Parent**][dfn-parent]) represents an item in a
[**List**][dfn-list].
**ListItem** can be used where [**list**][dfn-list-content] content is expected.
Its content model is [**flow**][dfn-flow-content] content.
A `spread` field can be present.
It represents that the item contains two or more [*children*][term-child]
separated by a blank line (when `true`), or not (when `false` or not present).
For example, the following markdown:
```markdown
* bar
```
Yields:
```js
{
type: 'listItem',
spread: false,
children: [{
type: 'paragraph',
children: [{type: 'text', value: 'bar'}]
}]
}
```
### `Paragraph`
```idl
interface Paragraph <: Parent {
type: 'paragraph'
children: [PhrasingContent]
}
```
**Paragraph** ([**Parent**][dfn-parent]) represents a unit of discourse dealing
with a particular point or idea.
**Paragraph** can be used where [**content**][dfn-content] is expected.
Its content model is [**phrasing**][dfn-phrasing-content] content.
For example, the following markdown:
```markdown
Alpha bravo charlie.
```
Yields:
```js
{
type: 'paragraph',
children: [{type: 'text', value: 'Alpha bravo charlie.'}]
}
```
### `Root`
```idl
interface Root <: Parent {
type: 'root'
}
```
**Root** ([**Parent**][dfn-parent]) represents a document.
**Root** can be used as the [*root*][term-root] of a [*tree*][term-tree], never
as a [*child*][term-child].
Its content model is **not** limited to [**flow**][dfn-flow-content] content,
but instead can contain any [**mdast content**][dfn-mdast-content] with the
restriction that all content must be of the same category.
### `Strong`
```idl
interface Strong <: Parent {
type: 'strong'
children: [PhrasingContent]
}
```
**Strong** ([**Parent**][dfn-parent]) represents strong importance, seriousness,
or urgency for its contents.
**Strong** 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:
```markdown
**alpha** __bravo__
```
Yields:
```js
{
type: 'paragraph',
children: [
{
type: 'strong',
children: [{type: 'text', value: 'alpha'}]
},
{type: 'text', value: ' '},
{
type: 'strong',
children: [{type: 'text', value: 'bravo'}]
}
]
}
```
### `Text`
```idl
interface Text <: Literal {
type: 'text'
}
```
**Text** ([**Literal**][dfn-literal]) represents everything that is just text.
**Text** can be used where [**phrasing**][dfn-phrasing-content] content is
expected.
Its content is represented by its `value` field.
For example, the following markdown:
```markdown
Alpha bravo charlie.
```
Yields:
```js
{type: 'text', value: 'Alpha bravo charlie.'}
```
### `ThematicBreak`
```idl
interface ThematicBreak <: Node {
type: 'thematicBreak'
}
```
**ThematicBreak** ([**Node**][dfn-node]) represents a thematic break, such as a
scene change in a story, a transition to another topic, or a new document.
**ThematicBreak** can be used where [**flow**][dfn-flow-content] content is
expected.
It has no content model.
For example, the following markdown:
```markdown
***
```
Yields:
```js
{type: 'thematicBreak'}
```
## Mixin
### `Alternative`
```idl
interface mixin Alternative {
alt: string?
}
```
**Alternative** represents a node with a fallback
An `alt` field should be present.
It represents equivalent content for environments that cannot represent the
node as intended.
### `Association`
```idl
interface mixin Association {
identifier: string
label: string?
}
```
**Association** represents an internal relation from one node to another.
An `identifier` field must be present.
It can match another node.
`identifier` is a source value: character escapes and character references are
*not* parsed.
Its value must be normalized.
A `label` field can be present.
`label` is a string value: it works just like `title` on a link or a `lang` on
code: character escapes and character references are parsed.
To normalize a value, collapse markdown whitespace (`[\t\n\r ]+`) to a space,
trim the optional initial and/or final space, and perform case-folding.
Whether the value of `identifier` (or normalized `label` if there is no
`identifier`) is expected to be a unique identifier or not depends on the type
of node including the **Association**.
An example of this is that they should be unique on
[**Definition**][dfn-definition], whereas multiple
[**LinkReference**][dfn-link-reference]s can be non-unique to be associated with
one definition.
### `Reference`
```idl
interface mixin Reference {
referenceType: string
}
Reference includes Association
```
**Reference** represents a marker that is [**associated**][dfn-mxn-association]
to another node.
A `referenceType` field must be present.
Its value must be a [**referenceType**][dfn-enum-reference-type].
It represents the explicitness of the reference.
### `Resource`
```idl
interface mixin Resource {
url: string
title: string?
}
```
**Resource** represents a reference to resource.
A `url` field must be present.
It represents a URL to the referenced resource.
A `title` field can be present.
It represents advisory information for the resource, such as would be
appropriate for a tooltip.
## Enumeration
### `referenceType`
```idl
enum referenceType {
'shortcut' | 'collapsed' | 'full'
}
```
**referenceType** represents the explicitness of a reference.
* **shortcut**: the reference is implicit, its identifier inferred from its
content
* **collapsed**: the reference is explicit, its identifier inferred from its
content
* **full**: the reference is explicit, its identifier explicitly set
## Content model
```idl
type MdastContent = FlowContent | ListContent | PhrasingContent
```
Each node in mdast falls into one or more categories of **Content** that group
nodes with similar characteristics together.
### `Content`
```idl
type Content = Definition | Paragraph
```
**Content** represents runs of text that form definitions and paragraphs.
### `FlowContent`
```idl
type FlowContent =
Blockquote | Code | Heading | Html | List | ThematicBreak | Content
```
**Flow** content represent the sections of document.
### `ListContent`
```idl
type ListContent = ListItem
```
**List** content represent the items in a list.
### `PhrasingContent`
```idl
type PhrasingContent = Break | Emphasis | Html | Image | ImageReference
| InlineCode | Link | LinkReference | Strong | Text
```
**Phrasing** content represent the text in a document, and its markup.
## Extensions
Markdown syntax is often extended.
It is not a goal of this specification to list all possible extensions.
However, a short list of frequently used extensions are shown below.
### GFM
The following interfaces are found in [GitHub Flavored Markdown][gfm].
#### `Delete`
```idl
interface Delete <: Parent {
type: 'delete'
children: [PhrasingContent]
}
```
**Delete** ([**Parent**][dfn-parent]) represents contents that are no longer
accurate or no longer relevant.
**Delete** 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:
```markdown
~~alpha~~
```
Yields:
```js
{
type: 'delete',
children: [{type: 'text', value: 'alpha'}]
}
```
#### `ListItem` (GFM)
```idl
interface ListItemGfm <: ListItem {
checked: boolean?
}
```
In GFM, a `checked` field can be present.
It represents whether the item is done (when `true`), not done (when `false`),
or indeterminate or not applicable (when `null` or not present).
#### `FootnoteDefinition`
```idl
interface FootnoteDefinition <: Parent {
type: 'footnoteDefinition'
children: [FlowContent]
}
FootnoteDefinition includes Association
```
**FootnoteDefinition** ([**Parent**][dfn-parent]) represents content relating
to the document that is outside its flow.
**FootnoteDefinition** can be used where [**flow**][dfn-flow-content] content is
expected.
Its content model is also [**flow**][dfn-flow-content] content.
**FootnoteDefinition** includes the mixin
[**Association**][dfn-mxn-association].
**FootnoteDefinition** should be associated with
[**FootnoteReferences**][dfn-footnote-reference].
For example, the following markdown:
```markdown
[^alpha]: bravo and charlie.
```
Yields:
```js
{
type: 'footnoteDefinition',
identifier: 'alpha',
label: 'alpha',
children: [{
type: 'paragraph',
children: [{type: 'text', value: 'bravo and charlie.'}]
}]
}
```
#### `FootnoteReference`
```idl
interface FootnoteReference <: Node {
type: 'footnoteReference'
}
FootnoteReference includes Association
```
**FootnoteReference** ([**Node**][dfn-node]) represents a marker through
association.
**FootnoteReference** can be used where [**phrasing**][dfn-phrasing-content]
content is expected.
It has no content model.
**FootnoteReference** includes the mixin [**Association**][dfn-mxn-association].
**FootnoteReference** should be associated with a
[**FootnoteDefinition**][dfn-footnote-definition].
For example, the following markdown:
```markdown
[^alpha]
```
Yields:
```js
{
type: 'footnoteReference',
identifier: 'alpha',
label: 'alpha'
}
```
#### `Table`
```idl
interface Table <: Parent {
type: 'table'
align: [alignType]?
children: [TableContent]
}
```
**Table** ([**Parent**][dfn-parent]) represents two-dimensional data.
**Table** can be used where [**flow**][dfn-flow-content] content is expected.
Its content model is [**table**][dfn-table-content] content.
The [*head*][term-head] of the node represents the labels of the columns.
An `align` field can be present.
If present, it must be a list of [**alignType**s][dfn-enum-align-type].
It represents how cells in columns are aligned.
For example, the following markdown:
```markdown
| foo | bar |
| :-- | :-: |
| baz | qux |
```
Yields:
```js
{
type: 'table',
align: ['left', 'center'],
children: [
{
type: 'tableRow',
children: [
{
type: 'tableCell',
children: [{type: 'text', value: 'foo'}]
},
{
type: 'tableCell',
children: [{type: 'text', value: 'bar'}]
}
]
},
{
type: 'tableRow',
children: [
{
type: 'tableCell',
children: [{type: 'text', value: 'baz'}]
},
{
type: 'tableCell',
children: [{type: 'text', value: 'qux'}]
}
]
}
]
}
```
#### `TableCell`
```idl
interface TableCell <: Parent {
type: 'tableCell'
children: [PhrasingContent]
}
```
**TableCell** ([**Parent**][dfn-parent]) represents a header cell in a
[**Table**][dfn-table], if its parent is a [*head*][term-head], or a data
cell otherwise.
**TableCell** can be used where [**row**][dfn-row-content] content is expected.
Its content model is [**phrasing**][dfn-phrasing-content] content excluding
[**Break**][dfn-break] nodes.
For an example, see [**Table**][dfn-table].
#### `TableRow`
```idl
interface TableRow <: Parent {
type: 'tableRow'
children: [RowContent]
}
```
**TableRow** ([**Parent**][dfn-parent]) represents a row of cells in a table.
**TableRow** can be used where [**table**][dfn-table-content] content is
expected.
Its content model is [**row**][dfn-row-content] content.
If the node is a [*head*][term-head], it represents the labels of the columns
for its parent [**Table**][dfn-table].
For an example, see [**Table**][dfn-table].
#### `alignType`
```idl
enum alignType {
'left' | 'right' | 'center' | null
}
```
**alignType** represents how phrasing content is aligned
([\[CSSTEXT\]][css-text]).
* **`'left'`**: See the [`left`][css-left] value of the `text-align` CSS
property
* **`'right'`**: See the [`right`][css-right] value of the `text-align`
CSS property
* **`'center'`**: See the [`center`][css-center] value of the `text-align`
CSS property
* **`null`**: phrasing content is aligned as defined by the host environment
#### `FlowContent` (GFM)
```idl
type FlowContentGfm = FootnoteDefinition | Table | FlowContent
```
#### `ListContent` (GFM)
```idl
type ListContentGfm = ListItemGfm
```
#### `PhrasingContent` (GFM)
```idl
type PhrasingContentGfm = FootnoteReference | Delete | PhrasingContent
```
#### `RowContent`
```idl
type RowContent = TableCell
```
**Row** content represent the cells in a row.
#### `TableContent`
```idl
type TableContent = TableRow
```
**Table** content represent the rows in a table.
### Frontmatter
The following interfaces are found with YAML.
#### `Yaml`
```idl
interface Yaml <: Literal {
type: 'yaml'
}
```
**Yaml** ([**Literal**][dfn-literal]) represents a collection of metadata for
the document in the YAML ([\[YAML\]][yaml]) data serialisation language.
**Yaml** can be used where [**frontmatter**][dfn-frontmatter-content] content is
expected.
Its content is represented by its `value` field.
For example, the following markdown:
```markdown
---
foo: bar
---
```
Yields:
```js
{type: 'yaml', value: 'foo: bar'}
```
#### `FrontmatterContent`
```idl
type FrontmatterContent = Yaml
```
**Frontmatter** content represent out-of-band information about the document.
If frontmatter is present, it must be limited to one node in the
[*tree*][term-tree], and can only exist as a [*head*][term-head].
#### `FlowContent` (frontmatter)
```idl
type FlowContentFrontmatter = FrontmatterContent | FlowContent
```
### MDX
See [`remark-mdx`](https://mdxjs.com/packages/remark-mdx/#syntax-tree).
## Glossary
See the [unist glossary][glossary].
## List of utilities
See the [unist list of utilities][utilities] for more utilities.
* [`mdast-add-list-metadata`](https://gitlab.com/staltz/mdast-add-list-metadata)
— enhance the metadata of `list` and `listItem` nodes
* [`mdast-util-assert`](https://github.com/syntax-tree/mdast-util-assert)
— assert nodes
* [`mdast-builder`](https://github.com/mike-north/mdast-builder)
— build mdast structures with composable functions
* [`mdast-comment-marker`](https://github.com/syntax-tree/mdast-comment-marker)
— parse a comment marker
* [`mdast-util-compact`](https://github.com/syntax-tree/mdast-util-compact)
— make a tree compact
* [`mdast-util-definitions`](https://github.com/syntax-tree/mdast-util-definitions)
— find definition nodes
* [`mdast-util-directive`](https://github.com/syntax-tree/mdast-util-directive)
— parse and serialize directives
* [`mdast-util-find-and-replace`](https://github.com/syntax-tree/mdast-util-find-and-replace)
— find and replace text
* [`mdast-flatten-image-paragraphs`](https://gitlab.com/staltz/mdast-flatten-image-paragraphs)
— flatten `paragraph` and `image` into one `image` node
* [`mdast-flatten-listitem-paragraphs`](https://gitlab.com/staltz/mdast-flatten-listitem-paragraphs)
— flatten `listItem` and (nested) paragraph into one listItem node
* [`mdast-flatten-nested-lists`](https://gitlab.com/staltz/mdast-flatten-nested-lists)
— transform a tree to avoid lists in lists
* [`mdast-util-from-adf`](https://github.com/bitcrowd/mdast-util-from-adf)
— build mdast syntax tree from Atlassian Document Format (ADF)
* [`mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown)
— parse markdown
* [`mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-frontmatter)
— parse and serialize frontmatter
* [`mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm)
— parse and serialize GFM
* [`mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal)
— parse and serialize GFM autolink literals
* [`mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote)
— parse and serialize GFM footnotes
* [`mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough)
— parse and serialize GFM strikethrough
* [`mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table)
— parse and serialize GFM tables
* [`mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item)
— parse and serialize GFM task list items
* [`mdast-util-gridtables`](https://github.com/syntax-tree/mdast-util-gridtables)
— parse and serialize gridtables
* [`mdast-util-heading-range`](https://github.com/syntax-tree/mdast-util-heading-range)
— markdown heading as ranges
* [`mdast-util-heading-style`](https://github.com/syntax-tree/mdast-util-heading-style)
— get the style of a heading node
* [`mdast-util-hidden`](https://github.com/Xunnamius/unified-utils/tree/main/packages/mdast-util-hidden)
— prevent nodes from being seen by transformers.
* [`mdast-util-math`](https://github.com/syntax-tree/mdast-util-math)
— parse and serialize math
* [`mdast-util-mdx`](https://github.com/syntax-tree/mdast-util-mdx)
— parse and serialize MDX
* [`mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression)
— parse and serialize MDX expressions
* [`mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx)
— parse and serialize MDX JSX
* [`mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm)
— parse and serialize MDX ESM
* [`mdast-move-images-to-root`](https://gitlab.com/staltz/mdast-move-images-to-root)
— move image nodes up the tree until they are direct children of the root
* [`mdast-normalize-headings`](https://github.com/syntax-tree/mdast-normalize-headings)
— ensure at most one top-level heading is in the document
* [`mdast-util-phrasing`](https://github.com/syntax-tree/mdast-util-phrasing)
— check if a node is phrasing content
* [`mdast-squeeze-paragraphs`](https://github.com/syntax-tree/mdast-squeeze-paragraphs)
— remove empty paragraphs
* [`mdast-util-toc`](https://github.com/syntax-tree/mdast-util-toc)
— generate a table of contents from a tree
* [`mdast-util-to-hast`](https://github.com/syntax-tree/mdast-util-to-hast)
— transform to hast
* [`mdast-util-to-markdown`](https://github.com/syntax-tree/mdast-util-to-markdown)
— serialize markdown
* [`mdast-util-to-nlcst`](https://github.com/syntax-tree/mdast-util-to-nlcst)
— transform to nlcst
* [`mdast-util-to-string`](https://github.com/syntax-tree/mdast-util-to-string)
— get the plain text content of a node
* [`mdast-zone`](https://github.com/syntax-tree/mdast-zone)
— HTML comments as ranges or markers
## References
* **unist**:
[Universal Syntax Tree][unist].
T. Wormer; et al.
* **Markdown**:
[Markdown][].
J. Gruber.
* **CommonMark**:
[CommonMark][].
J. MacFarlane; et al.
* **GFM**:
[GitHub Flavored Markdown][gfm].
GitHub.
* **HTML**:
[HTML Standard][html],
A. van Kesteren; et al.
WHATWG.
* **CSSTEXT**:
[CSS Text][css-text],
CSS Text, E. Etemad, K. Ishii.
W3C.
* **JavaScript**:
[ECMAScript Language Specification][javascript].
Ecma International.
* **YAML**:
[YAML Ain’t Markup Language][yaml],
O. Ben-Kiki, C. Evans, I. döt Net.
* **Web IDL**:
[Web IDL][webidl],
C. McCormack.
W3C.
## Security
As mdast can contain HTML and be used to represent HTML, and improper use of
HTML can open you up to a [cross-site scripting (XSS)][xss] attack, improper use
of mdast is also unsafe.
When transforming to HTML (typically through [**hast**][hast]), always be
careful with user input and use [`hast-util-santize`][sanitize] to make the hast
tree safe.
## Related
* [hast](https://github.com/syntax-tree/hast)
— Hypertext Abstract Syntax Tree format
* [nlcst](https://github.com/syntax-tree/nlcst)
— Natural Language Concrete Syntax Tree format
* [xast](https://github.com/syntax-tree/xast)
— Extensible Abstract Syntax Tree
## Contribute
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.
Ideas for new utilities and tools can be posted in [`syntax-tree/ideas`][ideas].
A curated list of awesome syntax-tree, unist, mdast, hast, xast, and nlcst
resources can be found in [awesome syntax-tree][awesome].
This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.
## Acknowledgments
The initial release of this project was authored by
[**@wooorm**](https://github.com/wooorm).
Special thanks to [**@eush77**](https://github.com/eush77) for their work,
ideas, and incredibly valuable feedback!
Thanks to
[**@anandthakker**](https://github.com/anandthakker),
[**@arobase-che**](https://github.com/arobase-che),
[**@BarryThePenguin**](https://github.com/BarryThePenguin),
[**@chinesedfan**](https://github.com/chinesedfan),
[**@ChristianMurphy**](https://github.com/ChristianMurphy),
[**@craftzdog**](https://github.com/craftzdog),
[**@d4rekanguok**](https://github.com/d4rekanguok),
[**@detj**](https://github.com/detj),
[**@dominictarr**](https://github.com/dominictarr),
[**@gkatsev**](https://github.com/gkatsev),
[**@Hamms**](https://github.com/Hamms),
[**@Hypercubed**](https://github.com/Hypercubed),
[**@ikatyang**](https://github.com/ikatyang),
[**@izumin5210**](https://github.com/izumin5210),
[**@jasonLaster**](https://github.com/jasonLaster),
[**@Justineo**](https://github.com/Justineo),
[**@justjake**](https://github.com/justjake),
[**@KyleAMathews**](https://github.com/KyleAMathews),
[**@laysent**](https://github.com/laysent),
[**@macklinu**](https://github.com/macklinu),
[**@mike-north**](https://github.com/mike-north),
[**@Murderlon**](https://github.com/Murderlon),
[**@nevik**](https://github.com/nevik),
[**@Rokt33r**](https://github.com/Rokt33r),
[**@rhysd**](https://github.com/rhysd),
[**@rubys**](https://github.com/rubys),
[**@Sarah-Seo**](https://github.com/Sarah-Seo),
[**@sethvincent**](https://github.com/sethvincent),
[**@silvenon**](https://github.com/silvenon),
[**@simov**](https://github.com/simov),
[**@staltz**](https://github.com/staltz),
[**@stefanprobst**](https://github.com/stefanprobst),
[**@tmcw**](https://github.com/tmcw),
and [**@vhf**](https://github.com/vhf)
for contributing to mdast and related
projects!
## License
[CC-BY-4.0][license] © [Titus Wormer][author]
[health]: https://github.com/syntax-tree/.github
[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
[awesome]: https://github.com/syntax-tree/awesome-syntax-tree
[ideas]: https://github.com/syntax-tree/ideas
[license]: https://creativecommons.org/licenses/by/4.0/
[author]: https://wooorm.com
[logo]: https://raw.githubusercontent.com/syntax-tree/mdast/e6b43aa/logo.svg?sanitize=true
[releases]: https://github.com/syntax-tree/mdast/releases
[latest]: https://github.com/syntax-tree/mdast/releases/tag/5.0.0
[dfn-node]: https://github.com/syntax-tree/unist#node
[dfn-unist-parent]: https://github.com/syntax-tree/unist#parent
[dfn-unist-literal]: https://github.com/syntax-tree/unist#literal
[dfn-parent]: #parent
[dfn-literal]: #literal
[dfn-code]: #code
[dfn-inline-code]: #inlinecode
[dfn-list]: #list
[dfn-table]: #table
[dfn-break]: #break
[dfn-link-reference]: #linkreference
[dfn-image-reference]: #imagereference
[dfn-footnote-reference]: #footnotereference
[dfn-definition]: #definition
[dfn-footnote-definition]: #footnotedefinition
[term-tree]: https://github.com/syntax-tree/unist#tree
[term-child]: https://github.com/syntax-tree/unist#child
[term-sibling]: https://github.com/syntax-tree/unist#sibling
[term-root]: https://github.com/syntax-tree/unist#root
[term-head]: https://github.com/syntax-tree/unist#head
[dfn-mxn-resource]: #resource
[dfn-mxn-association]: #association
[dfn-mxn-reference]: #reference
[dfn-mxn-alternative]: #alternative
[dfn-enum-align-type]: #aligntype
[dfn-enum-reference-type]: #referencetype
[dfn-mdast-content]: #content-model
[dfn-flow-content]: #flowcontent
[dfn-frontmatter-content]: #frontmattercontent
[dfn-content]: #content
[dfn-list-content]: #listcontent
[dfn-table-content]: #tablecontent
[dfn-row-content]: #rowcontent
[dfn-phrasing-content]: #phrasingcontent
[list-of-utilities]: #list-of-utilities
[unist]: https://github.com/syntax-tree/unist
[syntax-tree]: https://github.com/syntax-tree/unist#syntax-tree
[yaml]: https://yaml.org
[html]: https://html.spec.whatwg.org/multipage/
[css-text]: https://drafts.csswg.org/css-text/
[css-left]: https://drafts.csswg.org/css-text/#valdef-text-align-left
[css-right]: https://drafts.csswg.org/css-text/#valdef-text-align-right
[css-center]: https://drafts.csswg.org/css-text/#valdef-text-align-center
[javascript]: https://www.ecma-international.org/ecma-262/9.0/index.html
[webidl]: https://heycam.github.io/webidl/
[markdown]: https://daringfireball.net/projects/markdown/
[commonmark]: https://commonmark.org
[gfm]: https://github.github.com/gfm/
[glossary]: https://github.com/syntax-tree/unist#glossary
[utilities]: https://github.com/syntax-tree/unist#list-of-utilities
[unified]: https://github.com/unifiedjs/unified
[remark]: https://github.com/remarkjs/remark
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[hast]: https://github.com/syntax-tree/hast
[sanitize]: https://github.com/syntax-tree/hast-util-sanitize