A remark-lint plugin with configurations tailored to the documentation and contribution standards of the Node.js GitHub Organization .
Installation
npm install --save-dev @node-core/remark-lint copy
Usage
Add the plugin to your .remarkrc or remark.config.js:
{
"plugins" : [ "@node-core/remark-lint" ]
} copy
Run remark to lint your Markdown files:
Configuration
Released Versions
Some rules, such as node-core:yaml-comments, validate version references against known released Node.js versions. You can provide these using the releasedVersions option:
{
"plugins" : [
[
"@node-core/remark-lint" ,
{
"releasedVersions" : [ "v18.0.0" , "v18.1.0" , "v18.2.0" , "v20.0.0" ]
}
]
]
} copy
For Node.js projects, these versions can be automatically generated using list-released-versions-from-changelogs.mjs .
If not specified, version-related rules will accept any valid SemVer format.
Rules
node-core:duplicate-stability-nodes
Prevents redundant stability markers in nested sections.
Not allowed:
# Parent Section
> Stability: 2 - Stable
## Child Section
> Stability: 2 - Stable <!-- Redundant! --> copy
node-core:invalid-type-reference
Ensures that all {type} references are valid types and formatted correctly.
Allowed:
This is usually a {boolean}, but it could also be a {string|number}. copy
Not allowed:
This is an {invalid} type, and so is {string | number} because there should **not** be whitespace around the `|` . copy
node-core:hashed-self-reference
Ensures self-references use fragment-only links.
Allowed:
See the [ Introduction ]( #introduction ) section. copy
Not allowed:
See the [ Introduction ]( document.md#introduction ) section. copy
node-core:ordered-references
Enforces alphabetical sorting of reference-style link definitions.
Allowed:
[ api ]: https://example.com/api
[ docs ]: https://example.com/docs
[ info ]: https://example.com/info copy
Requires essential metadata for documentation:
llm_description: A description for Large Language Models (can be inferred from first paragraph)
introduced_in: API introduction version
Metadata can be provided in comments:
<!-- llm_description= Utilities for working with file paths --> copy
Enforces structure and content of YAML comment blocks:
added: An array of valid version strings
napiVersion: The N-API version
deprecated: An array of valid version strings
removed: An array of valid version strings
changes: An array of:
pr-url: Pull request URL
commit: Commit hash (only required for security fixes)
version: Valid version string
description: Change description
All version references must be valid SemVer, or match the provided releasedVersions.