<commit_before># mdast-zone

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] utility to find two comments and replace the content in them.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`zone(tree, name, handler)`](#zonetree-name-handler)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that lets you find certain comments, then takes the
content between them, and calls a given handler with the result, so that you can
change or replace things.

## When should I use this?

This utility is typically useful when you have certain sections that can be
generated.
Comments are a hidden part of markdown, so they can be used as processing
instructions.
You can use those comments to define what content to change or replace.

A similar package, [`mdast-util-heading-range`][mdast-util-heading-range], does
the same but uses a heading to mark the start and end of sections.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install mdast-zone
```

In Deno with [`esm.sh`][esmsh]:

```js
import {zone} from 'https://esm.sh/mdast-zone@5'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {zone} from 'https://esm.sh/mdast-zone@5?bundle'
</script>
```

## Use

Say we have the following file, `example.md`:

```markdown
<!--foo start-->

Foo

<!--foo end-->
```

…and a module `example.js`:

```js
import {read} from 'to-vfile'
import {remark} from 'remark'
import {zone} from 'mdast-zone'

const file = await remark()
  .use(myPluginThatReplacesFoo)
  .process(await read('example.md'))

console.log(String(file))

/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function myPluginThatReplacesFoo() {
  return (tree) => {
    zone(tree, 'foo', (start, nodes, end) => [
      start,
      {type: 'paragraph', children: [{type: 'text', value: 'Bar.'}]},
      end
    ])
  }
}
```

…now running `node example.js` yields:

```markdown
<!--foo start-->

Bar
<commit_msg>Fix typo<commit_after># mdast-zone

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] utility to find two comments and replace the content in them.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`zone(tree, name, handler)`](#zonetree-name-handler)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that lets you find certain comments, then takes the
content between them, and calls a given handler with the result, so that you can
change or replace things.

## When should I use this?

This utility is typically useful when you have certain sections that can be
generated.
Comments are a hidden part of markdown, so they can be used as processing
instructions.
You can use those comments to define what content to change or replace.

A similar package, [`mdast-util-heading-range`][mdast-util-heading-range], does
the same but uses a heading to mark the start and end of sections.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install mdast-zone
```

In Deno with [`esm.sh`][esmsh]:

```js
import {zone} from 'https://esm.sh/mdast-zone@5'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {zone} from 'https://esm.sh/mdast-zone@5?bundle'
</script>
```

## Use

Say we have the following file, `example.md`:

```markdown
<!--foo start-->

Foo

<!--foo end-->
```

…and a module `example.js`:

```js
import {read} from 'to-vfile'
import {remark} from 'remark'
import {zone} from 'mdast-zone'

const file = await remark()
  .use(myPluginThatReplacesFoo)
  .process(await read('example.md'))

console.log(String(file))

/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function myPluginThatReplacesFoo() {
  return (tree) => {
    zone(tree, 'foo', (start, nodes, end) => [
      start,
      {type: 'paragraph', children: [{type: 'text', value: 'Bar.'}]},
      end
    ])
  }
}
```

…now running `node example.js` yields:

```markdown
<!--foo start-->

Bar.

{'fraction_non_alphanumeric': 0.17904723455793298, 'fraction_numerical': 0.005248284214775939, 'mean_word_length': 4.451045104510451, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 19, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2031745', 'n_tokens_mistral': 1792, 'n_tokens_neox': 1691, 'n_words': 509}