doc, tools: use eslint-plugin-markdown
Checklist
-
documentation is changed or added -
commit message follows commit guidelines
Affected core subsystem(s)
doc, tools
Refs: https://github.com/nodejs/node/pull/12557#issuecomment-296015032
Commit 1: an initial step to eliminate parsing errors. Fixing strategies:
- Mixed conflicting contexts: split into separate code blocks.
- Object literals erroneously parsed as code blocks:
- add
const defaults =
orconst options =
-
wrap in(See https://github.com/nodejs/node/pull/12563#discussion_r112729770)()
- add
- Terminal / REPL interaction logs in
repl.md
:add(see https://github.com/nodejs/node/pull/12563#issuecomment-296071614)<!-- eslint-disable -->
to disable linting + preserve syntax highlighting. - Non-js outputs: wrap in
``` ```
instead of```js ```
. - Truncated constructions: complete the code.
- Uncommented ellipses; comment out.
- Syntax errors: fix.
- Line numbers in front of the code: move to the line ends and comment out.
Commit 2: conform most of the problematic code to the rules.
Code is checked with this doc/.eslintrc.yaml
(see https://gist.github.com/not-an-aardvark/f3cb021e854414128d197dde8d0f62b2)
plugins: [markdown]
rules:
strict: 0
no-restricted-properties: 0
no-undef: 0
no-unused-vars: 0
Commit 3: add eslint-plugin-markdown stuff
-
npm install eslint-plugin-markdown
. - Add
doc/.eslintrc.yaml
; addplugins: [markdown]
to the main.eslintrc.yaml
. - Add
<!-- eslint-disable rule -->
or<!-- eslint-disable -->
for the rest problematic code. -
.js
files indoc
folder added to.eslintignore
. - Update
Makefile
andvcbuild.bat
.
Commit 4: make doc linting a bit more specific (as we do for tests code)
- Add
no-var: 2
andprefer-const: 2
indoc/.eslintrc.yaml
. - Fix some fragments in docs accordingly.