mdast HTML Comment Zone Utility

Common errors

• ERR_REQUIRE_ESM

  cause 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')

  cause 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'?

  cause 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.

Warnings

• breaking mdast-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.
• breaking Version 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.
• breaking The `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.
• breaking 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.
  Fix: Ensure your module bundler or Node.js environment is configured to correctly resolve `export` maps. Avoid using private or undocumented APIs.
• breaking 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.
  Fix: Review your TypeScript code for any direct or indirect usage of `unist-util-visit` types and update accordingly.

Install

• npm install mdast-zone npm
• yarn add mdast-zone yarn
• pnpm add mdast-zone pnpm

Imports

• zone
  wrong:

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

  correct:

  import { zone } from 'mdast-zone';

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

  import { Handler } from 'mdast-zone';

  correct:

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

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

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

  correct:

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

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

Quickstart

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.

import {zone} from 'mdast-zone';
import {remark} from 'remark';
import {unified} from 'unified'; // Required for unified.Plugin types

async function processMarkdown() {
  const markdownInput = `<!--foo start-->\n\nFoo\n\n<!--foo end-->`;

  /** @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();