{"id":11295,"library":"mdast-zone","title":"mdast HTML Comment Zone Utility","description":"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.","status":"active","version":"6.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-zone","tags":["javascript","unist","mdast","mdast-util","util","utility","html","comment","comments","typescript"],"install":[{"cmd":"npm install mdast-zone","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-zone","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-zone","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal dependency updated in patch releases, used for finding comment markers.","package":"mdast-comment-marker","optional":false}],"imports":[{"note":"mdast-zone has been ESM-only since v5.0.0. CommonJS `require` is not supported.","wrong":"const { zone } = require('mdast-zone');","symbol":"zone","correct":"import { zone } from 'mdast-zone';"},{"note":"This is a TypeScript type, so `import type` is the correct syntax. It's not a runtime export.","wrong":"import { Handler } from 'mdast-zone';","symbol":"Handler","correct":"import type { Handler } from 'mdast-zone';"},{"note":"The `ZoneInfo` type was renamed to `Info` in v6.0.0. Referencing `ZoneInfo` will cause a TypeScript error on newer versions.","wrong":"import type { ZoneInfo } from 'mdast-zone';","symbol":"Info","correct":"import type { Info } from 'mdast-zone';"}],"quickstart":{"code":"import {zone} from 'mdast-zone';\nimport {remark} from 'remark';\nimport {unified} from 'unified'; // Required for unified.Plugin types\n\nasync function processMarkdown() {\n  const markdownInput = `<!--foo start-->\\n\\nFoo\\n\\n<!--foo end-->`;\n\n  /** @type {import('unified').Plugin<[], import('mdast').Root>} */\n  function myPluginThatReplacesFoo() {\n    return function (tree) {\n      zone(tree, 'foo', function (start, nodes, end) {\n        console.log(`Found zone 'foo' with content: '${nodes.map(n => 'value' in n ? n.value : '').join('')}'`);\n        return [\n          start,\n          {type: 'paragraph', children: [{type: 'text', value: 'Bar.'}]},\n          end\n        ];\n      });\n    };\n  }\n\n  const file = await remark()\n    .use(myPluginThatReplacesFoo)\n    .process(markdownInput);\n\n  console.log(String(file));\n}\n\nprocessMarkdown();\n","lang":"typescript","description":"This example demonstrates how to define a content zone using HTML comments (`<!--foo start-->` and `<!--foo end-->`) 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."},"warnings":[{"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.","message":"mdast-zone migrated to being an ESM-only package. Attempting to `require` it will result in an `ERR_REQUIRE_ESM` error.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Node.js environment to version 16 or newer.","message":"Version 6.0.0 increased the minimum required Node.js version to 16. Running on older Node.js versions will cause compatibility issues.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Update all references to `ZoneInfo` to `Info` in your TypeScript code.","message":"The `ZoneInfo` TypeScript type was renamed to `Info` in version 6.0.0. Code referencing `ZoneInfo` will no longer compile.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure your module bundler or Node.js environment is configured to correctly resolve `export` maps. Avoid using private or undocumented APIs.","message":"Version 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.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Review your TypeScript code for any direct or indirect usage of `unist-util-visit` types and update accordingly.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to import `mdast-zone` using CommonJS `require()` syntax in an environment that enforces ESM-only.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure `unified` is installed (`npm install unified`) and imported if you're using TypeScript annotations like `import('unified').Plugin`.","cause":"Often occurs when `unified` types are missing for plugin annotations, or when `remark` and `unified` versions are incompatible.","error":"TypeError: Cannot read properties of undefined (reading 'Root')"},{"fix":"Replace `ZoneInfo` with `Info` in your TypeScript code.","cause":"Using the old type name `ZoneInfo` after upgrading to `mdast-zone` v6.0.0 or later.","error":"Cannot find name 'ZoneInfo'. Did you mean 'Info'?"}],"ecosystem":"npm"}