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 <!-- prettier-ignore -->, <!-- prettier-ignore-start -->, and <!-- prettier-ignore-end --> are to Prettier. In effect, remark-ignore is a more generic version of remark-lint's <!-- lint disable -->.

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

• Install
• Usage
  • Via API
  • Via remark-cli
  • Via unified configuration
• API
• Examples
• Related
• Contributing and Support
  • Contributors

Install

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

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 <!-- remark-ignore -->, <!-- remark-ignore-start -->, and <!-- remark-ignore-end --> 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

Related

• remark-tight-comments — remove unnecessary newlines around comments.
• remark-comments — 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.

Contributing and Support

New issues 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! ✊🏿 Thank you!

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

Contributors

See the table of contributors.