\n\n \n\n# remark-sort-definitions\n\n\n\nThis is a [unified][1] ([remark][2]) plugin that logically reorders the\nreference definitions at the bottom of your document depending on your sorting\npreference. Also plays nicely with [GFM footnotes][3] (by completely ignoring\nthem), and comes with full unicode support.\n\nAfter running this plugin, _all definitions_, both numeric and alphanumeric,\nwill always be placed at the very bottom of the document.\n\nYou might also be interested in [remark-reference-links][4], which transforms\nall your inline links into reference-style links, and\n[remark-renumber-references][5], which will contiguously renumber numeric\nreference-style link ids starting from `[1]`. For a live example of these\nplugins in action, check the bottom of [this very README.md file][6]. ✨\n\n\n\n---\n\n\n\n\n\n\n- [Install](#install)\n- [Usage](#usage)\n - [Via API](#via-api)\n - [Via remark-cli](#via-remark-cli)\n - [Via unified configuration](#via-unified-configuration)\n- [API](#api)\n - [Options](#options)\n- [Examples](#examples)\n - [Using the Default Configuration](#using-the-default-configuration)\n - [Using `algorithm`](#using-algorithm)\n- [Related](#related)\n- [Appendix](#appendix)\n - [Published Package Details](#published-package-details)\n - [License](#license)\n- [Contributing and Support](#contributing-and-support)\n - [Contributors](#contributors)\n\n\n\n\n\n \n\n## Install\n\n> Due to the nature of the unified ecosystem, this package is ESM only and\n> cannot be `require`'d.\n\n\n\nTo install:\n\n```shell\nnpm install --save-dev remark-sort-definitions\n```\n\n## Usage\n\nFor maximum flexibility, there are several ways this plugin can be invoked.\n\n### Via API\n\n```typescript\nimport { read } from 'to-vfile';\nimport { remark } from 'remark';\nimport remarkSortDefinitions from 'remark-sort-definitions';\n\nconst file = await remark()\n // An options object is NOT required\n .use(remarkSortDefinitions, { algorithm: 'alphanumeric-first' })\n .process(await read('example.md'));\n\nconsole.log(String(file));\n```\n\n\n\n### Via [remark-cli](https://xunn.at/docs-remark-cli)\n\n```shell\nremark -o --use sort-definitions README.md\n```\n\n\n\n### Via [unified configuration](https://xunn.at/docs-unified-configuration)\n\nIn `package.json`:\n\n```javascript\n /* … */\n \"remarkConfig\": {\n \"plugins\": [\n \"remark-sort-definitions\"\n /* … */\n ]\n },\n /* … */\n```\n\nIn `.remarkrc.js`:\n\n```javascript\nmodule.exports = {\n plugins: [\n // …\n ['sort-definitions', { algorithm: 'numeric-first' }]\n ]\n};\n```\n\nIn `.remarkrc.mjs`:\n\n```javascript\nimport remarkSortDefinitions from 'remark-sort-definitions';\n\nexport default {\n plugins: [\n // …\n remarkSortDefinitions\n ]\n};\n```\n\n## API\n\nDetailed interface information can be found under [`docs/`][x-repo-docs].\n\n### Options\n\nThis plugin recognizes the following options:\n\n#### `algorithm`\n\nValid values: `\"numeric-first\"` | `\"alphanumeric-first\"`\\\nDefault: `\"alphanumeric-first\"`\n\nThis option determines the sorting preference used when reordering definitions.\n\n`numeric-first` will put definitions with purely numeric ids first, sorted from\nleast (i.e. 1) to greatest, followed by any remaining definitions sorted\n[naturally][7].\n\n`alphanumeric-first` will put definitions with alphanumeric ids (i.e. any id\nthat cannot be parsed into an integer) first, sorted naturally, followed by any\nremaining definitions sorted from least (i.e. 1) to greatest.\n\n## Examples\n\nSuppose we have the following Markdown file `example.md`:\n\n```markdown\n# Documentation\n\n…\n\n[2nd-half-idiom]: https://meme-link-2\n[a-link]: https://a-link\n[1st-half-idiom]: https://meme-link-1\n[z-link]: https://z-link\n[8]: https://npm.im/remark\n[1]: https://npm.im/some-package\n[5]: #related\n[3]: #usage\n[6]: #contributing-and-support\n[2]: #install\n[7]: #contributors\n```\n\n### Using the Default Configuration\n\nThen running the following JavaScript:\n\n```typescript\nimport { read } from 'to-vfile';\nimport { remark } from 'remark';\nimport remarkSortDefinitions from 'remark-sort-definitions';\n\nconst file = await remark()\n .use(remarkSortDefinitions)\n // Or:\n //.use(remarkSortDefinitions, { algorithm: 'alphanumeric-first' })\n .process(await read('example.md'));\n\nconsole.log(String(file));\n```\n\nWould output the following (assuming remark is [configured][8] for tight\nreferences):\n\n```markdown\n# Documentation\n\n…\n\n[1st-half-idiom]: https://meme-link-1\n[2nd-half-idiom]: https://meme-link-2\n[a-link]: https://a-link\n[z-link]: https://z-link\n[1]: https://npm.im/some-package\n[2]: #install\n[3]: #usage\n[5]: #related\n[6]: #contributing-and-support\n[7]: #contributors\n[8]: https://npm.im/remark\n```\n\nNow all the definitions have been sorted. Nice!\n\n### Using `algorithm`\n\nWe could also sort using an algorithm that places definitions with numeric ids\nfirst. Running the follow JavaScript:\n\n```typescript\nimport { read } from 'to-vfile';\nimport { remark } from 'remark';\nimport remarkSortDefinitions from 'remark-sort-definitions';\n\nconst file = await remark()\n .use(remarkSortDefinitions, { algorithm: 'numeric-first' })\n .process(await read('example.md'));\n\nconsole.log(String(file));\n```\n\nWould output the following (assuming remark is [configured][8] for tight\nreferences):\n\n```markdown\n# Documentation\n\n…\n\n[1]: https://npm.im/some-package\n[2]: #install\n[3]: #usage\n[5]: #related\n[6]: #contributing-and-support\n[7]: #contributors\n[8]: https://npm.im/remark\n[1st-half-idiom]: https://meme-link-1\n[2nd-half-idiom]: https://meme-link-2\n[a-link]: https://a-link\n[z-link]: https://z-link\n```\n\nFinally, notice how those numeric reference definition ids are not contiguous: a\ndefinition with id `[4]` is missing, throwing off the `[1]` through `[8]`\nnumbering. Luckily, there exists [a remark plugin][5] that will ensure numeric\nreference ids flow through the document in ascending order starting from `[1]`.\n\n## Related\n\n- [remark-reference-links][4] — transform inline links into reference-style\n links.\n- [remark-remove-unused-definitions][9] — remove unused reference definitions.\n- [remark-renumber-references][5] — contiguously renumber numeric\n reference-style link ids starting from `[1]`.\n\n\n\n## Appendix\n\n\n\nFurther documentation can be found under [`docs/`][x-repo-docs].\n\n\n\n\n### Published Package Details\n\nThis is an [ESM-only package][x-pkg-esm-wine] built by Babel for use in Node.js\nversions that are not end-of-life. For TypeScript users, this package supports\nboth `\"Node10\"` and `\"Node16\"` module resolution strategies.\n\n\n\n\n\nExpand details\n\nThat means ESM source will load this package via `import { ... } from ...` or\n`await import(...)` and CJS source will load this package via dynamic\n`import()`. This has several benefits, the foremost being: less code\nshipped/smaller package size, avoiding [dual package\nhazard][x-pkg-dual-package-hazard] entirely, distributables are not\npacked/bundled/uglified, and a drastically less complex build process.\n\nThe glaring downside, which may or may not be relevant, is that CJS consumers\ncannot `require()` this package and can only use `import()` in an asynchronous\ncontext. This means, in effect, CJS consumers may not be able to use this\npackage at all.\n\nEach entry point (i.e. `ENTRY`) in [`package.json`'s\n`exports[ENTRY]`][x-repo-package-json] object includes one or more [export\nconditions][x-pkg-exports-conditions]. These entries may or may not include: an\n[`exports[ENTRY].types`][x-pkg-exports-types-key] condition pointing to a type\ndeclaration file for TypeScript and IDEs, a\n[`exports[ENTRY].module`][x-pkg-exports-module-key] condition pointing to\n(usually ESM) source for Webpack/Rollup, a `exports[ENTRY].node` and/or\n`exports[ENTRY].default` condition pointing to (usually CJS2) source for Node.js\n`require`/`import` and for browsers and other environments, and [other\nconditions][x-pkg-exports-conditions] not enumerated here. Check the\n[package.json][x-repo-package-json] file to see which export conditions are\nsupported.\n\nNote that, regardless of the [`{ \"type\": \"...\" }`][x-pkg-type] specified in\n[`package.json`][x-repo-package-json], any JavaScript files written in ESM\nsyntax (including distributables) will always have the `.mjs` extension. Note\nalso that [`package.json`][x-repo-package-json] may include the\n[`sideEffects`][x-pkg-side-effects-key] key, which is almost always `false` for\noptimal [tree shaking][x-pkg-tree-shaking] where appropriate.\n\n\n\n\n\n\n\n### License\n\n\n\nSee [LICENSE][x-repo-license].\n\n\n\n\n## Contributing and Support\n\n**[New issues][x-repo-choose-new-issue] and [pull requests][x-repo-pr-compare]\nare always welcome and greatly appreciated! 🤩** Just as well, you can [star 🌟\nthis project][x-badge-repo-link] to let me know you found it useful! ✊🏿 Or [buy\nme a beer][x-repo-sponsor], I'd appreciate it. Thank you!\n\nSee [CONTRIBUTING.md][x-repo-contributing] and [SUPPORT.md][x-repo-support] for\nmore information.\n\n\n\n\n\n### Contributors\n\n\n\n\n\n\n\nSee the [table of contributors][x-repo-contributors].\n\n\n\n[x-badge-blm-image]: https://xunn.at/badge-blm 'Join the movement!'\n[x-badge-blm-link]: https://xunn.at/donate-blm\n[x-badge-codecov-image]:\n https://img.shields.io/codecov/c/github/Xunnamius/unified-utils/main?style=flat-square&token=HWRIOBAAPW&flag=package.main_remark-sort-definitions\n 'Is this package well-tested?'\n[x-badge-codecov-link]: https://codecov.io/gh/Xunnamius/unified-utils\n[x-badge-downloads-image]:\n https://img.shields.io/npm/dm/remark-sort-definitions?style=flat-square\n 'Number of times this package has been downloaded per month'\n[x-badge-downloads-link]: https://npmtrends.com/remark-sort-definitions\n[x-badge-lastcommit-image]:\n https://img.shields.io/github/last-commit/Xunnamius/unified-utils?style=flat-square\n 'Latest commit timestamp'\n[x-badge-license-image]:\n https://img.shields.io/npm/l/remark-sort-definitions?style=flat-square\n \"This package's source license\"\n[x-badge-license-link]:\n https://github.com/Xunnamius/unified-utils/blob/main/LICENSE\n[x-badge-npm-image]:\n https://xunn.at/npm-pkg-version/remark-sort-definitions\n 'Install this package using npm or yarn!'\n[x-badge-npm-link]: https://npm.im/remark-sort-definitions\n[x-badge-repo-link]: https://github.com/Xunnamius/unified-utils\n[x-badge-semanticrelease-image]:\n https://xunn.at/badge-semantic-release\n 'This repo practices continuous integration and deployment!'\n[x-badge-semanticrelease-link]:\n https://github.com/semantic-release/semantic-release\n[x-pkg-dual-package-hazard]:\n https://nodejs.org/api/packages.html#dual-package-hazard\n[x-pkg-esm-wine]:\n https://dev.to/jakobjingleheimer/configuring-commonjs-es-modules-for-nodejs-12ed#esm-source-and-distribution\n[x-pkg-exports-conditions]:\n https://webpack.js.org/guides/package-exports#reference-syntax\n[x-pkg-exports-module-key]:\n https://webpack.js.org/guides/package-exports#providing-commonjs-and-esm-version-stateless\n[x-pkg-exports-types-key]:\n https://devblogs.microsoft.com/typescript/announcing-typescript-4-5-beta#packagejson-exports-imports-and-self-referencing\n[x-pkg-side-effects-key]:\n https://webpack.js.org/guides/tree-shaking#mark-the-file-as-side-effect-free\n[x-pkg-tree-shaking]: https://webpack.js.org/guides/tree-shaking\n[x-pkg-type]:\n https://github.com/nodejs/node/blob/8d8e06a345043bec787e904edc9a2f5c5e9c275f/doc/api/packages.md#type\n[x-repo-choose-new-issue]:\n https://github.com/Xunnamius/unified-utils/issues/new/choose\n[x-repo-contributing]: /CONTRIBUTING.md\n[x-repo-contributors]: /README.md#contributors\n[x-repo-docs]: docs\n[x-repo-license]: ./LICENSE\n[x-repo-package-json]: package.json\n[x-repo-pr-compare]: https://github.com/Xunnamius/unified-utils/compare\n[x-repo-sponsor]: https://github.com/sponsors/Xunnamius\n[x-repo-support]: /.github/SUPPORT.md\n[1]: https://github.com/unifiedjs/unified\n[2]: https://github.com/remarkjs/remark\n[3]: https://github.com/remarkjs/remark-gfm#what-is-this\n[4]: https://github.com/remarkjs/remark-reference-links\n[5]: /packages/remark-renumber-references\n[6]:\n https://raw.githubusercontent.com/Xunnamius/unified-utils/main/packages/remark-sort-definitions/README.md\n[7]: https://en.wikipedia.org/wiki/Natural_sort_order\n[8]: /.remarkrc.mjs\n[9]: /packages/remark-remove-unused-definitions\n","readmeFilename":"README.md"}
![](\"https://raw.githubusercontent.com/Xunnamius/unified-utils/refs/heads/main/packages/remark-sort-definitions/logo.png\"){kind=logo}
\n