DOCSEARCHbyAlgolia
Submit Docs

mdast

repository·main·Indexed 23 days ago

https://github.com/syntax-tree/mdast

A language-agnostic specification for representing Markdown as an abstract syntax tree (AST). Part of the unist ecosystem and the foundational data structure for the remark and unified projects, mdast supports various Markdown flavors including CommonMark and GitHub Flavored Markdown (GFM). It defines nodes for elements such as blockquotes, headings, lists, and images, and provides a wide range of utilities for parsing, serialization, transformation, and manipulation.

Tokens
3.4K
Snippets
23
Records
27
Agent score
31%

What's inside mdast

  1. What is mdast?

    main
    mdast (Markdown Abstract Syntax Tree) is a specification for representing Markdown as a syntax tree. It implements the unist format and is designed to represent various flavors of Markdown, including CommonMark and GitHub Flavored Markdown (GFM). While it has a rich ecosystem of utilities in JavaScript (via the unified and remark projects), the specification is language-agnostic and can be used in other programming languages.

  2. Related syntax-tree formats

    main

    mdast is part of a larger ecosystem of syntax tree formats:

    • hast: Hypertext Abstract Syntax Tree format (for HTML).
    • nlcst: Natural Language Concrete Syntax Tree format.
    • xast: Extensible Abstract Syntax Tree format.

  4. Prevent XSS when transforming mdast to HTML

    main

    Because mdast can contain HTML, improper use can lead to Cross-Site Scripting (XSS) attacks. When transforming an mdast tree to HTML (typically via hast), you must sanitize the resulting tree.

    Always use hast-util-sanitize to ensure the generated HTML is safe from malicious user input.

  5. Use YAML Frontmatter

    main

    Frontmatter represents out-of-band metadata for the document, typically using YAML. It must be limited to one node in the tree and can only exist as a head.

    Yaml

    • Content Model: FrontmatterContent (which is just Yaml).
    • value: The YAML data as a string.

    Example markdown:

    ---
foo: bar
---

    Yields:

    {type: 'yaml', value: 'foo: bar'}

  6. List of mdast utilities

    main

    A wide range of utilities exists to parse, serialize, transform, and manipulate mdast trees. Key categories include:

    • Parsing & Serialization: mdast-util-from-markdown (parse markdown), mdast-util-to-markdown (serialize markdown), mdast-util-frontmatter (frontmatter), mdast-util-gfm (GFM), mdast-util-mdx (MDX), and mdast-util-math (math).
    • Transformation: mdast-util-to-hast (transform to HTML AST), mdast-util-to-nlcst (transform to natural language AST), mdast-util-toc (generate table of contents), and mdast-util-compact (compact trees).
    • Manipulation: mdast-util-find-and-replace (text replacement), mdast-util-definitions (find definition nodes), and mdast-squeeze-paragraphs (remove empty paragraphs).
    • Validation: mdast-util-assert (assert nodes) and mdast-util-phrasing (check phrasing content).
    • Specialized Formats: mdast-util-from-adf (Atlassian Document Format) and mdast-util-gridtables (gridtables).

  7. The Literal interface

    main

    The Literal interface is an abstract interface in mdast that represents a node containing a raw value. It extends UnistLiteral.

    Properties:

    • value: A string representing the literal content.
    interface Literal <: UnistLiteral {
  value: string
}

  8. Represent the document root in mdast

    main

    A Root node represents the entire document. It is a Parent node that serves as the root of a tree and cannot be a child of another node. Its content can be any mdast content as long as all content belongs to the same category.

    interface Root <: Parent {
  type: 'root'
}

  9. Represent lists in mdast

    main

    A List node represents a list of items. It is a Parent node containing ListContent.

    Key properties:

    • ordered: boolean. If true, the list is intentionally ordered.
    • start: number. If ordered is true, this is the starting number.
    • spread: boolean. If true, one or more children are separated from siblings by a blank line.

    Example markdown:

    1. foo

    Yields:

    {
  type: 'list',
  ordered: true,
  start: 1,
  spread: false,
  children: [{
    type: 'listItem',
    spread: false,
    children: [{
      type: 'paragraph',
      children: [{type: 'text', value: 'foo'}]
    }]
  }]
}
    interface List <: Parent {
  type: 'list'
  ordered: boolean?
  start: number?
  spread: boolean?
  children: [ListContent]
}

  10. Represent image references in mdast

    main

    An ImageReference node represents an image through association (referencing a Definition) or its original source. It is a Node that includes the Reference and Alternative mixins and is described by its alt field.

    Example markdown:

    ![alpha][bravo]

    Yields:

    {
  type: 'imageReference',
  identifier: 'bravo',
  label: 'bravo',
  referenceType: 'full',
  alt: 'alpha'
}
    interface ImageReference <: Node {
  type: 'imageReference'
}

ImageReference includes Reference
ImageReference includes Alternative

  11. Represent raw HTML in mdast

    main

    An Html node represents a fragment of raw HTML. It is a Literal node where the content is stored in the value field. These nodes do not need to be valid or complete HTML constructs.

    Example markdown:

    <div>

    Yields:

    {type: 'html', value: '<div>'}
    interface Html <: Literal {
  type: 'html'
}

  12. Represent line breaks in mdast

    main

    A Break node represents a line break (e.g., in poems or addresses). It is a Node used where phrasing content is expected and has no content model.

    Example markdown:

    foo··
bar

    Yields:

    {
  type: 'paragraph',
  children: [
    {type: 'text', value: 'foo'},
    {type: 'break'},
    {type: 'text', value: 'bar'}
  ]
}
    interface Break <: Node {
  type: 'break'
}