chore(remark-lint): improve for node core (#9016)

avivkeller · web-flow · commit b42f4e07fa74 · 2026-07-26T19:30:00.000-07:00
* chore(remark-lint): improve for node core

* fixup!

* fixup!

* fixup!

* fixup!
diff --git a/.changeset/remark-lint-validate-links.md b/.changeset/remark-lint-validate-links.md
@@ -0,0 +1,5 @@
+---
+'@node-core/remark-lint': patch
+---
+
+Add link validation and fix issues in type validation
diff --git a/apps/site/.remarkrc.json b/apps/site/.remarkrc.json
@@ -1,3 +1,13 @@
 {
-  "plugins": ["remark-frontmatter", "@node-core/remark-lint"]
+  "plugins": [
+    "remark-frontmatter",
+    "@node-core/remark-lint",
+    [
+      "@node-core/remark-lint/rules/validate-links",
+      {
+        "ignoreFiles": ["pages/!(en)/**/*.{md,mdx}"],
+        "ignoreLinks": ["/learn", "/learn/**/*", "/static/**/*", "/feed/*"]
+      }
+    ]
+  ]
 }
diff --git a/apps/site/eslint.config.js b/apps/site/eslint.config.js
@@ -43,6 +43,8 @@ export default baseConfig.concat([
   },
 
   {
+    // TODO: Enable validate-links for translations once their routes and
+    // anchors are kept in sync with the English content.
     ...mdx.flat,
     processor: mdx.createRemarkProcessor({ lintCodeBlocks: true }),
     rules: {
diff --git a/apps/site/pages/en/about/eol.mdx b/apps/site/pages/en/about/eol.mdx
@@ -20,7 +20,7 @@ Major versions of Node.js are released, patched, and designated End-Of-Life on a
   </Button>
 </div>
 
-[View the Node.js release schedule](/about/releases/).
+[View the Node.js release schedule](/about/previous-releases/).
 
 ## What Happens When a Release Line Reaches EOL
 
diff --git a/apps/site/pages/en/blog/community/building-nodejs-together.md b/apps/site/pages/en/blog/community/building-nodejs-together.md
@@ -26,17 +26,17 @@ living breathing website whose content is created by our end users and team.
 The website should be the canonical location for documentation on how to use
 Node.js, how Node.js works, and how to find out what's going on in the Node
 community. We have seeded the initial documentation with [how to
-contribute](/about/get-involved/contribute/), [who the core team
-is](/about/organization/#index_md_technical_steering_committee),
+contribute](https://github.com/nodejs/node/blob/main/CONTRIBUTING.md), [who the core team
+is](https://github.com/nodejs/node),
 and some basic documentation of the [project
-itself](/about/organization). From there we're looking to
+itself](https://github.com/nodejs/TSC). From there we're looking to
 enable the community to come in and build out the rest of the framework for
 documentation.
 
 One of the key changes here is that we're extending the tools that generate API
 documentation to work for the website in general. That means the website is now
 written in markdown. Contributions work with the same
-[pull-request](/about/get-involved/contribute/#code-contributions)
+[pull-request](https://github.com/nodejs/node/blob/main/CONTRIBUTING.md#pull-requests)
 way as contributions to Node itself. The intent here is to be able to quickly
 generate new documentation and improve it with feedback from the community.
 
@@ -56,8 +56,7 @@ Road](http://blog.nodejs.org/2014/06/11/notes-from-the-road/) events there are
 often questions about what does and doesn't go into core. How the team
 identifies what those features are and when you decide to integrate them. I've
 spent a lot of time talking about that but I've also
-[added](/about/organization) it to the new documentation on
-the site.
+added it to the new documentation on the site.
 
 It's pretty straight forward, but in short if Node.js needs an interface to
 provide an abstraction, or if everyone in the community is using the same
@@ -144,7 +143,7 @@ responsible for the entirety of that subsystem, but they guide its progress by
 communicating with end users, reviewing bugs and pull requests, and identifying
 test cases and consumers of new features. People come and go from the core
 team, and recently we've added [some
-documentation](/about/organization) that describes how you
+documentation](https://github.com/nodejs/TSC) that describes how you
 find your way onto that team. It's based largely around our contribution
 process. It's not about who you work for, or about who you know, it's about
 your ability to provide technical improvement to the project itself.
diff --git a/apps/site/pages/en/blog/release/v8.0.0.md b/apps/site/pages/en/blog/release/v8.0.0.md
@@ -52,7 +52,7 @@ as well.
 The [N-API](https://nodejs.org/api/n-api.html) is experimental in Node.js 8.0.0,
 so significant changes in the implementation and API should be expected. Native
 addon developers are
-[encouraged to begin working with the API](/guides/publishing-napi-modules/)
+[encouraged to begin working with the API](/learn/modules/publishing-node-api-modules)
 as soon as possible and to provide feedback that will be necessary to ensure
 that the new API meets the needs of the ecosystem.
 
diff --git a/apps/site/pages/en/blog/uncategorized/evolving-the-node-js-brand.md b/apps/site/pages/en/blog/uncategorized/evolving-the-node-js-brand.md
@@ -30,6 +30,6 @@ We look forward to exploring this visual language as the technology charges into
 
 We hope you'll have fun using it.
 
-To download the new logo, visit [nodejs.org/en/about/resources/](/about/resources/).
+To download the new logo, visit [our branding page](https://nodejs.org/en/about/branding)
 
 ![Tri-color Node](/static/images/blog/uncategorized/evolving-the-node-js-brand/tri-color-node.png)
diff --git a/apps/site/pages/en/blog/vulnerability/february-2016-security-releases.md b/apps/site/pages/en/blog/vulnerability/february-2016-security-releases.md
@@ -23,7 +23,7 @@ Régis Leroy reported defects in Node.js that can make [request smuggling](https
 While the impact of this vulnerability is application and network dependent, it is likely to be difficult to assess whether a Node.js deployment is vulnerable to attack. We therefore recommend that all users upgrade.
 
 - Versions 0.10.x of Node.js are **vulnerable**, please upgrade to [v0.10.42 (Maintenance)](/blog/release/v0.10.42/).
-- Versions 0.12.x of Node.js are **vulnerable**, please upgrade to [v0.12.10 (LTS)](blog/release/v0.12.10/).
+- Versions 0.12.x of Node.js are **vulnerable**, please upgrade to [v0.12.10 (LTS)](/blog/release/v0.12.10/).
 - Versions 4.x, including LTS Argon, of Node.js are **vulnerable**, please upgrade to [v4.3.0 "Argon" (LTS)](/blog/release/v4.3.0/).
 - Versions 5.x of Node.js are **vulnerable**, please upgrade to [v5.6.0 (Stable)](/blog/release/v5.6.0/).
 
diff --git a/apps/site/pages/en/blog/vulnerability/february-2024-security-releases.md b/apps/site/pages/en/blog/vulnerability/february-2024-security-releases.md
@@ -167,6 +167,6 @@ Releases will be available on, or shortly after, Tuesday February 6 2024.
 
 ## Contact and future updates
 
-The current Node.js security policy can be found at [https://nodejs.org/security/](/security/). Please follow the process outlined in <https://github.com/nodejs/node/security/policy> if you wish to report a vulnerability in Node.js.
+Please follow the process outlined in <https://github.com/nodejs/node/security/policy> if you wish to report a vulnerability in Node.js.
 
 Subscribe to the low-volume announcement-only nodejs-sec mailing list at <https://groups.google.com/forum/#!forum/nodejs-sec> to stay up to date on security vulnerabilities and security-related releases of Node.js and the projects maintained in the nodejs GitHub organization.
diff --git a/apps/site/pages/en/blog/vulnerability/july-2022-security-releases.md b/apps/site/pages/en/blog/vulnerability/july-2022-security-releases.md
@@ -191,7 +191,7 @@ Releases will be available on, or shortly after, Tuesday, July 5th, 2022.
 However, when details of the OpenSSL defects are released on the 5th, our team will be making a more detailed assessment
 on the likely severity for Node.js users.
 
-The OpenSSL release may delay the Node.js release date. See [OpenSSL Security Release](#update-04-07-2022-openssl-security-release)
+The OpenSSL release may delay the Node.js release date.
 
 Please monitor the **nodejs-sec** Google Group for updates, including a decision within 24 hours after the OpenSSL release regarding release timing, and full details of the defects upon eventual release: https://groups.google.com/forum/#!forum/nodejs-sec
 
diff --git a/apps/site/pages/en/blog/vulnerability/june-2023-security-releases.md b/apps/site/pages/en/blog/vulnerability/june-2023-security-releases.md
@@ -212,6 +212,6 @@ Releases will be available on, or shortly after, Tuesday June 20 2023.
 
 ## Contact and future updates
 
-The current Node.js security policy can be found at [https://nodejs.org/security/](/security/). Please follow the process outlined in <https://github.com/nodejs/node/security/policy> if you wish to report a vulnerability in Node.js.
+Please follow the process outlined in <https://github.com/nodejs/node/security/policy> if you wish to report a vulnerability in Node.js.
 
 Subscribe to the low-volume announcement-only nodejs-sec mailing list at <https://groups.google.com/forum/#!forum/nodejs-sec> to stay up to date on security vulnerabilities and security-related releases of Node.js and the projects maintained in the nodejs GitHub organization.
diff --git a/apps/site/pages/en/blog/vulnerability/march-2025-ci-incident.md b/apps/site/pages/en/blog/vulnerability/march-2025-ci-incident.md
@@ -78,7 +78,7 @@ A full report of this incident will be available forthcoming. We appreciate the
 
 ## Contact and future updates
 
-The current Node.js security policy can be found at [https://nodejs.org/security/](/security/). Please follow the process outlined in <https://github.com/nodejs/node/security/policy> if you wish to report a vulnerability in Node.js.
+Please follow the process outlined in <https://github.com/nodejs/node/security/policy> if you wish to report a vulnerability in Node.js.
 
 Subscribe to the low-volume announcement-only nodejs-sec mailing list at <https://groups.google.com/forum/#!forum/nodejs-sec> to stay up to date on security vulnerabilities and security-related releases of Node.js and the projects maintained in the nodejs GitHub organization.
 
diff --git a/apps/site/pages/en/blog/vulnerability/october-2023-security-releases.md b/apps/site/pages/en/blog/vulnerability/october-2023-security-releases.md
@@ -122,6 +122,6 @@ Releases will be available on, or shortly after, Friday October 13 2023.
 
 ## Contact and future updates
 
-The current Node.js security policy can be found at [https://nodejs.org/security/](/security/). Please follow the process outlined in <https://github.com/nodejs/node/security/policy> if you wish to report a vulnerability in Node.js.
+Please follow the process outlined in <https://github.com/nodejs/node/security/policy> if you wish to report a vulnerability in Node.js.
 
 Subscribe to the low-volume announcement-only nodejs-sec mailing list at <https://groups.google.com/forum/#!forum/nodejs-sec> to stay up to date on security vulnerabilities and security-related releases of Node.js and the projects maintained in the nodejs GitHub organization.
diff --git a/packages/remark-lint/README.md b/packages/remark-lint/README.md
@@ -109,6 +109,16 @@ Enforces alphabetical sorting of reference-style link definitions.
 [info]: https://example.com/info
 ```
 
+### `node-core:validate-links`
+
+Checks that local links point to existing files and that fragment-only links
+point to headings in the current document. Root-relative website routes are
+mapped to the configured content and public directories, and route targets do
+not need to include a file extension. Directory routes resolve to `index.*`.
+
+For example, `/about/previous-releases` resolves to
+`pages/en/about/previous-releases.mdx`.
+
 ### `node-core:required-metadata`
 
 Requires essential metadata for documentation:
diff --git a/packages/remark-lint/package.json b/packages/remark-lint/package.json
@@ -1,10 +1,11 @@
 {
   "name": "@node-core/remark-lint",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "exports": {
     ".": "./src/index.mjs",
-    "./api": "./src/api.mjs"
+    "./api": "./src/api.mjs",
+    "./rules/*": "./src/rules/*.mjs"
   },
   "repository": {
     "type": "git",
@@ -21,6 +22,7 @@
   },
   "dependencies": {
     "@node-core/doc-kit": "^1.2.0",
+    "mdast-util-to-string": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-lint-blockquote-indentation": "^4.0.1",
     "remark-lint-checkbox-character-style": "^5.0.1",
diff --git a/packages/remark-lint/src/index.mjs b/packages/remark-lint/src/index.mjs
@@ -24,6 +24,8 @@ import remarkLintTableCellPadding from 'remark-lint-table-cell-padding';
 import remarkLintTablePipes from 'remark-lint-table-pipes';
 import remarkPresetLintRecommended from 'remark-preset-lint-recommended';
 
+import validateLinks from './rules/validate-links.mjs';
+
 export default {
   settings: {
     tightDefinitions: true,
@@ -54,6 +56,7 @@ export default {
     remarkLintNofileNameOuterDashes,
 
     // Heading and link rules
+    [validateLinks, { basePaths: ['pages/en', 'pages', 'public', '.'] }],
     remarkLintFinalDefinition,
     [remarkLintNoUnusedDefinitions, false],
     [remarkLintNoLiteralURLs, false],
diff --git a/packages/remark-lint/src/rules/__tests__/invalid-type-reference.test.mjs b/packages/remark-lint/src/rules/__tests__/invalid-type-reference.test.mjs
@@ -1,3 +1,4 @@
+import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
 import { testRule } from './utils.mjs';
@@ -24,6 +25,19 @@ const testCases = [
     input: '[<number>]()',
     expected: ['Type reference must be wrapped in "{}"; saw "<number>"'],
   },
+  {
+    name: 'ignores references in non-prose nodes',
+    input: `<!-- {invalid} -->
+
+\`{invalid}\`
+
+\`\`\`js
+const value = {invalid};
+\`\`\`
+
+<div>{invalid}</div>`,
+    expected: [],
+  },
   {
     name: 'multiple references',
     input: 'Psst, are you a {string | boolean}',
@@ -54,9 +68,13 @@ const testCases = [
 ];
 
 describe('invalid-type-reference', () => {
-  for (const { name, input, expected, options } of testCases) {
-    it(name, () =>
-      testRule(invalidTypeReference, input, expected, {}, options)
-    );
+  for (const { name, input, expected, options, replacement } of testCases) {
+    it(name, () => {
+      const tree = testRule(invalidTypeReference, input, expected, {}, options);
+
+      if (replacement) {
+        assert.equal(tree.children[0].children[0].value, replacement);
+      }
+    });
   }
 });
diff --git a/packages/remark-lint/src/rules/__tests__/utils.mjs b/packages/remark-lint/src/rules/__tests__/utils.mjs
@@ -32,6 +32,8 @@ export const testRule = (
     vfile.message.mock.calls.map(call => call.arguments[0]),
     expected
   );
+
+  return tree;
 };
 
 /**
diff --git a/packages/remark-lint/src/rules/__tests__/validate-links.test.mjs b/packages/remark-lint/src/rules/__tests__/validate-links.test.mjs
diff --git a/packages/remark-lint/src/rules/invalid-type-reference.mjs b/packages/remark-lint/src/rules/invalid-type-reference.mjs
diff --git a/packages/remark-lint/src/rules/validate-links.mjs b/packages/remark-lint/src/rules/validate-links.mjs
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@node-core/remark-lint': patch
 +---
++
 +Add link validation and fix issues in type validation
Original file line number	Diff line number	Diff line change
`@@ -43,6 +43,8 @@ export default baseConfig.concat([`
`43`	`43`	`},`
`44`	`44`
`45`	`45`	`{`
	`46`	`+ // TODO: Enable validate-links for translations once their routes and`
	`47`	`+ // anchors are kept in sync with the English content.`
`46`	`48`	`...mdx.flat,`
`47`	`49`	`processor: mdx.createRemarkProcessor({ lintCodeBlocks: true }),`
`48`	`50`	`rules: {`