nodejs / remark-preset-lint-node

remark preset to configure remark-lint with settings for nodejs/node

remark-preset-lint-node

remark preset to configure remark-lint with settings for nodejs/node

Install

npm install remark-preset-lint-node

Test

npm test

Add new language or grammar

Adding the language to the documentation style guide

1. PR the nodejs/node repo adding the language/grammar to the documentation style guide.

Adding the language to the linter

1. PR this repo adding the language/grammar.
2. Bump this package version, publish it.
3. In node-lint-md-cli-rollup, bump the remark-preset-lint-node dependency.
4. In the nodejs/node repo, rebuild the Markdown linter (make lint-md-rollup).
5. PR the nodejs/node repo with the updated linter.

Environment variables

NODE_RELEASED_VERSIONS

On runtime, the linter will check the environment if the NODE_RELEASED_VERSIONS variable is defined; if it's there, it will use the content of the variable as a comma-separated list of allowed version numbers. This list is supposed to be built from the changelog(s), and validates the version numbers for the nodejs-yaml-comments rule.

For better compatibility with the nodejs/node changelogs, there are a few exceptions:

• Version numbers ^0.0.0 || ^0.1.0 are not validated using the provided list. They are validated using the vx.x.x pattern.
• REPLACEME placeholder is always valid, regardless if it's in the list or not.

remark-preset-lint-node's Issues

Rule for ordering reference links

This is more style over function, but got the idea from @aduh95 in #139

Basic premise would be to flag:

Lorem impsom [Link A][], [Link B][]

[Link B]: http://example.com/bar
[Link A]: http://example.com/foo

Would flag that the Link A reference is before the Link B reference in the bottom.

Reasoning is, some pages the reference section gets quite large, and an alphabetical list is easier to visually parse when looking for one to update.

Remark 13 might break some things

Just opening as a tracking issue for remarkjs/remark#536
Came across this when nodejs/nodejs.org#3434 started to fail a bunch of things because it changed the parser for that particular plug-in

Automate NPM release with semantic-release

Came across this in https://github.com/htmlhint/HTMLHint/blob/1e85c6eb86bfabd0d4ca7a19ee2842706b449b48/.github/workflows/production.yml#L105-L121 https://github.com/htmlhint/HTMLHint/blob/master/.releaserc.json

Uses convetional commit message formatting to auto-cut release if anything beyond a chore is landed.

I know there is still a manual process to land it in nodejs/node, but was thinking it might be helpful for the other repos to be able to get Dependabot PRs for new releases from this repo.

Downside is that maybe it would still lead to more release churn, and would also probably need an issue on nodejs/admin for the token setup

3.0.0 checks are broken?

Does the fact that this succeeded means the unordered links check isn't working in 3.0.0? @nschonni

Originally posted by @Trott in nodejs/TSC#1072 (comment)

I've also noticed nodejs/node#39754 (comment), where a user is using a malformed version string, which nodejs-yaml-comments should be picking up, but the GH Action is green still.

Rule for enforcing use of passive voice

In professional documentation, I expect the passive voice. It’s not clear who the “we” would be here.

Originally posted by @GeoffreyBooth in nodejs/node#40708 (comment)

---

Strong agree with @GeoffreyBooth from me — perhaps we should consider including retext-passive in our preset to assist us in catching these.

Remark's move to ESM

It looks like Remark moved there new stuff to ESM, so the current new PRs are failing:

• #202
• #206

Doesn't seem like anything is going to be done for the old versions, so it's upgrade here to ESM, or lose support.

Adding full formatting integration tests to CI

Was going to try out the new formatting support on the nodejs.dev content an ran into (likely unrelated) issues.
I was thinking it might make sense to add some integration tests on a few of the main repos that use the config to see if there are any diffs/failures with running remark . -o.
Ones that pop into my head would be:

• nodejs/node
• nodejs/nodejs.org
• nodejs/nodejs.dev
• nodejs/TSC

Transfer into nodejs org

ToDo:

• Transfer repo
• Join linting team
• Integrate ci
• Sort permission on npm registry

Refs:

• nodejs/admin#273

publish new version?

Now that this lints for prohibited strings, would you be willing to publish a new version so we can have that linting in Node.js?

I imagine we'll want to add new strings often for at least a little while. A feature to extend the config file without having to install a new version is probably a good idea. (Does that feature already exist?)

Turning on auto-merge for DependaBot updates

Since we have good coverage of the tests running against the core docs, I think letting DependaBot land PRs when the tests pass should be safe.
Could convert over to the new Yaml config later, but I'm not seeing that setting in their docs right now.

Setup CI for testing changes

Was thinking that Travis could probably be setup to clone down the nodejs/node repo, and any other nodejs repos that are using this to see if changes to the config cause new issues.

[Discussion] About special rules for nodejs.org's md files check

Ref Drafts: #194

Considering there're things not decided yet, move here to have a discussion with you:

1. The rules for md files in nodejs.org is quite diff from what we saw before, Maybe this is the ONLY special one in the whole node.js org, so is it possible to define a remarkable link rules to check it? I don't think it good to pollute the original remarkable links' check rules by adding the options, let it be pure, maybe we can create another project with which we make a special thing for nodejs.org?

2. If OK for 1st, then I've finished some of it according to @aduh95 (First give him a BIG THANKS) roughly, and it really can help to find out many error link out, however I cannot create a new project something like "remark-preset-lint-node" due to the authentication & authorization of node.js, maybe we should seperate the special codes from general ones by creating a new project and refer it into nodejs.org?

3. The worst thing for me here is where to get the root disc? If giving the parameter from options outside, it's hard for write it out because the env will be quite different from each other (we cannot hard coded the disc). So until now I get the absolute path with the disc through vfile.cwd, and then combine my absolute links from the current md file together. Of course, some links may have resources such as *.js...ect. I have to suppose they are all under the "static" folder (For more, after running the npm run build, you can see what's on in "build" folder of your folked project locally).

4. At last, share my rough codes (It can run properly with some checks). But not complete, anyone who can create a new project for nodejs.org may use them. You can folk the nodejs.org project and then paste the whole codes to override "node_modules\remark-preset-lint-node\remark-lint-nodejs-links.js", and remove the ["remark-preset-lint-node/remark-lint-nodejs-links", false] in the ".remarkrc".

"use strict";

const fs = require("fs");
const path = require("path");
const { pathToFileURL } = require("url");

const rule = require("unified-lint-rule");

function* getLinksRecursively(node) {
  if (node.url) {
    yield node;
  }
  for (const child of node.children || []) {
    yield* getLinksRecursively(child);
  }
}

function validateLinks(tree, vfile) {
  const currentFileURL = pathToFileURL(path.join(vfile.cwd, vfile.path));
  let previousDefinitionLabel;

  const rootPaths = [pathToFileURL(path.join(vfile.cwd, 'locale'))];

  let targetURL = null;

  for (const node of getLinksRecursively(tree)) {
    if (node.url[0] !== "#") {

      targetURL = new URL(node.url, currentFileURL);

      if (targetURL.protocol === "file:") {

        let possibleFolderPath = 'notExists'

        // If we've checked the link starting with '/', this means
        // we should get its root path and do checks
        if (path.isAbsolute(node.url)) {
          // console.log(`node url is: ${node.url}, ${node.url.endsWith('/')}`);

          // If node.url ends with '/', 
          // This should be a md file under 'locale'
          // or this is a folder with an index.md
          // we are not sure which is right, so try both
          if (node.url.endsWith('/')) {
            const possibleFile = `${node.url.substring(0, node.url.length - 1)}.md`;
            const possibleFolder = `${node.url}index.md`;
            targetURL = new URL(rootPaths[0] + possibleFile);
            possibleFolderPath = new URL(rootPaths[0] + possibleFolder);
          }
          else {
            // Files without "/" should be a resource file under 'static'
            targetURL = new URL(pathToFileURL(vile.cwd) + node.url);
          }
        }
        if (!fs.existsSync(targetURL) && !fs.existsSync(possibleFolderPath)) {
          //console.log(`Target URL not found: ${targetURL} ${possibleFolderPath}`);
          vfile.message("Broken link", node);
        }
      } else if (targetURL.pathname === currentFileURL.pathname) {
        const expected = node.url.includes("#")
          ? node.url.slice(node.url.indexOf("#"))
          : "#";
        vfile.message(
          `Self-reference must start with hash (expected "${expected}", got "${node.url}")`,
          node
        );
      }
    }
    if (node.type === "definition") {
      if (previousDefinitionLabel && previousDefinitionLabel > node.label) {
        vfile.message(
          `Unordered reference ("${node.label}" should be before "${previousDefinitionLabel}")`,
          node
        );
      }
      previousDefinitionLabel = node.label;
    }
  }
}

module.exports = rule("remark-lint:nodejs-links", validateLinks);

Expand test to cover all documents the nodejs/node lints

Currently the CI test only covers the docs, but there are a few additional directories that the main repo checks https://github.com/nodejs/node/blob/5f80df882057522c38c30b99f4bf25d82c68f662/Makefile#L1196-L1200
The current remark-lint way of ignoring globs might not work, so a test script or some && calls might be required

Rule for enforcing use of `<kbd>`

I believe this would just be an implementation of the prohibited-strings rule. It would look for /(CTRL|ALT)(\+)?(\w)+/ as a primitive first idea of a regex