tools: add remark-lint configuration in .remarkrc

[ChALkeR]

Checklist

• commit message follows commit guidelines

Affected core subsystem(s)

tools, doc

Description of change

Specifies the configuration for remark-lint, a markdown linter.

This configuration will not cause any warnings on any of the currently present *.md files (ignoring thirdparty), once #7727 lands (hence blocked now).

It is useful not only for possible future tooling that would check the markdown files syntax, but also as a configuration for editor plugins, e.g. linter-markdown for atom-linter.

Issues fixed in #7637 and #7727 were mostly found using remark-lint.

/cc @nodejs/documentation @addaleax @silverwind @mscdex @Fishrock123.

[ChALkeR]

Once this lands, I will propose remark-cli + remark-lint tooling for linting our *.md files similar to how *.js files are linted with eslint.

That should prevent future errors like the ones fixed in #7637 (that fixed several actual errors that broke something in the docs, not just formatting issues) and #7590.

[cjihrig]

Mostly a rubber stamp LGTM. Linting the docs is a great idea.

[targos]

👍

Is it capable of finding errors in the relative links (especially in the fragment identifiers)? That would be awesome.

[silverwind]

Is it capable of finding errors in the relative links

That'd be glorious indeed.

[addaleax]

Is it capable of finding errors in the relative links

I doubt it, the doctool generates its own non-standard format for the anchors (I think that’s done so that there are no duplicates in the generated all.html).

I’ve been occasionally using my own tooling for that, but it needs to be applied to the generated HTML docs instead of the source.

[eljefedelrodeodeljefe]

I think this file shoudn't need to be top-level for a couple of reasons.

1. remark is not included as dependency
2. we were considering building own doc tooling (missing reference to @addaleax issue), and would have based it on remark. Linting could be part of it, but hardly as third party format.
3. the file is nonessential to building and maintaining node and hence should rather be in tooling, not to confuse newcomers
4. remark can, in a couple of years, be exactly what marked is now: an unmaintained npm library, that should leave vendored baggage around.

Sorry, strong -1 in this form. But the intention should be picked up for sure.

[addaleax]

@eljefedelrodeodeljefe Would you think differently about this if remark was, in fact, included as a dependency and/or became the underlying markdown parser for the doctool?

[eljefedelrodeodeljefe]

yes.

[ChALkeR]

@eljefedelrodeodeljefe, this is valuable even without proper tooling on our side (though I plan to add such tooling, just wanted to keep things separate) — code editors (e.g. Atom with linter-markdown plugin) read that file and use that to highlight formatting issues in markdown files. Note that we have .editorconfig in place and I haven't seen it confusing anyone. This sets a project-level config, putting it inside the tooling dir would break editor plugins integration. That config is also specific to our markdown files, hence it doesn't belong in the user configuration.

Nevertheless, I will probably file a pull request with actual remark-cli and remark-lint inclusion around tomorrow.

[eljefedelrodeodeljefe]

hmm. Valid point - some at least.

Maybe just hold off on that until we have done actual work on proper tooling and we integrate that right away. That would decrease module bloat at least and we wouldn't continue with the patch work.

[ChALkeR]

/cc @Trott

[Trott]

LGTM

[ChALkeR]

This should be good to land once #7971 and #7727 are landed.

We can then fix the code blocks language specifications and remove the "no-shell-dollars": false, exception.

no-unused-definitions should be fixed by #7757.

[jasnell]

Rubber stamp LGTM

[ChALkeR]

Yay, I removed the no-unused-definitions exception due to @addaleax awesome work in #7757.

I have added one more commit because another error made it to the docs while this was here, could someone review that one too? Should be trivial. /cc @nodejs/collaborators

@eljefedelrodeodeljefe I still don't see the reason to hold this util the tooling is ready, this at least defines some rules that could help to find errors in the docs.

Going to land this if no objections.

[ChALkeR]

Thanks, all! Landed in b779eb4...4c86fa3.

[silverwind]

Excuse me asking, but how does one run the markdown linter? Is it not included in make lint?

[ChALkeR]

@silverwind Ah, the tooling is included in a separate PR: #8551

The current configuration works if you have remark-cli and remark-lint installed locally (e.g. an editor plugin).

The tooling PR got stalled because I didn't have enough time to fix CI support, but I'm going to continue that soon, and probably make the CI support a separate issue to get the tooling landed faster.

[silverwind]

Thanks. I managed to run it with

yarn global add remark-cli
remark doc/api/*.md

We have 174 lines that exceed 80 characters, yay.