node package manager

mdast

MDAST

⚠️

mdast, the pluggable markdown parser, was recently separated from this project and given a new name: remark. See its documentation to read more about what changed and how to migrate »

Markdown Abstract Syntax Tree format.


MDAST discloses markdown as an abstract syntax tree. Abstract means not all information is stored in this tree and an exact replica of the original document cannot be re-created. Syntax Tree means syntax is present in the tree, thus an exact syntactic document can be re-created.

AST

Node

Node represents any unit in MDAST hierarchy.

interface Node {
    type: string;
    data: Data | null;
    position: Location?;
}

Location

Node can have a reference to its original location, if applicable. Start determines the line and column at which the original location starts; end, respectively; and indent the column at which further lines start.

interface Location {
    start: Position;
    end: Position;
    indent: [uint32 >= 1]
}

Position

A position contains a column and a line. Both start at 1.

interface Position {
    line: uint32 >= 1;
    column: uint32 >= 1;
}

Data

Data represents data associated with any node. Data is a scope for plug-ins to store any information. Its only limitation being that each property should by stringifyable: not throw when passed to JSON.stringify().

interface Data { }

Parent

Most nodes inherit the Parent (Node) interface: nodes which accept other nodes as children.

interface Parent <: Node {
    children: [Node];
}

Text

Most others inherit Text (Node): nodes which accept a value.

interface Text <: Node {
    value: string;
}

Root

Root (Parent) houses all nodes.

interface Root <: Parent {
    type: "root";
}

Paragraph

Paragraph (Parent) represents a unit of discourse dealing with a particular point or idea.

interface Paragraph <: Parent {
    type: "paragraph";
}

Blockquote

Blockquote (Parent) represents a quote.

interface Blockquote <: Parent {
    type: "blockquote";
}

Heading

Heading (Parent), just like with HTML, with a level greater than or equal to 1, lower than or equal to 6.

interface Heading <: Parent {
    type: "heading";
    depth: 1 <= uint32 <= 6;
}

Code

Code (Text) occurs at block level (see InlineCode for code spans). Code sports a language tag (when using GitHub Flavoured Markdown fences with a flag, null otherwise).

interface Code <: Text {
    type: "code";
    lang: string | null;
}

InlineCode

InlineCode (Text) occurs inline (see Code for blocks). Inline code does not sport a lang attribute.

interface InlineCode <: Text {
    type: "inlineCode";
}

YAML

YAML (Text) can occur at the start of a document, and contains embedded YAML data.

interface YAML <: Text {
    type: "yaml";
}

HTML

HTML (Text) contains embedded HTML.

interface HTML <: Text {
    type: "html";
}

List

List (Parent) contains ListItem’s.

The start property contains the starting number of the list when ordered: true; null otherwise.

When all list items have loose: false, the list’s loose property is also false. Otherwise, loose: true.

interface List <: Parent {
    type: "list";
    loose: true | false;
    start: uint32 | null;
    ordered: true | false;
}

ListItem

ListItem (Parent) is a child of a List.

Loose ListItem’s often contain more than one block-level elements.

When in gfm: true mode, a checked property exists on ListItem’s, either set to true (when checked), false (when unchecked), or null (when not containing a checkbox). See Task Lists on GitHub for information.

interface ListItem <: Parent {
    type: "listItem";
    loose: true | false;
    checked: true | false | null | undefined;
}

Table

Table (Parent) represents tabular data, with alignment. Its children are either TableHeader (the first child), or TableRow (all other children).

table.align represents the alignment of columns.

interface Table <: Parent {
    type: "table";
    align: [alignType];
}
enum alignType {
    "left" | "right" | "center" | null;
}

TableHeader

TableHeader (Parent). Its children are always TableCell.

interface TableHeader <: Parent {
    type: "tableHeader";
}

TableRow

TableRow (Parent). Its children are always TableCell.

interface TableRow <: Parent {
    type: "tableRow";
}

TableCell

TableCell (Parent). Contains a single tabular field.

interface TableCell <: Parent {
    type: "tableCell";
}

HorizontalRule

Just a HorizontalRule (Node).

interface HorizontalRule <: Node {
    type: "horizontalRule";
}

Break

Break (Node) represents an explicit line break.

interface Break <: Node {
    type: "break";
}

Emphasis

Emphasis (Parent) represents slightly important text.

interface Emphasis <: Parent {
    type: "emphasis";
}

Strong

Strong (Parent) represents super important text.

interface Strong <: Parent {
    type: "strong";
}

Delete

Delete (Parent) represents text ready for removal.

interface Delete <: Parent {
    type: "delete";
}

Link

Link (Parent) represents the humble hyperlink.

interface Link <: Parent {
    type: "link";
    title: string | null;
    href: string;
}

Image

Image (Node) represents the figurative figure.

interface Image <: Node {
    type: "image";
    title: string | null;
    alt: string | null;
    src: string;
}

Footnote

Footnote (Parent) represents an inline marker, whose content relates to the document but is outside its flow.

interface Footnote <: Parent {
    type: "footnote";
}

LinkReference

Link (Parent) represents a humble hyperlink, its href and title defined somewhere else in the document by a Definition.

interface LinkReference <: Parent {
    type: "linkReference";
    identifier: string;
}

ImageReference

Link (Node) represents a figurative figure, its src and title defined somewhere else in the document by a Definition.

interface ImageReference <: Node {
    type: "imageReference";
    alt: string | null;
    identifier: string;
}

FootnoteReference

FootnoteReference (Node) is like Footnote, but its content is already outside the documents flow: placed in a FootnoteDefinition.

interface FootnoteReference <: Node {
    type: "footnoteReference";
    identifier: string;
}

Definition

Definition (Node) represents the definition (i.e., location and title) of a LinkReference or an ImageReference.

interface Definition <: Node {
    type: "definition";
    identifier: string;
    title: string | null;
    link: string;
}

FootnoteDefinition

FootnoteDefinition (Parent) represents the definition (i.e., content) of a FootnoteReference.

interface FootnoteDefinition <: Parent {
    type: "footnoteDefinition";
    identifier: string;
}

TextNode

TextNode (Text) represents everything that is just text. Note that its type property is text, but it is different from Text.

interface TextNode <: Text {
    type: "text";
}

Related

License

MIT © Titus Wormer