ts-mdast - Typescript utilities for Markdown Abstract Syntax Tree

This package provides utilities to work with Markdown abstract syntax tree (MDAST). It contains:

• functions to create the different node types (also useful in pure Javascript);
• type guard and assertion functions to ensure the node is of expected type (especially useful with Typescript).

This package also re-export all types of @types/mdast and type of @types/unist which are useful for Markdown. It is therefore not necessary to include those packages if you are using this one.

Language/langue

Documents, messages, code (including variable names and comments), are in English.

Anyway, because Slune is French firm, all documents and important messages must also be provided in French. Other translations are welcome.

:fr: Une version française de ce document se trouve ici.

Installation

Installation is done using npm install command:

$ npm install --save ts-mdast

Usage

For each NodeType node type, the package contains :

• an assertNodeType(node: Node) function raising an exception if node is not of type NodeType ;
• an isNodeType(node: Node) function returning true if node is of type NodeType ;
• a createNodeType(...) function creating a node of type NodeType.

The first two functions are understood by Typescript which is after able to control the node type in an appropriate way.

The creation function is used this as following:

createNodeType(mandatory1, mandatory2 [, optional1 [, optional2 [, optional3]] | {optional1, optional2, optional3}] [, children])

where mandatory_ represent the mandatory parameters, optional_ the optional parameters and children an array with child nodes. Following calls are therefore possible:

createNodeType(mandatory1, mandatory2, optional1, [child1, child2])
createNodeType(mandatory1, mandatory2, optional1, optional2)
createNodeType(mandatory1, mandatory2, { optional1, optional3 })
createNodeType(mandatory1, mandatory2, { optional2, optional3 }, [child1, child2])
createNodeType(mandatory1, mandatory2, [child1, child2])

The array containing children is directly used in the node and can therefore be modified after node creation:

const children: Content[] = []
createNodeType(mandatory1, mandatory2, children)
children.push(createNodeType(mandatory1, mandatory2))

Notes:

• The createNodeType(...) function only exists for concrete nodes (not on Content nor BlockContent for example).
• All node types do not have mandatory parameters, optional parameters or child nodes.

Nodes

Parent

Reference: Parent

Type assertion:

function assertParent(node: Node): asserts node is Parent

Type guard:

function isParent(node: Node): node is Parent

Literal

Reference: Literal

Type assertion:

function assertLiteral(node: Node): asserts node is Literal

Type guard:

function isLiteral(node: Node): node is Literal

Content

Reference: Content

Type assertion:

function assertContent(node: Node): asserts node is Content

Type guard:

function isContent(node: Node): node is Content

TopLevelContent

Reference: TopLevelContent

Type assertion:

function assertTopLevelContent(node: Node): asserts node is TopLevelContent

Type guard:

function isTopLevelContent(node: Node): node is TopLevelContent

BlockContent

Reference: BlockContent

Type assertion:

function assertBlockContent(node: Node): asserts node is BlockContent

Type guard:

function isBlockContent(node: Node): node is BlockContent

FrontmatterContent

Reference: FrontmatterContent

Type assertion:

function assertFrontmatterContent(node: Node): asserts node is FrontmatterContent

Type guard:

function isFrontmatterContent(node: Node): node is FrontmatterContent

DefinitionContent

Reference: DefinitionContent

Type assertion:

function assertDefinitionContent(node: Node): asserts node is DefinitionContent

Type guard:

function isDefinitionContent(node: Node): node is DefinitionContent

ListContent

Reference: ListContent

Type assertion:

function assertListContent(node: Node): asserts node is ListContent

Type guard:

function isListContent(node: Node): node is ListContent

TableContent

Reference: TableContent

Type assertion:

function assertTableContent(node: Node): asserts node is TableContent

Type guard:

function isTableContent(node: Node): node is TableContent

RowContent

Reference: RowContent

Type assertion:

function assertRowContent(node: Node): asserts node is RowContent

Type guard:

function isRowContent(node: Node): node is RowContent

PhrasingContent

Reference: PhrasingContent

Type assertion:

function assertPhrasingContent(node: Node): asserts node is PhrasingContent

Type guard:

function isPhrasingContent(node: Node): node is PhrasingContent

StaticPhrasingContent

Reference: StaticPhrasingContent

Type assertion:

function assertStaticPhrasingContent(node: Node): asserts node is StaticPhrasingContent

Type guard:

function isStaticPhrasingContent(node: Node): node is StaticPhrasingContent

Root

Reference: Root

Type assertion:

function assertRoot(node: Node): asserts node is Root

Type guard:

function isRoot(node: Node): node is Root

Creation:

function createRoot(children?: Content[]): Root

Paragraph

Reference: Paragraph

Type assertion:

function assertParagraph(node: Node): asserts node is Paragraph

Type guard:

function isParagraph(node: Node): node is Paragraph

Creation:

function createParagraph(children?: PhrasingContent[]): Paragraph

Heading

Reference: Heading

Type assertion:

function assertHeading(node: Node): asserts node is Heading

Type guard:

function isHeading(node: Node): node is Heading

Creation:

function createHeading(depth: 1 | 2 | 3 | 4 | 5 | 6, children?: PhrasingContent[])

ThematicBreak

Reference: ThematicBreak

Type assertion:

function assertThematicBreak(node: Node): asserts node is ThematicBreak

Type guard:

function isThematicBreak(node: Node): node is ThematicBreak

Creation:

function createThematicBreak(): ThematicBreak

Blockquote

Reference: Blockquote

Type assertion:

function assertBlockquote(node: Node): asserts node is Blockquote

Type guard:

function isBlockquote(node: Node): node is Blockquote

Creation:

function createBlockquote(children?: BlockContent[]): Blockquote

List

Reference: List

Type assertion:

function assertList(node: Node): asserts node is List

Type guard:

function isList(node: Node): node is List

Creation:

function createList(ordered: boolean, start: number, spread: boolean, children?: ListContent[]): List
function createList(ordered: boolean, start: number, children?: ListContent[]): List
function createList(ordered: boolean, children?: ListContent[]): List
function createList(children?: ListContent[]): List
function createList(
  options: { ordered?: boolean; start?: number; spread?: boolean },
  children?: ListContent[]
): List

ListItem

Reference: ListItem

Type assertion:

function assertListItem(node: Node): asserts node is ListItem

Type guard:

function isListItem(node: Node): node is ListItem

Creation:

function createListItem(checked: boolean, spread: boolean, children?: BlockContent[]): ListItem
function createListItem(checked: boolean, children?: BlockContent[]): ListItem
function createListItem(children?: BlockContent[]): ListItem
function createListItem(
  options: { checked?: boolean; spread?: boolean },
  children?: BlockContent[]
): ListItem

Table

Reference: Table

Type assertion:

function assertTable(node: Node): asserts node is Table

Type guard:

function isTable(node: Node): node is Table

Creation:

function createTable(align: AlignType[], children?: TableContent[]): Table
function createTable(children?: TableContent[]): Table
function createTable(options: { align?: AlignType[] }, children?: TableContent[]): Table

TableRow

Reference: TableRow

Type assertion:

function assertTableRow(node: Node): asserts node is TableRow

Type guard:

function isTableRow(node: Node): node is TableRow

Creation:

function createTableRow(children?: RowContent[]): TableRow

TableCell

Reference: TableCell

Type assertion:

function assertTableCell(node: Node): asserts node is TableCell

Type guard:

function isTableCell(node: Node): node is TableCell

Creation:

function createTableCell(children?: PhrasingContent[]): TableCell

HTML

Reference: HTML

Type assertion:

function assertHTML(node: Node): asserts node is HTML

Type guard:

function isHTML(node: Node): node is HTML

Creation:

function createHTML(value: string): HTML

Code

Reference: Code

Type assertion:

function assertCode(node: Node): asserts node is Code

Type guard:

function isCode(node: Node): node is Code

Creation:

function createCode(value: string, lang?: string, meta?: string): Code
function createCode(value: string, options: { lang?: string; meta?: string }): Code

YAML

Reference: YAML

Type assertion:

function assertYAML(node: Node): asserts node is YAML

Type guard:

function isYAML(node: Node): node is YAML

Creation:

function createYAML(value: string): YAML

Definition

Reference: Definition

Type assertion:

function assertDefinition(node: Node): asserts node is Definition

Type guard:

function isDefinition(node: Node): node is Definition

Creation:

function createDefinition(identifier: string, url: string, label?: string, title?: string): Definition
function createDefinition(
  identifier: string,
  url: string,
  options: { label?: string; title?: string }
): Definition

FootnoteDefinition

Reference: FootnoteDefinition

Type assertion:

function assertFootnoteDefinition(node: Node): asserts node is FootnoteDefinition

Type guard:

function isFootnoteDefinition(node: Node): node is FootnoteDefinition

Creation:

function createFootnoteDefinition(
  identifier: string,
  label: string,
  children?: BlockContent[]
): FootnoteDefinition
function createFootnoteDefinition(identifier: string, children?: BlockContent[]): FootnoteDefinition
function createFootnoteDefinition(
  identifier: string,
  options: { label?: string },
  children?: BlockContent[]
): FootnoteDefinition

Text

Reference: Text

Type assertion:

function assertText(node: Node): asserts node is Text

Type guard:

function isText(node: Node): node is Text

Creation:

function createText(value: string): Text

Emphasis

Reference: Emphasis

Type assertion:

function assertEmphasis(node: Node): asserts node is Emphasis

Type guard:

function isEmphasis(node: Node): node is Emphasis

Creation:

function createEmphasis(children?: PhrasingContent[]): Emphasis

Strong

Reference: Strong

Type assertion:

function assertStrong(node: Node): asserts node is Strong

Type guard:

function isStrong(node: Node): node is Strong

Creation:

function createStrong(children?: PhrasingContent[]): Strong

Delete

Reference: Delete

Type assertion:

function assertDelete(node: Node): asserts node is Delete

Type guard:

function isDelete(node: Node): node is Delete

Creation:

function createDelete(children?: PhrasingContent[]): Delete

InlineCode

Reference: InlineCode

Type assertion:

function assertInlineCode(node: Node): asserts node is InlineCode

Type guard:

function isInlineCode(node: Node): node is InlineCode

Creation:

function createInlineCode(value: string): InlineCode

Break

Reference: Break

Type assertion:

function assertBreak(node: Node): asserts node is Break

Type guard:

function isBreak(node: Node): node is Break

Creation:

function createBreak(): Break

Link

Reference: Link

Type assertion:

function assertLink(node: Node): asserts node is Link

Type guard:

function isLink(node: Node): node is Link

Creation:

function createLink(url: string, title: string, children?: StaticPhrasingContent[]): Link
function createLink(url: string, children?: StaticPhrasingContent[]): Link
function createLink(url: string, options: { title?: string }, children?: StaticPhrasingContent[]): Link

Image

Reference: Image

Type assertion:

function assertImage(node: Node): asserts node is Image

Type guard:

function isImage(node: Node): node is Image

Creation:

function createImage(url: string, alt?: string, title?: string): Image
function createImage(url: string, options: { alt?: string; title?: string }): Image

LinkReference

Reference: LinkReference

Type assertion:

function assertLinkReference(node: Node): asserts node is LinkReference

Type guard:

function isLinkReference(node: Node): node is LinkReference

Creation:

function createLinkReference(
  identifier: string,
  referenceType: ReferenceType,
  label: string,
  children?: StaticPhrasingContent[]
): LinkReference
function createLinkReference(
  identifier: string,
  referenceType: ReferenceType,
  children?: StaticPhrasingContent[]
): LinkReference
function createLinkReference(
  identifier: string,
  referenceType: ReferenceType,
  options: { label?: string },
  children?: StaticPhrasingContent[]
): LinkReference

ImageReference

Reference: ImageReference

Type assertion:

function assertImageReference(node: Node): asserts node is ImageReference

Type guard:

function isImageReference(node: Node): node is ImageReference

Creation:

function createImageReference(
  identifier: string,
  referenceType: ReferenceType,
  alt?: string,
  label?: string
): ImageReference
function createImageReference(
  identifier: string,
  referenceType: ReferenceType,
  options: { alt?: string; label?: string }
): ImageReference

Footnote

Reference: Footnote

Type assertion:

function assertFootnote(node: Node): asserts node is Footnote

Type guard:

function isFootnote(node: Node): node is Footnote

Creation:

function createFootnote(children?: PhrasingContent[]): Footnote

FootnoteReference

Reference: FootnoteReference

Type assertion:

function assertFootnoteReference(node: Node): asserts node is FootnoteReference

Type guard:

function isFootnoteReference(node: Node): node is FootnoteReference

Creation:

function createFootnoteReference(identifier: string, label?: string): FootnoteReference
function createFootnoteReference(identifier: string, options: { label?: string }): FootnoteReference

Contributing

Even though we cannot guarantee a response time, please feel free to file an issue if you have any question or problem using the package.

Pull Requests are welcome. You can, of course, submit corrections or improvements for code, but do not hesitate to also improve documentation, even for small spell or grammar errors.