mdast-zone

library6.1.0jsnpmunverified

mdast-zone is a utility within the `syntax-tree` ecosystem designed to manipulate Markdown Abstract Syntax Trees (mdast) by identifying and modifying content sections defined by HTML comments. It provides a `zone` function that takes an mdast tree, a comment name (e.g., 'foo'), and a handler function. This handler receives the `start` comment, the `nodes` between the comments, and the `end` comment, allowing developers to replace or modify the content within these defined zones. The current stable version is 6.1.0, and new releases, including major versions, appear roughly annually, with minor and patch updates in between, demonstrating active maintenance. It differentiates itself from similar utilities like `mdast-util-heading-range` by using hidden HTML comments as markers for sections rather than visible headings, making it suitable for programmatic content generation or manipulation where markers should not be visible in the rendered output. This package is ESM-only and requires Node.js 16+ since v6.0.0.

serialization

npm install mdast-zone

github ↗package ↗

INSTALL

IMPORT

SIG · MDAST-ZONE

mdast-zone

serializationjavascriptv6.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

zone

✓ import { zone } from 'mdast-zone';

✗ const { zone } = require('mdast-zone');

mdast-zone has been ESM-only since v5.0.0. CommonJS `require` is not supported.

Handler

✓ import type { Handler } from 'mdast-zone';

✗ import { Handler } from 'mdast-zone';

This is a TypeScript type, so `import type` is the correct syntax. It's not a runtime export.

Info

✓ import type { Info } from 'mdast-zone';

✗ import type { ZoneInfo } from 'mdast-zone';

The `ZoneInfo` type was renamed to `Info` in v6.0.0. Referencing `ZoneInfo` will cause a TypeScript error on newer versions.

This example demonstrates how to define a content zone using HTML comments (`` and ``) and then replace the content within that zone using the `mdast-zone` utility within a `remark` plugin. It logs the original content found and replaces it with a new paragraph.

import {zone} from 'mdast-zone'; import {remark} from 'remark'; import {unified} from 'unified'; // Required for unified.Plugin types async function processMarkdown() { const markdownInput = `\n\nFoo\n\n`; /** @type {import('unified').Plugin<[], import('mdast').Root>} */ function myPluginThatReplacesFoo() { return function (tree) { zone(tree, 'foo', function (start, nodes, end) { console.log(`Found zone 'foo' with content: '${nodes.map(n => 'value' in n ? n.value : '').join('')}'`); return [ start, {type: 'paragraph', children: [{type: 'text', value: 'Bar.'}]}, end ]; }); }; } const file = await remark() .use(myPluginThatReplacesFoo) .process(markdownInput); console.log(String(file)); } processMarkdown();

Debug

Known issues

breakingmdast-zone migrated to being an ESM-only package. Attempting to `require` it will result in an `ERR_REQUIRE_ESM` error.

fix

Migrate your project to use ES modules (`import`) or ensure you are loading mdast-zone in an ESM context. Update Node.js to v16 or later.

affects: >=5.0.0

breakingVersion 6.0.0 increased the minimum required Node.js version to 16. Running on older Node.js versions will cause compatibility issues.

fix

Upgrade your Node.js environment to version 16 or newer.

affects: >=6.0.0

breakingThe `ZoneInfo` TypeScript type was renamed to `Info` in version 6.0.0. Code referencing `ZoneInfo` will no longer compile.

fix

Update all references to `ZoneInfo` to `Info` in your TypeScript code.

affects: >=6.0.0

breakingVersion 6.0.0 changed to use an `export` map, which might affect some build systems or specific module resolution strategies if relying on undocumented or private APIs.

fix

Ensure your module bundler or Node.js environment is configured to correctly resolve `export` maps. Avoid using private or undocumented APIs.

affects: >=6.0.0

breakingVersion 4.0.0 updated its dependency on `unist-util-visit`, which could potentially introduce breaking changes for TypeScript users if their types were tightly coupled or if they relied on specific `unist-util-visit` type definitions.

fix

Review your TypeScript code for any direct or indirect usage of `unist-util-visit` types and update accordingly.

affects: >=4.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to import `mdast-zone` using CommonJS `require()` syntax in an environment that enforces ESM-only.

fix

Change `const { zone } = require('mdast-zone');` to `import { zone } from 'mdast-zone';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

TypeError: Cannot read properties of undefined (reading 'Root')

Often occurs when `unified` types are missing for plugin annotations, or when `remark` and `unified` versions are incompatible.

fix

Ensure `unified` is installed (`npm install unified`) and imported if you're using TypeScript annotations like `import('unified').Plugin`.

Cannot find name 'ZoneInfo'. Did you mean 'Info'?

Using the old type name `ZoneInfo` after upgrading to `mdast-zone` v6.0.0 or later.

fix

Replace `ZoneInfo` with `Info` in your TypeScript code.

Upgrade

Version history

6.1.0latest on npm

Audit

Dependencies

mdast-comment-markerrequiredInternal dependency updated in patch releases, used for finding comment markers.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/mdast-zone ↗

packagehttps://www.npmjs.com/package/mdast-zone ↗