Skip to content

Commit f297174

Browse files
aduh95MylesBorins
aduh95
authored and
MylesBorins
committed
tools,doc: enforce alphabetical order for md refs
PR-URL: #35244 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Shelley Vohr <[email protected]>
1 parent 11b10d7 commit f297174

15 files changed

+48
-33
lines changed

‎doc/api/inspector.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -239,8 +239,8 @@ session.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => {
239239
});
240240
```
241241

242-
[`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused
243-
[`session.connect()`]: #inspector_session_connect
244242
[CPU Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/Profiler
245243
[Chrome DevTools Protocol Viewer]: https://chromedevtools.github.io/devtools-protocol/v8/
246244
[Heap Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler
245+
[`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused
246+
[`session.connect()`]: #inspector_session_connect

‎doc/api/punycode.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,5 +148,5 @@ added: v0.6.1
148148

149149
Returns a string identifying the current [Punycode.js][] version number.
150150

151-
[Punycode.js]: https://github.com/bestiejs/punycode.js
152151
[Punycode]: https://tools.ietf.org/html/rfc3492
152+
[Punycode.js]: https://github.com/bestiejs/punycode.js

‎doc/api/wasi.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,6 @@ added: v12.16.0
154154
should be passed as the `wasi_snapshot_preview1` import during the instantiation
155155
of a [`WebAssembly.Instance`][].
156156

157+
[WebAssembly System Interface]: https://wasi.dev/
157158
[`WebAssembly.Instance`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance
158159
[`WebAssembly.Memory`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory
159-
[WebAssembly System Interface]: https://wasi.dev/

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,6 @@ replace that with the staging branch for the targeted release line.
8989
After the pull request lands, replace the `backport-requested-v10.x` label
9090
on the original pull request with `backported-to-v10.x`.
9191

92-
[Release Schedule]: https://github.com/nodejs/Release#release-schedule1
9392
[Release Plan]: https://github.com/nodejs/Release#release-plan
93+
[Release Schedule]: https://github.com/nodejs/Release#release-schedule1
9494
[`node-test-pull-request`]: https://ci.nodejs.org/job/node-test-pull-request/build

‎doc/guides/collaborator-guide.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -771,10 +771,10 @@ If you cannot find who to cc for a file, `git shortlog -n -s <file>` can help.
771771
[backporting guide]: backporting-to-release-lines.md
772772
[commit message guidelines]: contributing/pull-requests.md#commit-message-guidelines
773773
[commit-example]: https://github.com/nodejs/node/commit/b636ba8186
774+
[git-email]: https://help.github.com/articles/setting-your-commit-email-address-in-git/
774775
[git-node]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md
775776
[git-node-metadata]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-metadata
776777
[git-username]: https://help.github.com/articles/setting-your-username-in-git/
777-
[git-email]: https://help.github.com/articles/setting-your-commit-email-address-in-git/
778778
[node-core-utils-credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials
779779
[node-core-utils-issues]: https://github.com/nodejs/node-core-utils/issues
780780
[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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -593,15 +593,15 @@ widely used, so don't be discouraged!
593593
If you want to know more about the code review and the landing process, see the
594594
[Collaborator Guide][].
595595

596-
[approved]: #getting-approvals-for-your-pull-request
597-
[benchmark results]: ../writing-and-running-benchmarks.md
598596
[Building guide]: ../../../BUILDING.md
599597
[CI (Continuous Integration) test run]: #ci-testing
600598
[Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md
601599
[Collaborator Guide]: ../collaborator-guide.md
600+
[IRC in the #node-dev channel]: https://webchat.freenode.net?channels=node-dev&uio=d4
601+
[Onboarding guide]: ../../../onboarding.md
602+
[approved]: #getting-approvals-for-your-pull-request
603+
[benchmark results]: ../writing-and-running-benchmarks.md
602604
[guide for writing tests in Node.js]: ../writing-tests.md
603605
[hiding-a-comment]: https://help.github.com/articles/managing-disruptive-comments/#hiding-a-comment
604606
[https://ci.nodejs.org/]: https://ci.nodejs.org/
605-
[IRC in the #node-dev channel]: https://webchat.freenode.net?channels=node-dev&uio=d4
606-
[Onboarding guide]: ../../../onboarding.md
607607
[running tests]: ../../../BUILDING.md#running-tests

‎doc/guides/cpp-style-guide.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -392,15 +392,15 @@ Node.js is built [without C++ exception handling][], so code using `throw` or
392392
even `try` and `catch` **will** break.
393393

394394
[C++ Core Guidelines]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines
395-
[Google C++ Style Guide]: https://google.github.io/styleguide/cppguide.html
396-
[Google’s `cpplint`]: https://github.com/google/styleguide
397-
[errors]: https://github.com/nodejs/node/blob/master/doc/guides/using-internal-errors.md
398395
[ES.47]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-nullptr
399396
[ES.48]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts
400397
[ES.49]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts-named
398+
[Google C++ Style Guide]: https://google.github.io/styleguide/cppguide.html
399+
[Google’s `cpplint`]: https://github.com/google/styleguide
401400
[R.20]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-owner
402401
[R.21]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-unique
403402
[Run Time Type Information]: https://en.wikipedia.org/wiki/Run-time_type_information
403+
[aliased_buffer.h]: https://github.com/nodejs/node/blob/master/src/aliased_buffer.h#L12
404404
[cppref_auto_ptr]: https://en.cppreference.com/w/cpp/memory/auto_ptr
405+
[errors]: https://github.com/nodejs/node/blob/master/doc/guides/using-internal-errors.md
405406
[without C++ exception handling]: https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_exceptions.html#intro.using.exception.no
406-
[aliased_buffer.h]: https://github.com/nodejs/node/blob/master/src/aliased_buffer.h#L12

‎doc/guides/maintaining-V8.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -411,8 +411,8 @@ This would require some tooling to:
411411
as their support has ended.
412412

413413
[ChromiumReleaseCalendar]: https://www.chromium.org/developers/calendar
414-
[Node.js `canary` branch]: https://github.com/nodejs/node-v8/tree/canary
415414
[Node.js CI]: https://ci.nodejs.org/job/node-test-pull-request/
415+
[Node.js `canary` branch]: https://github.com/nodejs/node-v8/tree/canary
416416
[NodeJS-Backport-Approved-Chromium]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3ANodeJS-Backport-Approved
417417
[NodeJS-Backport-Approved-V8]: https://bugs.chromium.org/p/v8/issues/list?can=1&q=label%3ANodeJS-Backport-Approved
418418
[NodeJS-Backport-Done-Chromium]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3ANodeJS-Backport-Done
@@ -421,10 +421,10 @@ as their support has ended.
421421
[NodeJS-Backport-Rejected-V8]: https://bugs.chromium.org/p/v8/issues/list?can=1&q=label%3ANodeJS-Backport-Rejected
422422
[NodeJS-Backport-Review-Chromium]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3ANodeJS-Backport-Review
423423
[NodeJS-Backport-Review-V8]: https://bugs.chromium.org/p/v8/issues/list?can=1&q=label%3ANodeJS-Backport-Review
424-
[`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-v8
425424
[V8 CI]: https://ci.nodejs.org/job/node-test-commit-v8-linux/
426425
[V8ActiveBranches]: https://build.chromium.org/p/client.v8.branches/console
427426
[V8Contributing]: https://github.com/v8/v8/wiki/Contributing
428427
[V8MergingPatching]: https://github.com/v8/v8/wiki/Merging%20&%20Patching
429428
[V8TemplateMergeRequest]: https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20merge%20request
430429
[V8TemplateUpstreamBug]: https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20upstream%20bug
430+
[`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-v8

‎doc/guides/releases.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -866,9 +866,9 @@ test, or doc-related are to be listed as notable changes. Some SEMVER-MINOR
866866
commits may be listed as notable changes on a case-by-case basis. Use your
867867
judgment there.
868868

869-
[CI lockdown procedure]: https://github.com/nodejs/build/blob/master/doc/jenkins-guide.md#restricting-access-for-security-releases
870869
[Build issue tracker]: https://github.com/nodejs/build/issues/new
870+
[CI lockdown procedure]: https://github.com/nodejs/build/blob/master/doc/jenkins-guide.md#restricting-access-for-security-releases
871+
[Partner Communities]: https://github.com/nodejs/community-committee/blob/master/governance/PARTNER_COMMUNITIES.md
871872
[nodejs.org release-post.js script]: https://github.com/nodejs/nodejs.org/blob/master/scripts/release-post.js
872873
[nodejs.org repository]: https://github.com/nodejs/nodejs.org
873-
[Partner Communities]: https://github.com/nodejs/community-committee/blob/master/governance/PARTNER_COMMUNITIES.md
874874
[webchat.freenode.net]: https://webchat.freenode.net/

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -551,8 +551,8 @@ Supported options keys are:
551551
benchmarker
552552

553553
[autocannon]: https://github.com/mcollina/autocannon
554-
[wrk]: https://github.com/wg/wrk
555-
[t-test]: https://en.wikipedia.org/wiki/Student%27s_t-test#Equal_or_unequal_sample_sizes.2C_unequal_variances
554+
[benchmark-ci]: https://github.com/nodejs/benchmarking/blob/master/docs/core_benchmarks.md
556555
[git-for-windows]: https://git-scm.com/download/win
557556
[nghttp2.org]: https://nghttp2.org
558-
[benchmark-ci]: https://github.com/nodejs/benchmarking/blob/master/docs/core_benchmarks.md
557+
[t-test]: https://en.wikipedia.org/wiki/Student%27s_t-test#Equal_or_unequal_sample_sizes.2C_unequal_variances
558+
[wrk]: https://github.com/wg/wrk

‎doc/guides/writing-tests.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -434,9 +434,9 @@ Nightly coverage reports for the Node.js master branch are available at
434434

435435
[ASCII]: https://man7.org/linux/man-pages/man7/ascii.7.html
436436
[Google Test]: https://github.com/google/googletest
437+
[Test Coverage section of the Building guide]: https://github.com/nodejs/node/blob/master/BUILDING.md#running-coverage
437438
[`common` module]: https://github.com/nodejs/node/blob/master/test/common/README.md
438439
[all maintained branches]: https://github.com/nodejs/lts
440+
[directory structure overview]: https://github.com/nodejs/node/blob/master/test/README.md#test-directories
439441
[node.green]: https://node.green/
440442
[test fixture]: https://github.com/google/googletest/blob/master/googletest/docs/Primer.md#test-fixtures-using-the-same-data-configuration-for-multiple-tests
441-
[Test Coverage section of the Building guide]: https://github.com/nodejs/node/blob/master/BUILDING.md#running-coverage
442-
[directory structure overview]: https://github.com/nodejs/node/blob/master/test/README.md#test-directories

‎onboarding.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -245,12 +245,12 @@ needs to be pointed out separately during the onboarding.
245245
the [summit](https://github.com/nodejs/summit) repository for details.
246246

247247
[Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md
248+
[Landing Pull Requests]: doc/guides/collaborator-guide.md#landing-pull-requests
249+
[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/
248250
[`author-ready`]: doc/guides/collaborator-guide.md#author-ready-pull-requests
249251
[`core-validate-commit`]: https://github.com/nodejs/core-validate-commit
250252
[`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md
251253
[`node-core-utils`]: https://github.com/nodejs/node-core-utils
252-
[Landing Pull Requests]: doc/guides/collaborator-guide.md#landing-pull-requests
253-
[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/
254254
[set up the credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials
255255
[two-factor authentication]: https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/
256256
[using a TOTP mobile app]: https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/

‎src/README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -881,6 +881,10 @@ static void GetUserInfo(const FunctionCallbackInfo<Value>& args) {
881881
}
882882
```
883883

884+
[C++ coding style]: ../doc/guides/cpp-style-guide.md
885+
[Callback scopes]: #callback-scopes
886+
[JavaScript value handles]: #js-handles
887+
[N-API]: https://nodejs.org/api/n-api.html
884888
[`BaseObject`]: #baseobject
885889
[`Context`]: #context
886890
[`Environment`]: #environment
@@ -903,10 +907,6 @@ static void GetUserInfo(const FunctionCallbackInfo<Value>& args) {
903907
[`v8.h` in Node.js master]: https://github.com/nodejs/node/blob/master/deps/v8/include/v8.h
904908
[`v8.h` in V8 master]: https://github.com/v8/v8/blob/master/include/v8.h
905909
[`vm` module]: https://nodejs.org/api/vm.html
906-
[C++ coding style]: ../doc/guides/cpp-style-guide.md
907-
[Callback scopes]: #callback-scopes
908-
[JavaScript value handles]: #js-handles
909-
[N-API]: https://nodejs.org/api/n-api.html
910910
[binding function]: #binding-functions
911911
[cleanup hooks]: #cleanup-hooks
912912
[event loop]: #event-loop

‎test/wpt/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,5 +164,5 @@ Web API, or certain harness has not been ported in our test runner yet.
164164
In that case it needs to be marked with `skip` instead of `fail`.
165165

166166
[Web Platform Tests]: https://github.com/web-platform-tests/wpt
167-
[git node wpt]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-wpt
168167
[`test/fixtures/wpt/README.md`]: ../fixtures/wpt/README.md
168+
[git node wpt]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-node-wpt

‎tools/doc/checkLinks.js

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,12 @@ function findMarkdownFilesRecursively(dirPath) {
2727
if (
2828
entry.isDirectory() &&
2929
entry.name !== 'api' &&
30-
entry.name !== 'tmp' &&
31-
entry.name !== 'fixtures' &&
3230
entry.name !== 'changelogs' &&
3331
entry.name !== 'deps' &&
34-
entry.name !== 'node_modules'
32+
entry.name !== 'fixtures' &&
33+
entry.name !== 'node_modules' &&
34+
entry.name !== 'out' &&
35+
entry.name !== 'tmp'
3536
) {
3637
findMarkdownFilesRecursively(path);
3738
} else if (entry.isFile() && extname(entry.name) === '.md') {
@@ -46,6 +47,7 @@ function checkFile(path) {
4647
.parse(fs.readFileSync(path));
4748

4849
const base = pathToFileURL(path);
50+
let previousDefinitionLabel;
4951
for (const node of getLinksRecursively(tree)) {
5052
const targetURL = new URL(node.url, base);
5153
if (targetURL.protocol === 'file:' && !fs.existsSync(targetURL)) {
@@ -55,5 +57,18 @@ function checkFile(path) {
5557
`Broken link at ${path}:${line}:${column} (${node.url})`);
5658
process.exitCode = 1;
5759
}
60+
if (node.type === 'definition') {
61+
if (previousDefinitionLabel &&
62+
previousDefinitionLabel > node.label) {
63+
const { line, column } = node.position.start;
64+
console.error((process.env.GITHUB_ACTIONS ?
65+
`::error file=${path},line=${line},col=${column}::` : '') +
66+
`Unordered reference at ${path}:${line}:${column} (` +
67+
`"${node.label}" should be before "${previousDefinitionLabel})"`
68+
);
69+
process.exitCode = 1;
70+
}
71+
previousDefinitionLabel = node.label;
72+
}
5873
}
5974
}

0 commit comments

Comments
 (0)