feat(remark-lint): add #8057

avivkeller · 2025-08-01T15:59:59Z

This PR updates the monorepo to include a rewrite of remark-preset-lint-node. Now that we've migrated to the new generators, it makes sense to centralize our linting rules in one place, maintained by the same team. This ensures the generator syntax aligns exactly with the linting configuration.

The updated preset includes all existing rules plus the custom ones currently defined in doc-kit. With a follow-up in doc-kit, this will also address nodejs/doc-kit#328.

Once the migration to doc-kit is finished, we can follow up in node core to replace remark-preset-lint-node with @nodejs/remark-lint/api.

Our current setup is fragmented:

remark-preset-lint-node
Custom rules in node core
More rules in doc-kit
No clear separation in remark-preset-lint-node between general and API-specific rules

By consolidating everything into a single package, we’ll simplify future maintenance.

Tip

This package is versioned, and will only publish when the version package.json field is bumped (or via workflow_dispatch).

cc @nodejs/web-infra
cc @nodejs/linting
cc @Trott

Blocked: NPM_TOKEN secret needs to be updated to allow publishing @node-core/remark-lint

vercel · 2025-08-01T16:00:03Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
nodejs-org	Ready	Preview	Aug 22, 2025 8:51pm

avivkeller · 2025-08-01T16:08:00Z

The only lint changes are escaping characters (i.e _ because \_)

codecov · 2025-08-01T16:09:31Z

Codecov Report

❌ Patch coverage is 98.89225% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.84%. Comparing base (5be4099) to head (d8d311c).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...es/remark-lint/src/rules/yaml/validate-changes.mjs	90.32%	9 Missing ⚠️
...es/remark-lint/src/rules/hashed-self-reference.mjs	97.77%	1 Missing ⚠️
...s/remark-lint/src/rules/yaml/ordered-yaml-keys.mjs	98.27%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8057      +/-   ##
==========================================
+ Coverage   73.17%   75.84%   +2.66%     
==========================================
  Files          97      112      +15     
  Lines        8440     9433     +993     
  Branches      228      304      +76     
==========================================
+ Hits         6176     7154     +978     
- Misses       2263     2278      +15     
  Partials        1        1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

araujogui

Where's the llm_description lint rules?

avivkeller · 2025-08-01T20:20:21Z

Where's the llm_description lint rules?

🤦

I'll add them today, whoops

Trott · 2025-08-01T22:11:21Z

Is the idea that this is what will also be used to lint non-documentation .md files in the nodejs/node and nodejs/TSC repositories? Or will those continue to use remark-lint-preset-node and this is for website linting only?

avivkeller · 2025-08-01T22:27:00Z

Is the idea that this is what will also be used to lint non-documentation .md files in the nodejs/node and nodejs/TSC repositories? Or will those continue to use remark-lint-preset-node and this is for website linting only?

The idea is for this to be the linter associated with doc-kit, the new generator for nodejs/node.

So, the web-infra and website teams will maintain a linter that complies with the generators we wrote (to ensure that they integrate well together).

Yes, it'll work on the other repositories, but there's no obligation to use it there.

avivkeller · 2025-08-01T22:29:14Z

It's going to have two presets. index (just the default import), and api.

api will include all of the rules that are (as I see it) all over the place. (Some in doc kit, some in core, etc).

index will work for website linting, but could work anywhere in the organization.

bmuenzenmeyer

Am I missing a place or decision for us to have/not have READMEs in our packages? Seems like some of the context of this PR and the discussion already would be great to document as intents.

I noticed that the other packages don't have READMEs either. I don't intent to scope creep you but this seems like a good idea, no?

More review coming.

ovflowd · 2025-08-02T14:35:04Z

Blocked: NPM_TOKEN secret needs to be updated to allow publishing @node-core/remark-lint

Issue on /admin repo?

packages/remark-lint/src/index.mjs

packages/remark-lint/src/rules/required-metadata.mjs

avivkeller · 2025-08-02T14:41:46Z

Blocked: NPM_TOKEN secret needs to be updated to allow publishing @node-core/remark-lint

Issue on /admin repo?

Yes, I'll open one, once this gets some approvals

ovflowd

Mostly LGTM, but I feel our YAML rules could receive a bit of cleanup.

packages/remark-lint/src/rules/yaml/validate-versions.mjs

packages/remark-lint/src/rules/yaml/validate-changes.mjs

Copilot

Pull Request Overview

This PR adds a new @node-core/remark-lint package that consolidates Node.js documentation linting rules into a centralized location. The package includes both base linting rules and API-specific rules that were previously scattered across different repositories.

Key changes:

New remark-lint package with comprehensive validation rules for YAML comments, metadata, and Node.js documentation standards
Migration of the site configuration to use the new centralized package
Enhanced CI workflow to handle versioned packages properly

Reviewed Changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/remark-lint/*	Complete implementation of the new remark-lint package with rules, tests, and configuration
apps/site/.remarkrc.json	Simplified configuration to use the new centralized package
apps/site/package.json	Updated dependencies to use the new package
.github/workflows/publish-packages.yml	Enhanced CI to handle versioned packages correctly
apps/site/pages//.md	Minor formatting fixes in documentation files

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

packages/remark-lint/src/rules/yaml/index.mjs

apps/site/pages/en/learn/modules/publishing-a-package.mdx

Ethan-Arrowood

All in all lgtm! I have some non blocking questions but otherwise the tests look great and I'm excited for this to land.

.github/workflows/publish-packages.yml

packages/remark-lint/README.md

packages/remark-lint/package.json

packages/remark-lint/src/api.mjs

packages/remark-lint/src/rules/required-metadata.mjs

packages/remark-lint/src/rules/yaml/validate-versions.mjs

1

github-actions · 2025-08-22T20:51:33Z

Lighthouse Results

URL	Performance	Accessibility	Best Practices	SEO	Report
/en	🟢 99	🟢 100	🟢 100	🟢 100	🔗
/en/about	🟢 100	🟢 97	🟢 100	🟠 88	🔗
/en/about/previous-releases	🟢 98	🟢 93	🟢 100	🟠 89	🔗
/en/download	🟢 95	🟢 100	🟢 100	🟢 100	🔗
/en/blog	🟢 100	🟢 100	🟢 96	🟢 100	🔗

avivkeller requested review from Trott and Copilot August 1, 2025 15:59

avivkeller added the blocked label Aug 1, 2025

avivkeller requested review from a team as code owners August 1, 2025 16:00

This comment was marked as outdated.

Sign in to view

avivkeller force-pushed the feat/remark-lint branch from 4ca85a5 to a8a258b Compare August 1, 2025 16:08

vercel bot deployed to Preview August 1, 2025 16:09 View deployment

vercel bot deployed to Preview August 1, 2025 16:13 View deployment

araujogui reviewed Aug 1, 2025

View reviewed changes

avivkeller requested a review from araujogui August 1, 2025 21:21

vercel bot deployed to Preview August 1, 2025 21:22 View deployment

bmuenzenmeyer reviewed Aug 2, 2025

View reviewed changes

ovflowd reviewed Aug 2, 2025

View reviewed changes

packages/remark-lint/src/index.mjs Outdated Show resolved Hide resolved

ovflowd reviewed Aug 2, 2025

View reviewed changes

packages/remark-lint/src/rules/required-metadata.mjs Show resolved Hide resolved

avivkeller force-pushed the feat/remark-lint branch from a8e566c to ce80c49 Compare August 2, 2025 20:43

vercel bot deployed to Preview August 2, 2025 20:45 View deployment

avivkeller mentioned this pull request Aug 2, 2025

feat: introduce logger nodejs/doc-kit#367

Merged

4 tasks

avivkeller requested review from ovflowd and Copilot August 5, 2025 22:57

ovflowd approved these changes Aug 19, 2025

View reviewed changes

packages/remark-lint/src/rules/yaml/validate-versions.mjs Outdated Show resolved Hide resolved

packages/remark-lint/src/rules/yaml/validate-versions.mjs Show resolved Hide resolved

packages/remark-lint/src/rules/yaml/validate-changes.mjs Outdated Show resolved Hide resolved

vercel bot deployed to Preview August 19, 2025 23:07 View deployment

avivkeller force-pushed the feat/remark-lint branch from f854b17 to 91a19c0 Compare August 19, 2025 23:10

vercel bot deployed to Preview August 19, 2025 23:12 View deployment

avivkeller removed the blocked label Aug 19, 2025

avivkeller removed the request for review from a team August 19, 2025 23:12

avivkeller mentioned this pull request Aug 20, 2025

chore(lint): remove nodejs/doc-kit#415

Merged

avivkeller requested review from ovflowd and Copilot August 20, 2025 20:31

Copilot AI reviewed Aug 20, 2025

View reviewed changes

packages/remark-lint/src/rules/yaml/index.mjs Outdated Show resolved Hide resolved

apps/site/pages/en/learn/modules/publishing-a-package.mdx Outdated Show resolved Hide resolved

vercel bot deployed to Preview August 20, 2025 20:47 View deployment

Ethan-Arrowood approved these changes Aug 22, 2025

View reviewed changes

feat(remark-lint): add

0c89552

1

avivkeller force-pushed the feat/remark-lint branch from 8d64751 to 0c89552 Compare August 22, 2025 20:46

vercel bot had a problem deploying to Preview August 22, 2025 20:46 Failure

avivkeller added 2 commits August 22, 2025 16:47

fixup!

95a2c47

fixup!

5765590

vercel bot deployed to Preview August 22, 2025 20:48 View deployment

fixup!

d8d311c

avivkeller added the github_actions:pull-request Trigger Pull Request Checks label Aug 22, 2025

github-actions bot removed the github_actions:pull-request Trigger Pull Request Checks label Aug 22, 2025

vercel bot deployed to Preview August 22, 2025 20:51 View deployment

avivkeller enabled auto-merge August 22, 2025 20:53

avivkeller added this pull request to the merge queue Aug 22, 2025

Merged via the queue into main with commit ef86853 Aug 22, 2025
16 checks passed

avivkeller deleted the feat/remark-lint branch August 22, 2025 20:59

This was referenced Aug 22, 2025

feat(remark-lint): add strict rules #8106

Open

[automated]: crowdin sync #8117

Closed

Uh oh!

feat(remark-lint): add #8057

feat(remark-lint): add #8057

Uh oh!

Conversation

avivkeller commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

avivkeller commented Aug 1, 2025

Uh oh!

codecov bot commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

araujogui left a comment

Choose a reason for hiding this comment

Uh oh!

avivkeller commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤦

Uh oh!

Trott commented Aug 1, 2025

Uh oh!

avivkeller commented Aug 1, 2025

Uh oh!

avivkeller commented Aug 1, 2025

Uh oh!

bmuenzenmeyer left a comment

Choose a reason for hiding this comment

Uh oh!

ovflowd commented Aug 2, 2025

Uh oh!

Uh oh!

Uh oh!

avivkeller commented Aug 2, 2025

Uh oh!

ovflowd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Ethan-Arrowood left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avivkeller commented Aug 1, 2025 •

edited

Loading

vercel bot commented Aug 1, 2025 •

edited

Loading

codecov bot commented Aug 1, 2025 •

edited

Loading

avivkeller commented Aug 1, 2025 •

edited

Loading

github-actions bot commented Aug 22, 2025 •

edited

Loading