tools: lint doc/*.md files

Makefile

@@ -1044,7 +1044,7 @@ lint-md-build: tools/remark-cli/node_modules \
 .PHONY: lint-md
 ifneq ("","$(wildcard tools/remark-cli/node_modules/)")
 
-LINT_MD_DOC_FILES = $(shell ls doc/**/*.md)
+LINT_MD_DOC_FILES = $(shell ls doc/*.md doc/**/*.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)

doc/STYLE_GUIDE.md

@@ -58,15 +58,19 @@
   * Use a capital letter after the "Note:" label.
   * Preferably, make the note a new paragraph for better visual distinction.
 * Function arguments or object properties should use the following format:
-  * <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`.</code>
-  * E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.</code>
+  * ``` * `name` {type|type2} Optional description. **Default:** `value`. ```
+  <!--lint disable maximum-line-length remark-lint-->
+  * For example: <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.</code>
+  <!--lint enable maximum-line-length remark-lint-->
   * The `type` should refer to a Node.js type or a [JavaScript type][].
 * Function returns should use the following format:
   * <code>* Returns: {type|type2} Optional description.</code>
   * E.g. <code>* Returns: {AsyncHook} A reference to `asyncHook`.</code>
 * Use official styling for capitalization in products and projects.
   * OK: JavaScript, Google's V8
+  <!--lint disable prohibited-strings remark-lint-->
   * NOT OK: Javascript, Google's v8
+  <!-- lint enable prohibited-strings remark-lint-->
 
 See also API documentation structure overview in [doctools README][].
 

doc/guides/contributing/pull-requests.md

@@ -137,8 +137,8 @@ notes about [commit squashing](#commit-squashing)).
 A good commit message should describe what changed and why.
 
 1. The first line should:
-   - contain a short description of the change (preferably 50 characters or less,
-     and no more than 72 characters)
+   - contain a short description of the change (preferably 50 characters or
+     less, and no more than 72 characters)
    - be entirely in lowercase with the exception of proper nouns, acronyms, and
    the words that refer to code, like function/variable names
    - be prefixed with the name of the changed subsystem and start with an
@@ -456,7 +456,8 @@ Focus first on the most significant aspects of the change:
 1. Does this change make sense for Node.js?
 2. Does this change make Node.js better, even if only incrementally?
 3. Are there clear bugs or larger scale issues that need attending to?
-4. Is the commit message readable and correct? If it contains a breaking change is it clear enough?
+4. Is the commit message readable and correct? If it contains a breaking change
+   is it clear enough?
 
 When changes are necessary, *request* them, do not *demand* them, and do not
 assume that the submitter already knows how to add a test or run a benchmark.

doc/onboarding.md

@@ -144,7 +144,7 @@ onboarding session.
     (especially if it just has nits left).
 * Approving a change
   * Collaborators indicate that they have reviewed and approve of the changes in
-    a pull request using Github’s approval interface
+    a pull request using GitHub’s approval interface
   * Some people like to comment `LGTM` (“Looks Good To Me”)
   * You have the authority to approve any other collaborator’s work.
   * You cannot approve your own pull requests.
@@ -206,7 +206,7 @@ needs to be pointed out separately during the onboarding.
 ## Exercise: Make a PR adding yourself to the README
 
 * Example:
-  [https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0][]
+  https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0
   * For raw commit message: `git log ce986de829457c39257cd205067602e765768fb0
     -1`
 * Collaborators are in alphabetical order by GitHub username.
@@ -250,7 +250,6 @@ needs to be pointed out separately during the onboarding.
 [`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md
 [`node-core-utils`]: https://github.com/nodejs/node-core-utils
 [Landing Pull Requests]: https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md#landing-pull-requests
-[https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0]: https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0
 [Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/
 [set up the credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials
 [two-factor authentication]: https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/

doc/releases.md

@@ -88,8 +88,8 @@ least one business day in advance of the expected release. Coordinating with
 Build is essential to make sure that the CI works, release files are published,
 and the release blog post is available on the project website.
 
-Build can be contacted best by opening up an issue on the [Build issue tracker][],
-and by posting in `#node-build` on [webchat.freenode.net][].
+Build can be contacted best by opening up an issue on the [Build issue
+tracker][], and by posting in `#node-build` on [webchat.freenode.net][].
 
 When preparing a security release, contact Build at least two weekdays in
 advance of the expected release. To ensure that the security patch(es) can be
@@ -524,7 +524,8 @@ To announce the build on Twitter through the official @nodejs account, email
 
 To ensure communication goes out with the timing of the blog post, please allow
 24 hour prior notice. If known, please include the date and time the release
-will be shared with the community in the email to coordinate these announcements.
+will be shared with the community in the email to coordinate these
+announcements.
 
 ### 16. Cleanup