---
type: ApiDoc
path: src/AstQuery.js
---
# AstQuery Class

The AstQuery class is a wrapper around The [MDAST AST Tree](https://github.com/syntax-tree/mdast)

It provides methods for querying nodes in the document.

## Examples

### Accessing the astQuery instance for a document

```javascript
const doc = collection.document("epics/authentication")
const { astQuery } = doc
// equivalent to doc.astQuery but can be used against any AST
const query = doc.queryAst(document.ast)
const other = new AstQuery(doc.ast)
```

### Selecting all nodes that match a selector

You can use any of the selectors documented in [unist-util-select](https://www.npmjs.com/package/unist-util-select)

-   [x] `*` (universal selector)
-   [x] `,` (multiple selector)
-   [x] `paragraph` (type selector)
-   [x] `blockquote paragraph` (combinator: descendant selector)
-   [x] `blockquote > paragraph` (combinator: child selector)
-   [x] `code + paragraph` (combinator: adjacent sibling selector)
-   [x] `code ~ paragraph` (combinator: general sibling selector)
-   [x] `[attr]` (attribute existence, checks that the value on the tree is not
        nullish)
-   [x] `[attr=value]` (attribute equality, this stringifies values on the tree)
-   [x] `[attr^=value]` (attribute begins with, only works on strings)
-   [x] `[attr$=value]` (attribute ends with, only works on strings)
-   [x] `[attr*=value]` (attribute contains, only works on strings)
-   [x] `[attr~=value]` (attribute contains, checks if `value` is in the array,
        if there’s an array on the tree, otherwise same as attribute equality)
-   [x] `:any()` (functional pseudo-class, use `:matches` instead)
-   [x] `:has()` (functional pseudo-class)
        Relative selectors (`:has(> img)`) are not supported, but `:scope` is
-   [x] `:matches()` (functional pseudo-class)
-   [x] `:not()` (functional pseudo-class)
-   [x] `:blank` (pseudo-class, blank and empty are the same: a parent without
        children, or a node without value)
-   [x] `:empty` (pseudo-class, blank and empty are the same: a parent without
        children, or a node without value)
-   [x] `:root` (pseudo-class, matches the given node)
-   [x] `:scope` (pseudo-class, matches the given node)
-   [x] \* `:first-child` (pseudo-class)
-   [x] \* `:first-of-type` (pseudo-class)
-   [x] \* `:last-child` (pseudo-class)
-   [x] \* `:last-of-type` (pseudo-class)
-   [x] \* `:only-child` (pseudo-class)
-   [x] \* `:only-of-type` (pseudo-class)
-   [x] \* `:nth-child()` (functional pseudo-class)
-   [x] \* `:nth-last-child()` (functional pseudo-class)
-   [x] \* `:nth-last-of-type()` (functional pseudo-class)
-   [x] \* `:nth-of-type()` (functional pseudo-class)

```javascript
const h1 = astQuery.selectAll("heading[depth=1]")
const h2 = astQuery.selectAll("heading[depth=2]")
const codeBlocks = astQuery.selectAll("code")
```

There is also `astQuery.select` which will only return one node instead of an array of nodes.

### Finding all nodes between two headings

```javascript
const nodes = astQuery.findBetweenHeadings(
  astQuery.select("heading")[0],
  astQuery.select("heading")[1]
)
```

### Finding all nodes after another node

```javascript
const afterNodes = astQuery.findAllAfter(astQuery.select("heading")[0])
```

There is also `astQuery.findAfter` which just finds a single node.

### Finding all nodes before another node

```javascript
const beforeNodes = astQuery.findAllBefore(astQuery.select("heading")[0])
```

There is also `astQuery.findBefore` which just finds a single node.

## API

### Instance Methods


#### findAllBefore

Find all nodes in the document that come before the given node.  Passing an optional
selector will filter the results.

#### findAllAfter

Find all nodes in the document that come after the given node. Passing an optional
selector will filter the results.

#### findBefore

Find the first node before the given node which matches the selector
- `{AstNode} node` a node in the AST to start searching from
- `{String|Function} selector` a selector string from unist-util-select, or a function which will be passed the node and return true if it matches

#### findAfter

Find the next node after the given node which matches the given elector
- `{AstNode} node` a node in the AST to start searching from
- `{Function} selector` a function which returns true if the node matches

Returns `{AstNode} the first node to match the selector`

#### findBetween

Find all the nodes between the given nodes
- `{AstNode} nodeOne` a node in the AST to start searching from
- `{AstNode} nodeTwo` a node in the AST to stop searching at

#### select

Find the first node which matches the selector.  See unist-util-select
- `{String|Function} selector` a string from unist-util-select or a function which should return true if the node matches

Returns `{AstNode} the first node to match the selector`

#### selectAll

Find all nodes which match the selector.  See unist-util-select
- `{String|Function} selector` a string from unist-util-select or a function which should return true if the node matches

Returns `{Array[AstNode]} all nodes to match the selector`

#### visit

Run the given visitor function for each node in the document.
- `{Function} visitor` a function which will be passed a node from the tree.

#### atLine

Get the node at a given line number.
- `{Number} lineNumber` the line number to find

Returns `{AstNode} the node at the given line number`

#### findNextSiblingHeadingTo

Find the next heading node with the same depth as the given node.
- `{AstNode} headingNode` a heading node to start searching from

Returns `{AstNode} the next heading node with the same depth as the given node`

#### headingsAtDepth

Get all headings at a given depth.
- `{Number} depth` the heading depth to find (1-6)

Returns `{Array[AstNode]} all headings at the given depth`

#### findAllHeadingsByText

Finds all headings where the content matches the given string.  Not case sensitive.
Passing false as a second argument will use a substring match.
- `{String} text` the text of the heading to match
- `{Boolean} exact` whether to use an exact match or a substring match

Returns `{Array[AstNode]} all headings with the given text`

#### findHeadingByText

Find a heading where the content matches the given string.  Not case sensitive.
Passing false as a second argument will use a substring match.
- `{String} text` the text of the heading to match
- `{Boolean} exact` whether to use an exact match or a substring match

Returns `{AstNode} the first heading with the given text`