remark plugin to exclude one or more nodes from transformation in the manner of "prettier-ignore" or "instanbul ignore next"

![Black Lives Matter!][x-badge-blm-image] ![Last commit timestamp][x-badge-lastcommit-image] ![Codecov][x-badge-codecov-image] [![Source license][x-badge-license-image]][x-badge-license-link] [![Uses Semantic Release!][x-badge-semanticrelease-image]][x-badge-semanticrelease-link] ![NPM version][x-badge-npm-image] ![Monthly Downloads][x-badge-downloads-image]

remark-ignore

This is a unified (remark) plugin that allows you to specify one or more sections of a Markdown file that should not be transformed or linted by remark.

This plugin is to remark what , , and  are to Prettier. In effect, remark-ignore is a more generic version of remark-lint's .

This plugin is useful for preventing the transformation of auto-generated content, e.g. all-contributors, doctoc, etc. You might also be interested in remark-tight-comments, which removes unnecessary newlines that remark inserts between/around Markdown comments by default. For a live example of these two plugins in action, check the source of [this very README.md file][8]. ✨

Install

Due to the nature of the unified ecosystem, this package is ESM only and cannot be require'd.

To install:

npm install --save-dev remark-ignore

Usage

For maximum flexibility, there are several ways this plugin can be invoked.

Via API

import { read } from 'to-vfile';
import { remark } from 'remark';
import remarkIgnore from 'remark-ignore';
import remarkReferenceLinks from 'remark-reference-links';

const file = await remark()
  // remarkIgnore should always be among the first plugins used
  .use(remarkIgnore)
  .use(remarkReferenceLinks)
  .process(await read('example.md'));

console.log(String(file));

There is an alternative syntax that allows you more fine-grain control over when ignored nodes are hidden from transformers (i.e. ignoreStart) versus when they are revealed (i.e. ignoreEnd):

import { read } from 'to-vfile';
import { remark } from 'remark';
import { ignoreStart, ignoreEnd } from 'remark-ignore';
import remarkReferenceLinks from 'remark-reference-links';

const file = await remark()
  .use(ignoreStart)
  .use(remarkReferenceLinks)
  .use(pluginThatCallsUseInternally)
  .use(ignoreEnd)
  .use(pluginThatWillSeeOtherwiseIgnoredNodes)
  .process(await read('example.md'));

console.log(String(file));

This is useful when dealing with plugins that call use internally, which might interfere with remark-ignore's default export (remarkIgnore in the above examples) which itself calls use(ignoreEnd) internally, or if you want plugins used before ignoreStart and/or after ignoreEnd to transform otherwise-"ignored" nodes.

Via remark-cli

remark -o --use ignore README.md

Or, using the alternative syntax:

remark -o --use ignore/start --use … --use ignore/end README.md

Via unified configuration

In package.json:

  /* … */
  "remarkConfig": {
    "plugins": [
      "remark-ignore"
      /* … */
    ]
  },
  /* … */

In .remarkrc.js (using the alternative syntax):

module.exports = {
  plugins: [
    'remark-ignore/start',
    // …
    'remark-ignore/end'
  ]
};

In .remarkrc.mjs (using the alternative syntax):

import { ignoreStart, ignoreEnd } from 'remark-ignore';

export default {
  plugins: [
    ignoreStart,
    // …
    ignoreEnd
  ]
};

API

Detailed interface information can be found under docs/.

Examples

Note that , , and  must always be top-level nodes. If they are nested within other nodes, such as a list item, they will be ignored.

Suppose we have the following Markdown file example.md:

# Some project

[![Build](https://github.com/remarkjs/remark-defsplit/workflows/main/badge.svg)](https://github.com/remarkjs/remark-defsplit/actions)

## Section

[A link](https://example.com)

[Another link](https://example.com)

Then running the following JavaScript:

import { read } from 'to-vfile';
import { remark } from 'remark';
import remarkIgnore from 'remark-ignore';
import remarkReferenceLinks from 'remark-reference-links';

const file = await remark()
  // remarkIgnore should always be among — if not THE — first plugins used
  .use(remarkIgnore)
  .use(remarkReferenceLinks)
  .process(await read('example.md'));

console.log(String(file));

Would output the following:

# Some project

[![Build][2]][1]

## Section

[A link][3]

[Another link][3]

[1]: https://github.com/remarkjs/remark-defsplit/actions
[2]: https://github.com/remarkjs/remark-defsplit/workflows/main/badge.svg
[3]: https://example.com

On the other hand, if example.md contained the following:

# Some project

<!-- remark-ignore -->

[![Build](https://github.com/remarkjs/remark-defsplit/workflows/main/badge.svg)](https://github.com/remarkjs/remark-defsplit/actions)

## Section

[A link](https://example.com)

[Another link](https://example.com)

Then running that same JavaScript would output:

# Some project

<!-- remark-ignore -->

[![Build](https://github.com/remarkjs/remark-defsplit/workflows/main/badge.svg)](https://github.com/remarkjs/remark-defsplit/actions)

## Section

[A link][1]

[Another link][1]

[1]: https://example.com

If instead example.md contained the following:

<!-- remark-ignore-start -->

# Some project

[![Build](https://github.com/remarkjs/remark-defsplit/workflows/main/badge.svg)](https://github.com/remarkjs/remark-defsplit/actions)

## Section

[A link](https://example.com)

<!-- remark-ignore-end -->

[Another link](https://example.com)

Then running that same JavaScript would output:

<!-- remark-ignore-start -->

# Some project

[![Build](https://github.com/remarkjs/remark-defsplit/workflows/main/badge.svg)](https://github.com/remarkjs/remark-defsplit/actions)

## Section

[A link](https://example.com)

<!-- remark-ignore-end -->

[Another link][1]

[1]: https://example.com

remark-tight-comments — remove unnecessary newlines around comments.
[remark-comments][9] — new syntax to ignore things.
remark-message-control — enable, disable, and ignore messages using comments.
mdast-util-hidden — prevent nodes from being seen by transformers.
mdast-comment-marker — parse a comment marker in mdast.
mdast-zone — treat HTML comments as ranges or markers in mdast.

Appendix

Further documentation can be found under docs/.

Published Package Details

This is an [ESM-only package][x-pkg-esm-wine] built by Babel for use in Node.js versions that are not end-of-life. For TypeScript users, this package supports both "Node10" and "Node16" module resolution strategies.

<summary>Expand details</summary> That means ESM source will load this package via import { ... } from ... or await import(...) and CJS source will load this package via dynamic import(). This has several benefits, the foremost being: less code shipped/smaller package size, avoiding [dual package hazard][x-pkg-dual-package-hazard] entirely, distributables are not packed/bundled/uglified, and a drastically less complex build process. The glaring downside, which may or may not be relevant, is that CJS consumers cannot require() this package and can only use import() in an asynchronous context. This means, in effect, CJS consumers may not be able to use this package at all. Each entry point (i.e. ENTRY) in package.json's exports[ENTRY] object includes one or more [export conditions][x-pkg-exports-conditions]. These entries may or may not include: an [exports[ENTRY].types][x-pkg-exports-types-key] condition pointing to a type declaration file for TypeScript and IDEs, a [exports[ENTRY].module][x-pkg-exports-module-key] condition pointing to (usually ESM) source for Webpack/Rollup, a exports[ENTRY].node and/or exports[ENTRY].default condition pointing to (usually CJS2) source for Node.js require/import and for browsers and other environments, and [other conditions][x-pkg-exports-conditions] not enumerated here. Check the package.json file to see which export conditions are supported. Note that, regardless of the [{ "type": "..." }][x-pkg-type] specified in package.json, any JavaScript files written in ESM syntax (including distributables) will always have the .mjs extension. Note also that package.json may include the [sideEffects][x-pkg-side-effects-key] key, which is almost always false for optimal tree shaking where appropriate.

License

See LICENSE.

Contributing and Support

[New issues][x-repo-choose-new-issue] and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can star 🌟 this project to let me know you found it useful! ✊🏿 Or buy me a beer, I'd appreciate it. Thank you!

See CONTRIBUTING.md and SUPPORT.md for more information.