remark plugin that removes unused reference definitions from a document
This is a unified (remark) plugin that removes unused reference
definitions from a document. Also removes unused GFM footnotes definitions.
While you can get a similar effect by running something like the following:
remark -o --use inline-links --use reference-links your-markdown-file.md
Such a naive approach will destroy all of your carefully considered
alphanumeric reference ids (e.g. the "alphanumeric-id" in
[text][alphanumeric-id])! This plugin only elides unused reference
definitions, leaving the rest intact.
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-remove-unused-definitions
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 remarkRemoveUnusedDefs from 'remark-remove-unused-definitions';
const file = await remark()
.use(remarkRemoveUnusedDefs)
.process(await read('example.md'));
console.log(String(file));
remark -o --use remove-unused-definitions README.md
In package.json:
/* … */
"remarkConfig": {
"plugins": [
"remark-remove-unused-definitions"
/* … */
]
},
/* … */
In .remarkrc.js:
module.exports = {
plugins: [
// …
'remove-unused-definitions'
]
};
In .remarkrc.mjs:
import remarkRemoveUnusedDefs from 'remark-remove-unused-definitions';
export default {
plugins: [
// …
remarkRemoveUnusedDefs
]
};
API
Detailed interface information can be found under docs/.
Examples
Suppose we have the following Markdown file example.md:
# Documentation
This [package][1] is [more than][2nd-half-idiom] meets the eye.
## Install [remark][8]
…
[1st-half-idiom]: https://meme-link-1
[2nd-half-idiom]: https://meme-link-2
[1]: https://npm.im/some-package
[2]: #install
[3]: #usage
[4]: #api
[5]: #related
[6]: #contributing-and-support
[7]: #contributors
[8]: https://npm.im/remark
Then running the following JavaScript:
import { read } from 'to-vfile';
import { remark } from 'remark';
import remarkRemoveUnusedDefs from 'remark-remove-unused-definitions';
const file = await remark()
.use(remarkRemoveUnusedDefs)
.process(await read('example.md'));
console.log(String(file));
Would output the following (assuming remark is configured for tight
references):
# Documentation
This [package][1] is [more than][2nd-half-idiom] meets the eye.
## Install [remark][8]
…
[2nd-half-idiom]: https://meme-link-2
[1]: https://npm.im/some-package
[8]: https://npm.im/remark
Now all the unused definitions have been deleted. Nice!
Finally, notice how those numeric reference definition ids are not contiguous:
instead of [1] and [2] it's [1] and [8]. Luckily, there exists a remark
plugin that will ensure numeric reference ids flow through the document in
ascending order starting from [1].
Appendix
Further documentation can be found under docs/.
Published Package Details
This is an ESM-only package 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 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. These entries may or may not include: an
exports[ENTRY].types condition pointing to a type
declaration file for TypeScript and IDEs, a
exports[ENTRY].module 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 not enumerated here. Check the
package.json file to see which export conditions are
supported.
Note that, regardless of the { "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 key, which is almost always false for
optimal tree shaking where appropriate.
License
See LICENSE.
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! ✊🏿 Or buy
me a beer, I'd appreciate it. Thank you!
See CONTRIBUTING.md and SUPPORT.md for
more information.
Contributors
See the table of contributors.
