`doc-kit` vs `remark-preset-lint-node`

[avivkeller]

In addition to the linting defined in this repository, we also rely on remark-preset-lint-node for shared linting rules.

How do we decide which linting rules belong in this repository vs. in remark-preset-lint-node?

Hypothetically, we could perform all the linting as (and move remark-present-lint-node into) a new remark plugin (@node-core/remark-lint in https://github.com/nodejs/nodejs.org, or something)

[avivkeller]

@nodejs/nodejs-website @nodejs/web-infra I'd like to move this into the Monorepo, is that okay with everyone?

[avivkeller]

(@Trott You seem to be the primary maintainer for the remark plugin, is there someone else we should ask for this?)

[Trott]

(@Trott You seem to be the primary maintainer for the remark plugin, is there someone else we should ask for this?)

I'm not sure. Maybe @nodejs/linting.

If you do move remark-preset-lint-node into this repo or something like that, be aware that the automated test for remark-preset-lint-node confirms that any change to it doesn't result in failures in the nodejs and tsc repos, so you'll probably want to maintain that practice.

[Trott]

How do we decide which linting rules belong in this repository vs. in remark-preset-lint-node?

It seems like the answer might be that if the linting rule is for API docs specifically, perhaps it belongs here, but if it's for markdown files generally in nodejs repositories, then it belongs in remark-preset-lint-node. That's based on about 10 seconds of research, though, so take with a grain of salt.

[Trott]

a new remark plugin (@node-core/remark-lint in https://github.com/nodejs/nodejs.org, or something)

It does seem like consolidating into a single package would be useful, as long as lint rules that are here also apply to other markdown files in the nodejs repos that use remark-preset-lint-node. But that might not be the case, in which case two presets probably make sense, and this package can just include remark-preset-lint-node.

I'll add that the name for remark-preset-lint-node was chosen to be consistent with naming in the remark-lint ecosystem. The remark-lint monorepo has three packages named reamrk-preset-lint-* and the ecosystem seems to have adopted the convention.

[avivkeller]

It does seem like consolidating into a single package would be useful, as long as lint rules that are here also apply to other markdown files in the nodejs repos that use remark-preset-lint-node. But that might not be the case, in which case two presets probably make sense, and this package can just include remark-preset-lint-node.

They should, for example, https://github.com/nodejs/remark-preset-lint-node/blob/main/remark-lint-nodejs-yaml-comments.js could work on any Node.js markdown file, despite being specific for the docs.

For the rules that are specifically (and only work on) the docs, we could use remark-preset-lint-node/api-docs vs remark-preset-lint-node directly, or something. I just feel like consolidating, as you said, would make the maintenance of this package easier, especially since it'll go hand in hand with our generators.

I'll add that the name for remark-preset-lint-node was chosen to be consistent with naming in the remark-lint ecosystem. The remark-lint monorepo has three packages named reamrk-preset-lint-* and the ecosystem seems to have adopted the convention.

The name is obviously workshopable, we could just continue with the current name, as well.