Hypertext Abstract Syntax Tree format.

hast is a specification for representing HTML (and embedded SVG or MathML) as an abstract syntax tree. It implements the unist spec.

This document may not be released. See releases for released documents. The latest released version is 2.3.0.

• Introduction
  • Where this specification fits
  • Virtual DOM
• Nodes
  • Parent
  • Literal
  • Root
  • Element
  • Doctype
  • Comment
  • Text
• Glossary
• List of Utilities
• Related HTML Utilities
• References
• Contribute
• Acknowledgments
• License

This document defines a format for representing hypertext as an abstract syntax tree. Development of hast started in April 2016 for rehype. This specification is written in a Web IDL-like grammar.

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

hast relates to JavaScript in that it has an ecosystem of utilities for working with compliant syntax trees in JavaScript. However, hast is not limited to JavaScript and can be used in other programming languages.

hast relates to the unified and rehype projects in that hast syntax trees are used throughout their ecosystems.

The reason for introducing a new “virtual” DOM is primarily:

• The DOM is very heavy to implement outside of the browser, a lean and stripped down virtual DOM can be used everywhere
• Most virtual DOMs do not focus on ease of use in transformations
• Other virtual DOMs cannot represent the syntax of HTML in its entirety (think comments and document types)
• Neither HTML nor virtual DOMs focus on positional information

interface Parent <: UnistParent {
  children: [Element | Doctype | Comment | Text]
}

Parent (UnistParent) represents a node in hast containing other nodes (said to be children).

Its content is limited to only other hast content.

interface Literal <: UnistLiteral {
  value: string
}

Literal (UnistLiteral) represents a node in hast containing a value.

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

Root (Parent) represents a document.

Root can be used as the root of a tree, or as a value of the content field on a 'template' Element, never as a child.

interface Element <: Parent {
  type: "element"
  tagName: string
  properties: Properties?
  content: Root?
  children: [Element | Comment | Text]
}

Element (Parent) represents an HTML Element.

A tagName field must be present. It represents the element’s local name.

The properties field represents information associated with the element. The value of the properties field implements the Properties interface.

If the tagName field is 'template', a content field can be present. The value of the content field implements the Root interface.

If the tagName field is 'template', the element must be a leaf.

If the tagName field is 'noscript', its children should be represented as if scripting is disabled.

For example, the following HTML:

<a href="http://alpha.com" class="bravo" download></a>

Yields:

{
  type: 'element',
  tagName: 'a',
  properties: {
    href: 'http://alpha.com',
    id: 'bravo',
    className: ['bravo'],
    download: true
  },
  children: []
}

interface Properties {}

Properties represents information associated with an element.

Every field must be a PropertyName and every value a PropertyValue.

typedef string PropertyName

Property names are keys on Properties objects and reflect HTML, SVG, ARIA, XML, XMLNS, or XLink attribute names. Often, they have the same value as the corresponding attribute (for example, id is a property name reflecting the id attribute name), but there are some notable differences.

These rules aren’t simple. Use hastscript (or property-information directly) to help.

The following rules are used to transform HTML attribute names to property names. These rules are based on how ARIA is reflected in the DOM, and differs from how some (older) HTML attributes are reflected in the DOM.

1. Any name referencing a combinations of multiple words (such as “stroke miter limit”) becomes a camel-cased property name capitalising each word boundary. This includes combinations that are sometimes written as several words. For example, stroke-miterlimit becomes strokeMiterLimit, autocorrect becomes autoCorrect, and allowfullscreen becomes allowFullScreen.
2. Any name that can be hyphenated, becomes a camel-cased property name capitalising each boundary. For example, “read-only” becomes readOnly.
3. Compound words that are not used with spaces or hyphens are treated as a normal word and the previous rules apply. For example, “placeholder”, “strikethrough”, and “playback” stay the same.
4. Acronyms in names are treated as a normal word and the previous rules apply. For example, itemid become itemId and bgcolor becomes bgColor.

Some jargon is seen as one word even though it may not be seen as such by dictionaries. For example, nohref becomes noHref, playsinline becomes playsInline, and accept-charset becomes acceptCharset.

The HTML attributes class and for respectively become className and htmlFor in alignment with the DOM. No other attributes gain different names as properties, other than a change in casing.

The property name rules differ from how HTML is reflected in the DOM for the following attributes:

typedef any PropertyValue

Property values should reflect the data type determined by their property name. For example, the HTML <div hidden></div> has a hidden attribute, which is reflected as a hidden property name set to the property value true, and <input minlength="5">, which has a minlength attribute, is reflected as a minLength property name set to the property value 5.

In JSON, the value null must be treated as if the property was not included. In JavaScript, both null and undefined must be similarly ignored.

The DOM is strict in reflecting HTML and hast is not. Where the DOM treats <div hidden=no></div> as having a value of true and <img width="yes"> as having a value of 0, these should be reflected as 'no' and 'yes', respectively, in hast.

The reason for this is to allow plug-ins and utilities to inspect these non-standard values.

The DOM also specifies comma- and space-separated lists attribute values. In hast, these should be treated as ordered lists. For example, <div class="alpha bravo"></div> is represented as ['alpha', 'bravo'].

There’s no special format for the property value of the style property name.

interface Doctype <: Node {
  type: "doctype"
  name: string
  public: string?
  system: string?
}

Doctype (Node) represents an HTML DocumentType.

A name field must be present.

A public field can be present. If present, it must be set to a string, and represents the document’s public identifier.

A system field can be present. If system, it must be set to a string, and represents the document’s system identifier.

For example, the following HTML:

<!doctype html>

Yields:

{
  type: 'doctype',
  name: 'html',
  public: null,
  system: null
}

interface Comment <: Literal {
  type: "comment"
}

Comment (Literal) represents an HTML Comment.

For example, the following HTML:

<!--Charlie-->

Yields:

{
  type: 'comment',
  value: 'Charlie'
}

interface Text <: Literal {
  type: "text"
}

Text (Literal) represents an HTML Text.

For example, the following HTML:

<span>Foxtrot</span>

Yields:

{
  type: 'element',
  tagName: 'span',
  properties: {},
  children: [{type: 'text', value: 'Foxtrot'}]
}

See the unist glossary.

See the unist list of utilities for more utilities.

• hastscript — Hyperscript compatible DSL for creating nodes
• hast-to-hyperscript — Convert a Node to React, Virtual DOM, Hyperscript, and more
• hast-util-assert — Assert HAST nodes
• hast-util-class-list — Simulate the browser’s classList API for HAST nodes
• hast-util-embedded — Check if node is embedded content
• hast-util-find-and-replace — Find and replace text
• hast-util-from-parse5 — Transform Parse5’s AST to HAST
• hast-util-from-string — Set the plain-text value of a node
• hast-util-from-webparser — Transform Webparser’s AST to HAST
• hast-util-has-property — Check if a node has a property
• hast-util-heading — Check if a node is heading content
• hast-util-interactive — Check if a node is interactive
• hast-util-is-body-ok-link — Check if a link element is “Body OK”
• hast-util-is-conditional-comment — Check if node is a conditional comment
• hast-util-is-css-link — Check if node is a CSS link
• hast-util-is-css-style — Check if node is a CSS style
• hast-util-is-element — Check if node is a (certain) element
• hast-util-is-event-handler — Check if property is an event handler
• hast-util-is-javascript — Check if node is a JavaScript script
• hast-util-labelable — Check if node is labelable
• hast-util-menu-state — Check the state of a menu element
• hast-util-parse-selector — Create an element from a simple CSS selector
• hast-util-phrasing — Check if a node is phrasing content
• hast-util-raw — Reparse a HAST tree
• hast-util-sanitize — Sanitise nodes
• hast-util-select — querySelector, querySelectorAll, and matches
• hast-util-script-supporting — Check if node is script-supporting content
• hast-util-sectioning — Check if node is sectioning content
• hast-util-table-cell-style — Transform deprecated styling attributes on table cells to inline styles
• hast-util-to-html — Stringify nodes to HTML
• hast-util-to-mdast — Transform HAST to MDAST
• hast-util-to-nlcst — Transform HAST to NLCST
• hast-util-to-parse5 — Transform HAST to Parse5’s AST
• hast-util-to-string — Get the plain-text value of a node
• hast-util-transparent — Check if node is transparent content
• hast-util-whitespace — Check if node is inter-element whitespace

• a-rel — List of link types for rel on a / area
• aria-attributes — List of ARIA attributes
• collapse-white-space — Replace multiple white-space characters with a single space
• comma-separated-tokens — Parse/stringify comma-separated tokens
• html-tag-names — List of HTML tag-names
• html-dangerous-encodings — List of dangerous HTML character encoding labels
• html-encodings — List of HTML character encoding labels
• html-element-attributes — Map of HTML attributes
• html-void-elements — List of void HTML tag-names
• link-rel — List of link types for rel on link
• mathml-tag-names — List of MathML tag-names
• meta-name — List of values for name on meta
• property-information — Information on HTML properties
• space-separated-tokens — Parse/stringify space-separated tokens
• svg-tag-names — List of SVG tag-names
• svg-element-attributes — Map of SVG attributes
• web-namespaces — Map of web namespaces

• unist: Universal Syntax Tree. T. Wormer; et al.
• JavaScript ECMAScript Language Specification. Ecma International.
• HTML: HTML Standard, A. van Kesteren; et al. WHATWG.
• SVG: Scalable Vector Graphics (SVG), N. Andronikos, R. Atanassov, T. Bah, B. Birtles, B. Brinza, C. Concolato, E. Dahlström, C. Lilley, C. McCormack, D. Schepers, R. Schwerdtfeger, D. Storey, S. Takagi, J. Watt. W3C.
• MathML: Mathematical Markup Language Standard, D. Carlisle, P. Ion, R. Miner. W3C.
• ARIA: Accessible Rich Internet Applications (WAI-ARIA), J. Diggs, J. Craig, S. McCarron, M. Cooper. W3C.
• JSON The JavaScript Object Notation (JSON) Data Interchange Format, T. Bray. IETF.
• Web IDL: Web IDL, C. McCormack. W3C.

hast is built by people just like you! Check out contributing.md for ways to get started.

This project has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.

Want to chat with the community and contributors? Join us in Gitter!

Have an idea for a cool new utility or tool? That’s great! If you want feedback, help, or just to share it with the world you can do so by creating an issue in the syntax-tree/ideas repository!

The initial release of this project was authored by @wooorm.

Special thanks to @eush77 for their work, ideas, and incredibly valuable feedback!

Thanks to @kthjm @KyleAMathews, @rhysd, @Rokt33r, @s1n, @Sarah-Seo, @sethvincent, and @simov for contributing to hast and related projects!

CC-BY-4.0 © Titus Wormer