Universal Syntax Tree.
Unist is the combination of three syntax trees, and more to come: mdast with remark for markdown, nlcst with retext for prose, and hast with rehype for HTML.
This document explains some terminology relating to unified and vfile as well.
This document may not be released. See releases for released
documents. The latest released version is 1.1.0.
Subsets of Unist can define new properties on new nodes, and plug-ins
and utilities can define new data properties on nodes. But,
the values on those properties must be JSON values: string,
number, object, array, true, false, or null. This means
that the syntax tree should be able to be converted to and from JSON
and produce the same tree. For example, in JavaScript, a tree should
be able to be passed through JSON.parse(JSON.stringify(tree)) and
result in the same values.
See nlcst for more information on retext nodes, mdast for information on remark nodes, and hast for information on rehype nodes.
A Node represents any unit in the Unist hierarchy. It is an abstract
interface. Interfaces extending Node must have a type property,
and may have data or position properties. types are defined by
their namespace.
Subsets of Unist are allowed to define properties on interfaces which
extend Unist’s abstract interfaces. For example, mdast defines
Link (Parent) with a url property.
interface Node {
type: string;
data: Data?;
position: Position?;
}Data represents data associated with any node. Data is a scope for
plug-ins to store any information. For example, remark-html
uses hProperties to let other plug-ins specify properties added to the
compiled HTML element.
interface Data { }Position references a range consisting of two points in a Unist
file. Position consists of a start and end point.
And, if relevant, an indent property.
When the value represented by a node is not present in the document corresponding to the syntax tree at the time of reading, it must not have positional information. These nodes are said to be generated.
interface Position {
start: Point;
end: Point;
indent: [uint32 >= 1]?;
}Point references a point consisting of two indices in a
Unist file: line and column, set to 1-based integers. An
offset (0-based) may be used.
interface Point {
line: uint32 >= 1;
column: uint32 >= 1;
offset: uint32 >= 0?;
}Nodes containing other nodes (said to be children) extend the abstract interface Parent (Node).
interface Parent <: Node {
children: [Node];
}Nodes containing a value extend the abstract interface Text (Node).
interface Text <: Node {
value: string;
}A tree is a node and all of its descendants (if any).
Node X is child of node Y, if Y’s children include X.
Node X is parent of node Y, if Y is a child of X.
The index of a child is its number of preceding siblings, or
0 if it has none.
Node X is a sibling of node Y, if X and Y have the same parent (if any).
The previous sibling of a child is its sibling at its index minus 1.
The next sibling of a child is its sibling at its index plus 1.
The root of an object is itself, if without parent or the root of its parent.
The root of a tree is any node in that tree without parent.
Node X is descendant of node Y, if X is a child of Y, or if X is a child of node Z that is a descendant of Y.
An inclusive descendant is a node or one of its descendants.
Node X is an ancestor of node Y, if Y is a descendant of X.
An inclusive ancestor is a node or one of its ancestors.
The head of a node is its first child (if any).
The tail of a node is its last child (if any).
Unist files are virtual files (such as vfile) representing documents at a certain location. They are not limited to existing files, nor to the file-system.
Unist utilities are functions which work with unist nodes, agnostic of remark, retext, or rehype.
A list of vfile-related utilities can be found at vfile.
unist-util-assert— Assert Unist nodesunist-util-filter— Create a new tree with all nodes that pass the given functionunist-util-find— Find a node by conditionunist-util-find-after— Find a node after another nodeunist-util-find-all-after— Find nodes after another node or indexunist-util-find-all-before— Find nodes before another node or indexunist-util-find-all-between— Find nodes between two nodes or positionsunist-util-find-before— Find a node before another nodeunist-util-generated— Check if a node is generatedunist-util-index— Index nodes by property or computed keyunist-util-inspect— Node inspectorunist-util-is— Check if a node passes a testunist-util-map— Create a new tree by mapping nodesunist-util-modify-children— Modify direct children of a parentunist-util-parents—parentreferences on nodesunist-util-position— Get positional info of nodesunist-util-remove— Remove nodes from Unist treesunist-util-remove-position— Remove positional info from a unist treeunist-util-select— Select nodes with CSS-like selectorsunist-util-source— Get the source of a value (node or position) in a fileunist-util-stringify-position— Stringify a node, position, or pointunist-util-visit— Recursively walk over nodesunist-util-visit-parents— Recursively walk over nodes, with a stack of parentsunist-util-visit-children— Visit direct children of a parentunist-util-visit-all-after— Visit nodes after another nodeunist-builder— Helper for creating treesunist-builder-blueprint— Convert Unist trees to unist-builder notation
unist 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 @azu, @blahah, @gibson042, @jlevy, and @mrzmmr for contributing commits since!