unified-log-tree

A robust Next.js newsletter Next.js Weekly is sponsoring me 💖

A warm thanks 🙌 to @ErfanEbrahimnia, @recepkyk, and @LSeaburg for the support 💖

This package is a unified (remark) plugin to log and optionally filter abstract syntax trees (ASTs) for debugging purposes. It is a debugging plugin for the unified ecosystem that logs ASTs without mutating.

unified is a project that transforms content with abstract syntax trees (ASTs) using the new parser micromark. remark adds support for markdown to unified. mdast is the Markdown Abstract Syntax Tree (AST) which is a specification for representing markdown in a syntax tree. rehype is a tool that transforms HTML with plugins. hast stands for HTML Abstract Syntax Tree (HAST) that rehype uses. recma adds support for producing a javascript code by transforming esast which stands for Ecma Script Abstract Syntax Tree (AST) that is used in production of compiled source for the MDX.

It is a unified plugin working with remark, rehype or recma. It doesn't mutate the AST. It only inspects and logs abstract syntax trees (ASTs) for debugging.

When should I use this?

unified-log-tree is useful when you want to inspect, debug, or snapshot syntax trees during a unified processing pipeline.

It works with any unist-compatible syntax tree:

• mdast (remark)
• hast (rehype)
• esast (recma)
• any custom unist-based AST

This plugin:

• ✅ Logs the syntax tree to the console
• ✅ Optionally filters nodes using test
• ✅ Preserves parent chains when filtering
• ✅ Optionally preserves full subtrees
• ✅ Can hide position data
• ❌ Does not transform or mutate the original tree

It is purely a debugging utility.

Installation

This package is ESM only.

In Node.js (version 16+), install with npm:

npm install unified-log-tree

or

yarn add unified-log-tree

Usage

⚠️ Important: Factory Pattern Usage

This plugin follows a factory pattern.

Unlike typical unified plugins that are used like this:

.use(plugin, options)

this plugin must be used like this:

.use(plugin(options))

Why?

The plugin is implemented as a factory so that it can be used multiple times in a single unified pipeline — for example, to log different stages (mdast, hast, etc.) independently.

Because of this structure, it returns a configured plugin instance immediately, which is why .use(plugin(options)) is required.

Basic usage (to log full tree)

import { read } from "to-vfile";
import { unified } from "unified";
import remarkParse from "remark-parse";
import logTree from "unified-log-tree";

const file = await unified()
  .use(remarkParse)
  .use(logTree()) // ← factory call
  .process(await read("example.md"));

Running this will print the full mdast to the console.

With filtering

You can pass a test option (powered by unist-util-is) to log only specific nodes.

.use(logTree({ test: "heading" }))

This will:

• Keep only heading nodes
• Preserve their parent chain
• Remove unrelated branches

With label

.use(logTree({ label: "Remark AST" }))

Console output:

[unified-log-tree] Remark AST
{ ...tree }

In a full pipeline (remark → rehype)

import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import logTree from "unified-log-tree";

await unified()
  .use(remarkParse)
  .use(logTree({ label: "MDAST" }))
  .use(remarkRehype)
  .use(logTree({ label: "HAST" }))
  .use(rehypeStringify)
  .process("# Hello");

This logs both the mdast and hast trees.

Options

All options are optional.

type LogTreeOptions = {
  test?: Test;
  preserveSubtree?: boolean;
  excludeKeys?: string[];
  depth?: number | null;
  indentation?: number;
  label?: string;
  ref?: object;
  enabled?: boolean;
};

test

Type: Test (from unist-util-is)
Default: undefined

Filters the tree. Only matching nodes and their parent chain are kept.

Examples:

test: "heading"
test: ["heading", "paragraph"]
test: (node) => node.type === "link"

If test is undefined or null, the full tree is logged.

preserveSubtree

Type: boolean
Default: true

Controls behavior when a node matches test.

• true → Keep the matched node and entire subtree.
• false → Recursively filter its children as well.

Example:

.use(logTree({
  test: "heading",
  preserveSubtree: false
}))

.use(logTree({
  test: { type: "CallExpression" }
  preserveSubtree: true
}))

excludeKeys

Type: string[]
Default: [] empty array

An array of property names to be recursively removed from the AST nodes before logging. This is useful for reducing noise by hiding metadata like position, loc, or range. Use this to filter out unwanted node data during logging.

.use(logTree({ excludeKeys: ["position"] }))

Strips position from the AST output. Output of the tree will not contain position data.

depth

Type: number | null
Default: null

Passed to console.dir as the depth option.

.use(logTree({ depth: 4 }))

indentation

Type: number
Default: 2

Controls JSON indentation size before printing.

label

Type: string
Default: undefined

Adds a label before the logged tree.

.use(logTree({ label: "Rehype AST" }))

ref

Type: object
Default: undefined

An optional object reference that will be mutated to contain the resulting tree. This is particularly useful in testing environments (like Vitest or Jest) where you need to perform assertions on the AST without relying on console.log captures.

[!IMPORTANT] Because JavaScript uses call-by-sharing for objects, the plugin uses Object.assign() to update the reference you provide. This allows the tree data to "leak" back out to your test scope.

const treeRef = {};

const processor = unified()
  .use(remarkParse)
  .use(logTree, { 
    ref: treeRef,
    excludeKeys: ["position"] 
  })
  .use(remarkStringify);

await processor.process("# Hello World");

// treeRef now contains the processed MDAST
console.log(treeRef.type); // "root"

enabled

Type: boolean
Default: true

Allows turning the logger off without removing it from the pipeline.

.use(logTree({ enabled: false }))

Useful in CI or production builds.

Filtering Behavior

When test is provided:

• Matching nodes are kept.
• Parent nodes are preserved if any descendant matches.
• Non-matching branches are removed.
• The original AST is never mutated.

The plugin internally clones the tree before pruning.

Syntax Tree

This plugin does not transform or mutate the syntax tree. It:

• Clones the tree (when filtering)
• Optionally prunes branches
• Logs the result
• Leaves the original AST untouched

Types

This package is fully typed with TypeScript. The options type is exported as LogTreeOptions.

Compatibility

This plugin works with unified version 6+, and any unist-compatible syntax trees in a plugin chain of remark, rehype, recma.

Security

This plugin does not generate HTML, execute user code, or manipulate output content. It only logs syntax trees to the console. There are no XSS or runtime security concerns.

My Plugins

I like to contribute the Unified / Remark / MDX ecosystem, so I recommend you to have a look my plugins.

Support My Work (become a sponsor 🚀)

If you find unified-log-tree or any of my projects is useful and helpful, please consider supporting my work. Your sponsorship means a lot to me and keeps these projects alive and updated! 💖

My sponsors are going to be featured at the very top of the page and proudly displayed on my Sponsor Wall.

Thank you for supporting open source! 🙌

My Remark Plugins

• remark-flexible-code-titles – Remark plugin to add titles or/and containers for the code blocks with customizable properties
• remark-flexible-containers – Remark plugin to add custom containers with customizable properties in markdown
• remark-ins – Remark plugin to add ins element in markdown
• remark-flexible-paragraphs – Remark plugin to add custom paragraphs with customizable properties in markdown
• remark-flexible-markers – Remark plugin to add custom mark element with customizable properties in markdown
• remark-flexible-toc – Remark plugin to expose the table of contents via vfile.data or via an option reference
• remark-mdx-remove-esm – Remark plugin to remove import and/or export statements (mdxjsEsm)
• remark-mdx-remove-expressions – Remark plugin to remove MDX expressions within curlybraces {} in MDX content

My Rehype Plugins

• rehype-pre-language – Rehype plugin to add language information as a property to pre element
• rehype-highlight-code-lines – Rehype plugin to add line numbers to code blocks and allow highlighting of desired code lines
• rehype-code-meta – Rehype plugin to copy code.data.meta to code.properties.metastring
• rehype-image-toolkit – Rehype plugin to enhance Markdown image syntax ![]() and Markdown/MDX media elements (<img>, <audio>, <video>) by auto-linking bracketed or parenthesized image URLs, wrapping them in <figure> with optional captions, unwrapping images/videos/audio from paragraph, parsing directives in title for styling and adding attributes, and dynamically converting images into <video> or <audio> elements based on file extension.

My Recma Plugins

• recma-mdx-escape-missing-components – Recma plugin to set the default value () => null for the Components in MDX in case of missing or not provided so as not to throw an error
• recma-mdx-change-props – Recma plugin to change the props parameter into the _props in the function _createMdxContent(props) {/* */} in the compiled source in order to be able to use {props.foo} like expressions. It is useful for the next-mdx-remote or next-mdx-remote-client users in nextjs applications.
• recma-mdx-change-imports – Recma plugin to convert import declarations for assets and media with relative links into variable declarations with string URLs, enabling direct asset URL resolution in compiled MDX.
• recma-mdx-import-media – Recma plugin to turn media relative paths into import declarations for both markdown and html syntax in MDX.
• recma-mdx-import-react – Recma plugin to ensure getting React instance from the arguments and to make the runtime props {React, jsx, jsxs, jsxDev, Fragment} is available in the dynamically imported components in the compiled source of MDX.
• recma-mdx-html-override – Recma plugin to allow selected raw HTML elements to be overridden via MDX components.
• recma-mdx-interpolate – Recma plugin to enable interpolation of identifiers wrapped in curly braces within the alt, src, href, and title attributes of markdown link and image syntax in MDX.

My Unist Utils and Unified Plugins

I also build low-level utilities and plugins for the Unified ecosystem that can be used across Remark, Rehype, Recma, and other unist-based abstract syntax trees (ASTs).

• unist-util-find-between – Unist utility to find the nodes between two nodes.
• unified-log-tree – Unified plugin to log abstract syntax trees (ASTs) for debugging without mutating.

License

MIT License © ipikuka