Package Exports

remark-renumber-references
remark-renumber-references/package
remark-renumber-references/package.json

Readme

remark plugin that renumbers numeric reference-style link ids contiguously starting from [1]

remark-renumber-references

This is a unified (remark) plugin that renumbers numeric reference-style link ids contiguously starting from [1] and counting up. Also plays nicely with GFM footnotes (by completely ignoring them), and comes with full unicode support.

After running this plugin, all definitions, both numeric and alphanumeric, will always be placed at the very bottom of the document.

This plugin is a drop-in replacement for remark-reference-links. If you want to preserve some inline links (e.g. for generated content), check out remark-ignore. You might also be interested in remark-sort-definitions, which will logically reorder the reference definitions at the bottom of your document. For a live example of these plugins in action, check the source of this very README.md file. ✨

Install
Usage
API
- Options
Examples
Related
Appendix
- Published Package Details
- License
Contributing and Support
- Contributors

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-renumber-references

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 remarkRenumberReferences from 'remark-renumber-references';

const file = await remark()
  // An options object is NOT required
  .use(remarkRenumberReferences, { preserveAlphanumericDefinitions: false })
  .process(await read('example.md'));

console.log(String(file));

Via remark-cli

remark -o --use renumber-references README.md

Via unified configuration

In package.json:

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

In .remarkrc.js:

module.exports = {
  plugins: [
    // …
    ['renumber-references', { preserveAlphanumericDefinitions: false }]
  ]
};

In .remarkrc.mjs:

import remarkRenumberReferences from 'remark-renumber-references';

export default {
  plugins: [
    // …
    remarkRenumberReferences
  ]
};

API

Detailed interface information can be found under docs/.

Options

This plugin recognizes the following options:

`preserveAlphanumericDefinitions`

Valid values: true | false
Default: true

If true, alphanumeric definition ids (i.e. any id that cannot be parsed into an integer) will be spared during the renumbering. If false, all definition ids will be deleted and recreated starting from [1].

Examples

Suppose we have the following Markdown file example.md:

# Documentation

This [package](https://npm.im/some-package) is [more than][2nd-half-idiom] meets
the eye.

- [Install remark](#install)
- [Usage](#usage)
- [API](#api)
- [Related](#related)
- [Contributing and Support](#contributing-and-support)
  - [Contributors](#contributors)

## Install [remark](https://npm.im/remark)

…

[2nd-half-idiom]: https://meme-link-2

Then running the following JavaScript:

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

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

console.log(String(file));

Would output the following (assuming remark is configured for tight references, dash bullets, and singular list item indents):

# Documentation

This [package][1] is [more than][2nd-half-idiom] meets the eye.

- [Install remark][2]
- [Usage][3]
- [API][4]
- [Related][5]
- [Contributing and Support][6]
  - [Contributors][7]

## Install [remark][8]

…

[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

Later on, we rewrite sections of example.md and remove others (using remark-remove-unused-definitions to clear out the unused reference definitions).

Note that, while a side-effect of running this plugin is that unused numeric reference definitions are removed during renumbering, this behavior is not guaranteed and hence should not be relied upon. To ensure all unused reference definitions are always removed, use remark-remove-unused-definitions before this plugin.

Rerunning the above JavaScript leaves us with the following output:

# Documentation

> Warning: [something][2] to pay attention to.

This [package][1] is [more than][2nd-half-idiom] [meets the eye][1st-half-idiom].

- [Install unified][4]
- [Usage][3]
- [Related][5]
- [Contributing and Support][6]
  - [Maintainers][8]
  - [Contributors][7]

## Install [unified][9]

…

[2nd-half-idiom]: https://meme-link-2
[1]: https://npm.im/some-package
[3]: #usage
[5]: #related
[6]: #contributing-and-support
[7]: #contributors
[1st-half-idiom]: https://meme-link-1
[2]: https://something-or-other
[4]: #install
[8]: #maintainers
[9]: https://npm.im/unified

This might be good enough when run through a Markdown renderer where the end user is not exposed to the reference numbers, but what about the humans reading the plain text document itself?

In the words of one of Markdown's creators:

Markdown allows you to write using an easy-to-read, easy-to-write plain text format … The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.

What's "easy to read" is subjective. For those who find it bothersome or distracting reading Markdown documents containing reference links with integer ids that hop around in a random order, this is the plugin for you.

Suppose instead we ran the following JavaScript:

import { read } from 'to-vfile';
import { remark } from 'remark';
import remarkReferenceLinks from 'remark-reference-links';
import remarkRenumberReferences from 'remark-renumber-references';

const file = await remark()
  .use(remarkReferenceLinks)
  // It is important that this plugin is loaded AFTER any plugins that
  // *manipulate* or *remove* links, reference definitions, and/or their ids
  .use(remarkRenumberReferences)
  // However, this plugin should be loaded BEFORE any plugins that *sort*
  // reference definitions
  .process(await read('example.md'));

console.log(String(file));

Then we would get the following output:

# Documentation

> Warning: [something][1] to pay attention to.

This [package][2] is [more than][2nd-half-idiom] [meets the eye][1st-half-idiom].

- [Install unified][3]
- [Usage][4]
- [Related][5]
- [Contributing and Support][6]
  - [Maintainers][7]
  - [Contributors][8]

## Install [unified][9]

…

[2nd-half-idiom]: https://meme-link-2
[1st-half-idiom]: https://meme-link-1
[1]: https://something-or-other
[2]: https://npm.im/some-package
[3]: #install
[4]: #usage
[5]: #related
[6]: #contributing-and-support
[7]: #maintainers
[8]: #contributors
[9]: https://npm.im/unified

Now all the numeric reference ids flow through the document in ascending order starting from [1]. Nice!

Finally, notice how those reference definitions at the end (specifically the alphanumeric ids) are unordered. Luckily, there exists a remark plugin that will sort all your definitions in whatever order you choose.

remark-reference-links — transform inline links into reference-style links.
remark-sort-definitions — logically reorder reference definitions at the bottom of your document.
remark-remove-unused-definitions — remove unused reference definitions.

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.