feat(remark-lint): add

[avivkeller]

Fixes nodejs/doc-kit#350

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]

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]

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

[codecov]

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]

Where's the llm_description lint rules?

🤦

I'll add them today, whoops

[Trott]

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]

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]

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]

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

Issue on /admin repo?

[avivkeller]

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.

[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.}

[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-actions]

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	🔗