remark-sort-definitions

This is a unified (remark) plugin that logically reorders the reference definitions at the bottom of your document depending on your sorting preference. 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.

You might also be interested in remark-reference-links, which transforms all your inline links into reference-style links, and remark-renumber-references, which will contiguously renumber numeric reference-style link ids starting from [1]. For a live example of these plugins in action, check the bottom of this very README.md file. ✨

Install
Usage
API
- Options
Examples
- Using the Default Configuration
- Using algorithm
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-sort-definitions

Usage

Via API

import { read } from 'to-vfile';
import { remark } from 'remark';
import remarkSortDefinitions from 'remark-sort-definitions';

const file = await remark()
  // An options object is NOT required
  .use(remarkSortDefinitions, { algorithm: 'alphanumeric-first' })
  .process(await read('example.md'));

console.log(String(file));

Via remark-cli

remark -o --use sort-definitions README.md

Via unified configuration

In package.json:

  /* … */
  "remarkConfig": {
    "plugins": [
      "remark-sort-definitions"
      /* … */
    ]
  },
  /* … */

In .remarkrc.js:

module.exports = {
  plugins: [
    // …
    ['sort-definitions', { algorithm: 'numeric-first' }]
  ]
};

In .remarkrc.mjs:

import remarkSortDefinitions from 'remark-sort-definitions';

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

API

Detailed interface information can be found under docs/.

Options

This plugin recognizes the following options:

`algorithm`

Valid values: "numeric-first" | "alphanumeric-first"
Default: "alphanumeric-first"

This option determines the sorting preference used when reordering definitions.

numeric-first will put definitions with purely numeric ids first, sorted from least (i.e. 1) to greatest, followed by any remaining definitions sorted naturally.

alphanumeric-first will put definitions with alphanumeric ids (i.e. any id that cannot be parsed into an integer) first, sorted naturally, followed by any remaining definitions sorted from least (i.e. 1) to greatest.

Examples

Suppose we have the following Markdown file example.md:

# Documentation

…

[2nd-half-idiom]: https://meme-link-2
[a-link]: https://a-link
[1st-half-idiom]: https://meme-link-1
[z-link]: https://z-link
[8]: https://npm.im/remark
[1]: https://npm.im/some-package
[5]: #related
[3]: #usage
[6]: #contributing-and-support
[2]: #install
[7]: #contributors

Using the Default Configuration

Then running the following JavaScript:

import { read } from 'to-vfile';
import { remark } from 'remark';
import remarkSortDefinitions from 'remark-sort-definitions';

const file = await remark()
  .use(remarkSortDefinitions)
  // Or:
  //.use(remarkSortDefinitions, { algorithm: 'alphanumeric-first' })
  .process(await read('example.md'));

console.log(String(file));

Would output the following (assuming remark is configured for tight references):

# Documentation

…

[1st-half-idiom]: https://meme-link-1
[2nd-half-idiom]: https://meme-link-2
[a-link]: https://a-link
[z-link]: https://z-link
[1]: https://npm.im/some-package
[2]: #install
[3]: #usage
[5]: #related
[6]: #contributing-and-support
[7]: #contributors
[8]: https://npm.im/remark

Now all the definitions have been sorted. Nice!

Using `algorithm`

We could also sort using an algorithm that places definitions with numeric ids first. Running the follow JavaScript:

import { read } from 'to-vfile';
import { remark } from 'remark';
import remarkSortDefinitions from 'remark-sort-definitions';

const file = await remark()
  .use(remarkSortDefinitions, { algorithm: 'numeric-first' })
  .process(await read('example.md'));

console.log(String(file));

Would output the following (assuming remark is configured for tight references):

# Documentation

…

[1]: https://npm.im/some-package
[2]: #install
[3]: #usage
[5]: #related
[6]: #contributing-and-support
[7]: #contributors
[8]: https://npm.im/remark
[1st-half-idiom]: https://meme-link-1
[2nd-half-idiom]: https://meme-link-2
[a-link]: https://a-link
[z-link]: https://z-link

Finally, notice how those numeric reference definition ids are not contiguous: a definition with id [4] is missing, throwing off the [1] through [8] numbering. Luckily, there exists a remark plugin that will ensure numeric reference ids flow through the document in ascending order starting from [1].

remark-reference-links — transform inline links into reference-style links.
remark-remove-unused-definitions — remove unused reference definitions.
remark-renumber-references — contiguously renumber numeric reference-style link ids starting from [1].

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.