GitHub - syntax-tree/hast: Hypertext Abstract Syntax Tree format (original) (raw)

hast

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.4.0.

Contents

Introduction

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

Where this specification fits

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

hast relates to JavaScript in that it has anecosystem of utilitiesfor 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 rehypeprojects in that hast syntax trees are used throughout their ecosystems.

Virtual DOM

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

Types

If you are using TypeScript, you can use the hast types by installing them with npm:

Nodes (abstract)

Literal

interface Literal <: UnistLiteral { value: string }

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

Parent

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

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

Its content is limited to only other hast content.

Nodes

Comment

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

Comment (Literal) represents a Comment([DOM]).

For example, the following HTML:

Yields:

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

Doctype

interface Doctype <: Node { type: 'doctype' }

Doctype (Node) represents aDocumentType ([DOM]).

For example, the following HTML:

Yields:

Element

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

Element (Parent) represents an Element([DOM]).

A tagName field must be present. It represents the element’s local name([DOM]).

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_ ([HTML]).

For example, the following HTML:

Yields:

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

Root

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.

Text

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

Text (Literal) represents a Text([DOM]).

For example, the following HTML:

Yields:

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

Other types

Properties

Properties represents information associated with an element.

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

PropertyName

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 onhow ARIA is reflected in the DOM([ARIA]), 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 camelcased property name capitalizing 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 camelcased property name capitalizing 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
Exceptions

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 andhtmlFor in alignment with the DOM. No other attributes gain different names as properties, other than a change in casing.

Notes

property-information lists all property names.

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

View list of differences

PropertyValue

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 has strict rules on how it coerces HTML to expected values, whereas hast is more lenient in how it reflects the source. 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 plugins and utilities to inspect these non-standard values.

The DOM also specifies comma separated 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.

Glossary

See § Glossary in syntax-tree/unist.

List of utilities

See § List of utilities in syntax-tree/unistfor more utilities.

References

Security

As hast represents HTML, and improper use of HTML can open you up to across-site scripting (XSS) attack, improper use of hast is also unsafe. Always be careful with user input and usehast-util-santize to make the hast tree safe.

Contribute

See contributing.md insyntax-tree/.github for ways to get started. See support.md for ways to get help.

A curated list of awesome syntax-tree, unist, mdast, hast, xast, and nlcst resources can be found inawesome syntax-tree.

This project has a code of conduct. 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.

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

Thanks to@andrewburgess,@arobase-che,@arystan-sw,@BarryThePenguin,@brechtcs,@ChristianMurphy,@ChristopherBiscardi,@craftzdog,@cupojoe,@davidtheclark,@derhuerst,@detj,@DxCx,@erquhart,@flurmbo,@Hamms,@Hypercubed,@inklesspen,@jeffal,@jlevy,@Justineo,@lfittl,@kgryte,@kmck,@kthjm,@KyleAMathews,@macklinu,@medfreeman,@Murderlon,@nevik,@nokome,@phiresky,@revolunet,@rhysd,@Rokt33r,@rubys,@s1n,@Sarah-Seo,@sethvincent,@simov,@StarpTech,@stefanprobst,@stuff,@subhero24,@tripodsan,@tunnckoCore,@vhf,@voischev, and@zjaml, for contributing to hast and related projects!

License

CC-BY-4.0 © Titus Wormer