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]][x-badge-blm-link]
[![Last commit timestamp][x-badge-lastcommit-image]][x-badge-repo-link]
[![Codecov][x-badge-codecov-image]][x-badge-codecov-link]
[![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]][x-badge-npm-link]
[![Monthly Downloads][x-badge-downloads-image]][x-badge-downloads-link]
# remark-ignore
This is a [unified][1] ([remark][2]) 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][3]. In effect, remark-ignore is a more generic version of
[remark-lint's ``][4].
This plugin is useful for preventing the transformation of auto-generated
content, e.g. [all-contributors][5], [doctoc][6], etc. You might also be
interested in [remark-tight-comments][7], 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](#install)
- [Usage](#usage)
- [Via API](#via-api)
- [Via remark-cli](#via-remark-cli)
- [Via unified configuration](#via-unified-configuration)
- [API](#api)
- [Examples](#examples)
- [Related](#related)
- [Appendix](#appendix)
- [Published Package Details](#published-package-details)
- [License](#license)
- [Contributing and Support](#contributing-and-support)
- [Contributors](#contributors)
## Install
> Due to the nature of the unified ecosystem, this package is ESM only and
> cannot be `require`'d.
To install:
```shell
npm install --save-dev remark-ignore
```
## Usage
For maximum flexibility, there are several ways this plugin can be invoked.
### Via API
```typescript
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`):
```typescript
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`][4] 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](https://xunn.at/docs-remark-cli)
```shell
remark -o --use ignore README.md
```
Or, using the alternative syntax:
```shell
remark -o --use ignore/start --use … --use ignore/end README.md
```
### Via [unified configuration](https://xunn.at/docs-unified-configuration)
In `package.json`:
```javascript
/* … */
"remarkConfig": {
"plugins": [
"remark-ignore"
/* … */
]
},
/* … */
```
In `.remarkrc.js` (using the alternative syntax):
```javascript
module.exports = {
plugins: [
'remark-ignore/start',
// …
'remark-ignore/end'
]
};
```
In `.remarkrc.mjs` (using the alternative syntax):
```javascript
import { ignoreStart, ignoreEnd } from 'remark-ignore';
export default {
plugins: [
ignoreStart,
// …
ignoreEnd
]
};
```
## API
Detailed interface information can be found under [`docs/`][x-repo-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`:
```markdown
# Some project
[](https://github.com/remarkjs/remark-defsplit/actions)
## Section
[A link](https://example.com)
[Another link](https://example.com)
```
Then running the following JavaScript:
```typescript
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:
```markdown
# 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:
```markdown
# Some project
[](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:
```markdown
# Some project
[](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:
```markdown
# Some project
[](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:
```markdown
# Some project
[](https://github.com/remarkjs/remark-defsplit/actions)
## Section
[A link](https://example.com)
[Another link][1]
[1]: https://example.com
```
## Related
- [remark-tight-comments][7] — remove unnecessary newlines around comments.
- [remark-comments][9] — new syntax to ignore things.
- [remark-message-control][10] — enable, disable, and ignore messages using
comments.
- [mdast-util-hidden][11] — prevent nodes from being seen by [transformers][12].
- [mdast-comment-marker][13] — parse a comment marker in mdast.
- [mdast-zone][14] — treat HTML comments as ranges or markers in mdast.
## Appendix
Further documentation can be found under [`docs/`][x-repo-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.
Expand details
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]`][x-repo-package-json] 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][x-repo-package-json] file to see which export conditions are
supported.
Note that, regardless of the [`{ "type": "..." }`][x-pkg-type] specified in
[`package.json`][x-repo-package-json], any JavaScript files written in ESM
syntax (including distributables) will always have the `.mjs` extension. Note
also that [`package.json`][x-repo-package-json] may include the
[`sideEffects`][x-pkg-side-effects-key] key, which is almost always `false` for
optimal [tree shaking][x-pkg-tree-shaking] where appropriate.