tools,doc: Enforce alphabetical order in Markdown files

doc/api/inspector.md

@@ -239,8 +239,8 @@ session.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => {
 });
 ```
 
-[`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused
-[`session.connect()`]: #inspector_session_connect
 [CPU Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/Profiler
 [Chrome DevTools Protocol Viewer]: https://chromedevtools.github.io/devtools-protocol/v8/
 [Heap Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler
+[`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused
+[`session.connect()`]: #inspector_session_connect

doc/api/punycode.md

@@ -148,5 +148,5 @@ added: v0.6.1
 
 Returns a string identifying the current [Punycode.js][] version number.
 
-[Punycode.js]: https://github.com/bestiejs/punycode.js
 [Punycode]: https://tools.ietf.org/html/rfc3492
+[Punycode.js]: https://github.com/bestiejs/punycode.js

doc/api/wasi.md

@@ -162,6 +162,6 @@ added:
 should be passed as the `wasi_snapshot_preview1` import during the instantiation
 of a [`WebAssembly.Instance`][].
 
+[WebAssembly System Interface]: https://wasi.dev/
 [`WebAssembly.Instance`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance
 [`WebAssembly.Memory`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory
-[WebAssembly System Interface]: https://wasi.dev/

doc/guides/backporting-to-release-lines.md

@@ -89,6 +89,6 @@ replace that with the staging branch for the targeted release line.
 After the pull request lands, replace the `backport-requested-v10.x` label
 on the original pull request with `backported-to-v10.x`.
 
-[Release Schedule]: https://github.com/nodejs/Release#release-schedule1
 [Release Plan]: https://github.com/nodejs/Release#release-plan
+[Release Schedule]: https://github.com/nodejs/Release#release-schedule1
 [`node-test-pull-request`]: https://ci.nodejs.org/job/node-test-pull-request/build

doc/guides/collaborator-guide.md

@@ -771,10 +771,10 @@ If you cannot find who to cc for a file, `git shortlog -n -s <file>` can help.
 [backporting guide]: backporting-to-release-lines.md
 [commit message guidelines]: contributing/pull-requests.md#commit-message-guidelines
 [commit-example]: https://github.com/nodejs/node/commit/b636ba8186
+[git-email]: https://help.github.com/articles/setting-your-commit-email-address-in-git/
 [git-node]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md
 [git-node-metadata]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-metadata
 [git-username]: https://help.github.com/articles/setting-your-username-in-git/
-[git-email]: https://help.github.com/articles/setting-your-commit-email-address-in-git/
 [node-core-utils-credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials
 [node-core-utils-issues]: https://github.com/nodejs/node-core-utils/issues
 [unreliable tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+flaky+test%22

doc/guides/contributing/pull-requests.md

@@ -593,15 +593,15 @@ widely used, so don't be discouraged!
 If you want to know more about the code review and the landing process, see the
 [Collaborator Guide][].
 
-[approved]: #getting-approvals-for-your-pull-request
-[benchmark results]: ../writing-and-running-benchmarks.md
 [Building guide]: ../../../BUILDING.md
 [CI (Continuous Integration) test run]: #ci-testing
 [Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md
 [Collaborator Guide]: ../collaborator-guide.md
+[IRC in the #node-dev channel]: https://webchat.freenode.net?channels=node-dev&uio=d4
+[Onboarding guide]: ../../../onboarding.md
+[approved]: #getting-approvals-for-your-pull-request
+[benchmark results]: ../writing-and-running-benchmarks.md
 [guide for writing tests in Node.js]: ../writing-tests.md
 [hiding-a-comment]: https://help.github.com/articles/managing-disruptive-comments/#hiding-a-comment
 [https://ci.nodejs.org/]: https://ci.nodejs.org/
-[IRC in the #node-dev channel]: https://webchat.freenode.net?channels=node-dev&uio=d4
-[Onboarding guide]: ../../../onboarding.md
 [running tests]: ../../../BUILDING.md#running-tests

doc/guides/cpp-style-guide.md

@@ -392,15 +392,15 @@ Node.js is built [without C++ exception handling][], so code using `throw` or
 even `try` and `catch` **will** break.
 
 [C++ Core Guidelines]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines
-[Google C++ Style Guide]: https://google.github.io/styleguide/cppguide.html
-[Google’s `cpplint`]: https://github.com/google/styleguide
-[errors]: https://github.com/nodejs/node/blob/master/doc/guides/using-internal-errors.md
 [ES.47]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-nullptr
 [ES.48]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts
 [ES.49]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts-named
+[Google C++ Style Guide]: https://google.github.io/styleguide/cppguide.html
+[Google’s `cpplint`]: https://github.com/google/styleguide
 [R.20]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-owner
 [R.21]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-unique
 [Run Time Type Information]: https://en.wikipedia.org/wiki/Run-time_type_information
+[aliased_buffer.h]: https://github.com/nodejs/node/blob/master/src/aliased_buffer.h#L12
 [cppref_auto_ptr]: https://en.cppreference.com/w/cpp/memory/auto_ptr
+[errors]: https://github.com/nodejs/node/blob/master/doc/guides/using-internal-errors.md
 [without C++ exception handling]: https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_exceptions.html#intro.using.exception.no
-[aliased_buffer.h]: https://github.com/nodejs/node/blob/master/src/aliased_buffer.h#L12

doc/guides/maintaining-V8.md

@@ -415,8 +415,8 @@ This would require some tooling to:
 as their support has ended.
 
 [ChromiumReleaseCalendar]: https://www.chromium.org/developers/calendar
-[Node.js `canary` branch]: https://github.com/nodejs/node-v8/tree/canary
 [Node.js CI]: https://ci.nodejs.org/job/node-test-pull-request/
+[Node.js `canary` branch]: https://github.com/nodejs/node-v8/tree/canary
 [NodeJS-Backport-Approved-Chromium]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3ANodeJS-Backport-Approved
 [NodeJS-Backport-Approved-V8]: https://bugs.chromium.org/p/v8/issues/list?can=1&q=label%3ANodeJS-Backport-Approved
 [NodeJS-Backport-Done-Chromium]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3ANodeJS-Backport-Done
@@ -425,10 +425,10 @@ as their support has ended.
 [NodeJS-Backport-Rejected-V8]: https://bugs.chromium.org/p/v8/issues/list?can=1&q=label%3ANodeJS-Backport-Rejected
 [NodeJS-Backport-Review-Chromium]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3ANodeJS-Backport-Review
 [NodeJS-Backport-Review-V8]: https://bugs.chromium.org/p/v8/issues/list?can=1&q=label%3ANodeJS-Backport-Review
-[`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-v8
 [V8 CI]: https://ci.nodejs.org/job/node-test-commit-v8-linux/
 [V8ActiveBranches]: https://build.chromium.org/p/client.v8.branches/console
 [V8Contributing]: https://github.com/v8/v8/wiki/Contributing
 [V8MergingPatching]: https://github.com/v8/v8/wiki/Merging%20&%20Patching
 [V8TemplateMergeRequest]: https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20merge%20request
 [V8TemplateUpstreamBug]: https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20upstream%20bug
+[`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-v8

doc/guides/maintaining-icu.md

@@ -261,8 +261,8 @@ Node.js (see the top level README.md). Only modifying `icu-small` would cause
 the patch not to be landed in case the user specifies the ICU source code
 another way.
 
+[CLDR]: https://unicode.org/cldr
+[Ecma402]: https://github.com/tc39/ecma402
 [ICU]: http://icu-project.org
 [Unicode]: https://unicode.org
 [tz]: https://www.iana.org/time-zones
-[CLDR]: https://unicode.org/cldr
-[Ecma402]: https://github.com/tc39/ecma402

doc/guides/releases.md

@@ -869,9 +869,9 @@ test, or doc-related are to be listed as notable changes. Some SEMVER-MINOR
 commits may be listed as notable changes on a case-by-case basis. Use your
 judgment there.
 
-[CI lockdown procedure]: https://github.com/nodejs/build/blob/master/doc/jenkins-guide.md#restricting-access-for-security-releases
 [Build issue tracker]: https://github.com/nodejs/build/issues/new
+[CI lockdown procedure]: https://github.com/nodejs/build/blob/master/doc/jenkins-guide.md#restricting-access-for-security-releases
+[Partner Communities]: https://github.com/nodejs/community-committee/blob/master/governance/PARTNER_COMMUNITIES.md
 [nodejs.org release-post.js script]: https://github.com/nodejs/nodejs.org/blob/master/scripts/release-post.js
 [nodejs.org repository]: https://github.com/nodejs/nodejs.org
-[Partner Communities]: https://github.com/nodejs/community-committee/blob/master/governance/PARTNER_COMMUNITIES.md
 [webchat.freenode.net]: https://webchat.freenode.net/

doc/guides/writing-and-running-benchmarks.md

@@ -551,8 +551,8 @@ Supported options keys are:
   benchmarker
 
 [autocannon]: https://github.com/mcollina/autocannon
-[wrk]: https://github.com/wg/wrk
-[t-test]: https://en.wikipedia.org/wiki/Student%27s_t-test#Equal_or_unequal_sample_sizes.2C_unequal_variances
+[benchmark-ci]: https://github.com/nodejs/benchmarking/blob/master/docs/core_benchmarks.md
 [git-for-windows]: https://git-scm.com/download/win
 [nghttp2.org]: https://nghttp2.org
-[benchmark-ci]: https://github.com/nodejs/benchmarking/blob/master/docs/core_benchmarks.md
+[t-test]: https://en.wikipedia.org/wiki/Student%27s_t-test#Equal_or_unequal_sample_sizes.2C_unequal_variances
+[wrk]: https://github.com/wg/wrk

doc/guides/writing-tests.md

@@ -434,9 +434,9 @@ Nightly coverage reports for the Node.js master branch are available at
 
 [ASCII]: https://man7.org/linux/man-pages/man7/ascii.7.html
 [Google Test]: https://github.com/google/googletest
+[Test Coverage section of the Building guide]: https://github.com/nodejs/node/blob/master/BUILDING.md#running-coverage
 [`common` module]: https://github.com/nodejs/node/blob/master/test/common/README.md
 [all maintained branches]: https://github.com/nodejs/lts
+[directory structure overview]: https://github.com/nodejs/node/blob/master/test/README.md#test-directories
 [node.green]: https://node.green/
 [test fixture]: https://github.com/google/googletest/blob/master/googletest/docs/Primer.md#test-fixtures-using-the-same-data-configuration-for-multiple-tests
-[Test Coverage section of the Building guide]: https://github.com/nodejs/node/blob/master/BUILDING.md#running-coverage
-[directory structure overview]: https://github.com/nodejs/node/blob/master/test/README.md#test-directories

onboarding.md

@@ -245,12 +245,12 @@ needs to be pointed out separately during the onboarding.
   the [summit](https://github.com/nodejs/summit) repository for details.
 
 [Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md
+[Landing Pull Requests]: doc/guides/collaborator-guide.md#landing-pull-requests
+[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/
 [`author-ready`]: doc/guides/collaborator-guide.md#author-ready-pull-requests
 [`core-validate-commit`]: https://github.com/nodejs/core-validate-commit
 [`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md
 [`node-core-utils`]: https://github.com/nodejs/node-core-utils
-[Landing Pull Requests]: doc/guides/collaborator-guide.md#landing-pull-requests
-[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/
 [set up the credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials
 [two-factor authentication]: https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/
 [using a TOTP mobile app]: https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/

src/README.md

@@ -929,6 +929,10 @@ static void GetUserInfo(const FunctionCallbackInfo<Value>& args) {
 }
 ```
 
+[C++ coding style]: ../doc/guides/cpp-style-guide.md
+[Callback scopes]: #callback-scopes
+[JavaScript value handles]: #js-handles
+[N-API]: https://nodejs.org/api/n-api.html
 [`BaseObject`]: #baseobject
 [`Context`]: #context
 [`Environment`]: #environment
@@ -951,10 +955,6 @@ static void GetUserInfo(const FunctionCallbackInfo<Value>& args) {
 [`v8.h` in Node.js master]: https://github.com/nodejs/node/blob/master/deps/v8/include/v8.h
 [`v8.h` in V8 master]: https://github.com/v8/v8/blob/master/include/v8.h
 [`vm` module]: https://nodejs.org/api/vm.html
-[C++ coding style]: ../doc/guides/cpp-style-guide.md
-[Callback scopes]: #callback-scopes
-[JavaScript value handles]: #js-handles
-[N-API]: https://nodejs.org/api/n-api.html
 [binding function]: #binding-functions
 [cleanup hooks]: #cleanup-hooks
 [event loop]: #event-loop

test/wpt/README.md

@@ -164,5 +164,5 @@ Web API, or certain harness has not been ported in our test runner yet.
 In that case it needs to be marked with `skip` instead of `fail`.
 
 [Web Platform Tests]: https://github.com/web-platform-tests/wpt
-[git node wpt]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-wpt
 [`test/fixtures/wpt/README.md`]: ../fixtures/wpt/README.md
+[git node wpt]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-wpt

tools/doc/checkLinks.js

@@ -27,11 +27,12 @@ function findMarkdownFilesRecursively(dirPath) {
     if (
       entry.isDirectory() &&
       entry.name !== 'api' &&
-      entry.name !== 'tmp' &&
-      entry.name !== 'fixtures' &&
       entry.name !== 'changelogs' &&
       entry.name !== 'deps' &&
-      entry.name !== 'node_modules'
+      entry.name !== 'fixtures' &&
+      entry.name !== 'node_modules' &&
+      entry.name !== 'out' &&
+      entry.name !== 'tmp'
     ) {
       findMarkdownFilesRecursively(path);
     } else if (entry.isFile() && extname(entry.name) === '.md') {
@@ -46,6 +47,7 @@ function checkFile(path) {
     .parse(fs.readFileSync(path));
 
   const base = pathToFileURL(path);
+  let previousDefinitionLabel;
   for (const node of getLinksRecursively(tree)) {
     const targetURL = new URL(node.url, base);
     if (targetURL.protocol === 'file:' && !fs.existsSync(targetURL)) {
@@ -55,5 +57,18 @@ function checkFile(path) {
         `Broken link at ${path}:${line}:${column} (${node.url})`);
       process.exitCode = 1;
     }
+    if (node.type === 'definition') {
+      if (previousDefinitionLabel &&
+          previousDefinitionLabel > node.label) {
+        const { line, column } = node.position.start;
+        console.error((process.env.GITHUB_ACTIONS ?
+          `::error file=${path},line=${line},col=${column}::` : '') +
+          `Unordered reference at ${path}:${line}:${column} (` +
+          `"${node.label}" should be before "${previousDefinitionLabel})"`
+        );
+        process.exitCode = 1;
+      }
+      previousDefinitionLabel = node.label;
+    }
   }
 }

tools/doc/generate.js

@@ -87,7 +87,7 @@ async function main() {
     .use(html.firstHeader)
     .use(html.preprocessElements, { filename })
     .use(html.buildToc, { filename, apilinks })
-    .use(remark2rehype, { allowDangerousHTML: true })
+    .use(remark2rehype, { allowDangerousHtml: true })
     .use(raw)
     .use(htmlStringify)
     .process(input);

tools/doc/html.js

@@ -54,7 +54,7 @@ const gtocPath = path.join(docPath, 'api', 'index.md');
 const gtocMD = fs.readFileSync(gtocPath, 'utf8').replace(/^<!--.*?-->/gms, '');
 const gtocHTML = unified()
   .use(markdown)
-  .use(remark2rehype, { allowDangerousHTML: true })
+  .use(remark2rehype, { allowDangerousHtml: true })
   .use(raw)
   .use(navClasses)
   .use(htmlStringify)
@@ -281,7 +281,7 @@ function parseYAML(text) {
     meta.changes.forEach((change) => {
       const description = unified()
         .use(markdown)
-        .use(remark2rehype, { allowDangerousHTML: true })
+        .use(remark2rehype, { allowDangerousHtml: true })
         .use(raw)
         .use(htmlStringify)
         .processSync(change.description).toString();
@@ -379,7 +379,7 @@ function buildToc({ filename, apilinks }) {
 
     file.toc = unified()
       .use(markdown)
-      .use(remark2rehype, { allowDangerousHTML: true })
+      .use(remark2rehype, { allowDangerousHtml: true })
       .use(raw)
       .use(htmlStringify)
       .processSync(toc).toString();

tools/doc/json.js

@@ -24,7 +24,7 @@
 const unified = require('unified');
 const common = require('./common.js');
 const html = require('remark-html');
-const select = require('unist-util-select');
+const { selectAll } = require('unist-util-select');
 
 module.exports = { jsonAPI };
 
@@ -38,7 +38,7 @@ function jsonAPI({ filename }) {
     const stabilityExpr = /^Stability: ([0-5])(?:\s*-\s*)?(.*)$/s;
 
     // Extract definitions.
-    const definitions = select(tree, 'definition');
+    const definitions = selectAll('definition', tree);
 
     // Determine the start, stop, and depth of each section.
     const sections = [];