doc: add new documentation lint rule

[estrada9166]

Add 80 characters limit to docs.
Change docs to fit 80 characters per row.
Fix broken links in Changelog.md
Fixes: #18703
Refs: remarkjs/remark-lint#82

Also I had to change manually the documentation for tools/icu
the documentation is not clear to ignore files and with .remarkignore
it shows an error

The docs must be changed in order to follow the commit guidelines.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

Doc, Tools

[BridgeAR]

In general this is LGTM.

[BridgeAR]

Hm, these two changes look somewhat weird but I can imagine that the new rule will otherwise complain about it even though it should not?

[BridgeAR]

It would be great to ignore the changelog file but I guess it is not that bad if we don't. What do others think?

Besides that I am a bis surprised that the md files in docs are not linted. They are files that contain lines above 80 characters e.g. readline.md or tls.md.

@watilde is it possible to ignore files somehow?

[BridgeAR]

CI https://ci.nodejs.org/job/node-test-commit-light/256/

[BridgeAR]

@estrada9166 seems like the linter will now properly complain about the rest of the entries above 80 characters. Can you please also fix those? See https://ci.nodejs.org/job/node-test-linter/16080/console.

Those errors should also come up when executing make lint.

[estrada9166]

@BridgeAR Sure thing! fixing right now!

[benjamingr]

@estrada9166 - thanks for stepping up and making a PR :)

---

@nodejs/collaborators - is everyone OK with an 80 character limit in our docs?

Personally I'm -0 on it. Making sure there are no strong objections since this is a style rule.

[apapirovski]

In theory I'm in favour of it but I would like some clarity re: the long URLs. Is the change highlighted by @BridgeAR above necessary? If so, that makes me look less favourably on introducing this rule without first fixing it upstream to be a bit smarter.

[BridgeAR]

@benjamingr we already try to uphold that limit in the docs. Just manually and that fails some times. Therefore the request to add the rule.

[BridgeAR]

@apapirovski long URLs should definitely not cause issues. In case we have issues with those, I would suggest we fix it upstream and then get this in.

@watilde do you know if there is an option for things like that? Otherwise, would you be so kind and implement such an option or give a short hint where to work on to get it fixed upstream?

[estrada9166]

@BridgeAR I just updated CHANGELOG_V9.md and this was the result:

Should I continue changing changelogs?

[BridgeAR]

@estrada9166 as I pointed out, it would be good if we find a way to exclude those. So thanks a lot for the work you already did!

[evanlucas]

I'm -1 to including changelogs for this.

[estrada9166]

I'll contine searching how we can ignore them, because when I add them to .remarkignore this is the result:

Also I found this issue

[BridgeAR]

@wooorm would you be so kind and take a look / give advice?

[apapirovski]

It doesn't seem like remark supports stacking multiple .remarkrc files and due to the length of time it takes to lint the docs, we can't just switch over to using the approach suggested in the issue link above. Seems like we would need to make changes upstream unless I'm missing something. 🤔

[wooorm]

@wooorm would you be so kind and take a look / give advice?

Ignoring: you can either go with globs to files (remark **/*.md !foo.md), or go with remark . and a .remarkignore file. In the latter case you let remark do the work of finding / excluding files!

It doesn't seem like remark supports stacking multiple .remarkrc files and due to the length of time it takes to lint the docs, we can't just switch over to using the approach suggested in the issue link above. Seems like we would need to make changes upstream unless I'm missing something. 🤔

Well, config files can be JS, and can link to other configs, so you can do:

// .remarkrc
{
  "plugins": [
    "remark-lint-something",
    "./some-other-file"
  ]
}

...and

// ./some-other-file.js
exports.plugins = [require('remark-lint-something-else')]

[wooorm]

P.S. feel free to ask specific questions, I’d love to help, but I am also a bit swamped with a course (on node 🎉) I’m currently giving!

[apapirovski]

Thanks @wooorm. Due to how everything is structured within Node.js repo, it seems the file within doc/changelogs/ would have to be somewhat like this:

{
  "plugins": [
    "../../tools/remark-preset-lint-node/",
    ["../../tools/remark-preset-lint-node/node_modules/remark-lint-prohibited-strings", false]
  ]
}

Specifying simply "remark-lint-prohibited-strings" seems to result in the remark resolution algorithm being unable to find it. Unless you have any other tips?

[mcollina]

I'm -1 to this change (I'm making this explicit with the big red cross).

I see too many changes in our changelog, which I would prefer if this didn't touch.

I think this change could impact backporting doc changes too

Can we pick up a number that reflects the current situation (or causes less changes)?
We could pick the limit based on the max line length we have in the changelog.

[BridgeAR]

@mcollina read the above discussion ;-)

[estrada9166]

@BridgeAR My solution to exclude the changelogs is:
/makefile

LINT_MD_DOC_FILES = $(shell ls doc/*.md doc/api/*.md doc/guides/*.md)
run-lint-doc-md = tools/remark-cli/cli.js -q -f $(LINT_MD_DOC_FILES)
# Lint all changed markdown files under doc/
tools/.docmdlintstamp: $(LINT_MD_DOC_FILES)
	@echo "Running Markdown linter on docs..."
	@$(call available-node,$(run-lint-doc-md))
	@touch $@

Excluding them on LINT_MD_DOC_FILES = $(shell ls doc/*.md doc/api/*.md doc/guides/*.md), any consideration before pushing? Do we agree with this change?

[BridgeAR]

I think that is a pretty elegant and easy solution! In this case it is great because it is much faster than having to upstream a change first.

Just one more thing: I think it would also be good to exclude the CHANGELOG.md in root. I think if we have those out, we are good to progress further.

[estrada9166]

@BridgeAR Done!

[BridgeAR]

Light-CI https://ci.nodejs.org/job/node-test-commit-light/316/

[apapirovski]

LGTM

[BridgeAR]

Landed in a29089d

@estrada9166 congratulations on your first commit to Node.js 🎉
Thanks a lot for all your patience and your fast reactions! This was really good work.

[estrada9166]

Thank you so much to all of you!! 🎉

[MylesBorins]

Should this be backported to v9.x-staging? If yes please follow the guide and raise a backport PR, if not let me know or add the dont-land-on label.

[MylesBorins]

Should this be backported to v8.x-staging? If yes please follow the guide and raise a backport PR, if not let me know or add the dont-land-on label.