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. ✨
Due to the nature of the unified ecosystem, this package is ESM only and cannot be
require'd.
npm install --save-dev remark-ignoreFor maximum flexibility, there are several ways this plugin can be invoked.
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.mdOr, using the alternative syntax:
remark -o --use ignore/start --use … --use ignore/end README.mdIn 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
]
};Detailed interface information can be found under docs/.
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
[](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.comOn the other hand, if example.md contained the following:
# Some project
<!-- remark-ignore -->
[](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 -->
[](https://github.com/remarkjs/remark-defsplit/actions)
## Section
[A link][1]
[Another link][1]
[1]: https://example.comIf instead example.md contained the following:
<!-- remark-ignore-start -->
# Some project
[](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
[](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 — 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.
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.
See the table of contributors.