chore: add markdownlint (#1889)

.github/workflows/ci.yml

@@ -93,10 +93,13 @@ jobs:
       - name: Check code formatting
         run: yarn format-check
 
-      - name: Run linting
+      - name: Lint code
         run: yarn lint
 
-      - name: Validate spelling
+      - name: Lint markdown
+        run: yarn lint:markdown
+
+      - name: Check spelling
         run: yarn check:spelling
 
   integration_tests:

.markdownlint.json

@@ -0,0 +1,95 @@
+{
+  "default": false,
+
+  // MD001/heading-increment/header-increment - Heading levels should only increment by one level at a time
+  "MD001": true,
+  // MD002/first-heading-h1/first-header-h1 - First heading should be a top level heading
+  "MD002": false,
+  // MD003/heading-style/header-style - Heading style
+  "MD003": false,
+  // MD004/ul-style - Unordered list style
+  "MD004": false,
+  // MD005/list-indent - Inconsistent indentation for list items at the same level
+  "MD005": false,
+  // MD006/ul-start-left - Consider starting bulleted lists at the beginning of the line
+  "MD006": false,
+  // MD007/ul-indent - Unordered list indentation
+  "MD007": false,
+  // MD009/no-trailing-spaces - Trailing spaces
+  "MD009": false,
+  // MD010/no-hard-tabs - Hard tabs
+  "MD010": false,
+  // MD011/no-reversed-links - Reversed link syntax
+  "MD011": true,
+  // MD012/no-multiple-blanks - Multiple consecutive blank lines
+  "MD012": false,
+  // MD013/line-length - Line length
+  "MD013": { "line_length": 99999 }, // no line length
+  // MD014/commands-show-output - Dollar signs used before commands without showing output
+  "MD014": false,
+  // MD018/no-missing-space-atx - No space after hash on atx style heading
+  "MD018": true,
+  // MD019/no-multiple-space-atx - Multiple spaces after hash on atx style heading
+  "MD019": false,
+  // MD020/no-missing-space-closed-atx - No space inside hashes on closed atx style heading
+  "MD020": false,
+  // MD021/no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
+  "MD021": false,
+  // MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
+  "MD022": true,
+  // MD023/heading-start-left/header-start-left - Headings must start at the beginning of the line
+  "MD023": false,
+  // MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
+  "MD024": false,
+  // MD025/single-title/single-h1 - Multiple top level headings in the same document
+  "MD025": true,
+  // MD026/no-trailing-punctuation - Trailing punctuation in heading
+  "MD026": { "punctuation": ".,;:!。，；：！？" }, // specifically allow "?"
+  // MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol
+  "MD027": false,
+  // MD028/no-blanks-blockquote - Blank line inside blockquote
+  "MD028": true,
+  // MD029/ol-prefix - Ordered list item prefix
+  "MD029": false,
+  // MD030/list-marker-space - Spaces after list markers
+  "MD030": true,
+  // MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines
+  "MD031": false,
+  // MD032/blanks-around-lists - Lists should be surrounded by blank lines
+  "MD032": false,
+  // MD033/no-inline-html - Inline HTML
+  "MD033": { "allowed_elements": ["a", "img", "br", "sup", "h1", "p"] },
+  // MD034/no-bare-urls - Bare URL used
+  "MD034": false,
+  // MD035/hr-style - Horizontal rule style
+  "MD035": false,
+  // MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
+  "MD036": true,
+  // MD037/no-space-in-emphasis - Spaces inside emphasis markers
+  "MD037": true,
+  // MD038/no-space-in-code - Spaces inside code span elements
+  "MD038": true,
+  // MD039/no-space-in-links - Spaces inside link text
+  "MD039": true,
+  // MD040/fenced-code-language - Fenced code blocks should have a language specified
+  "MD040": true,
+  // MD041/first-line-heading/first-line-h1 - First line in file should be a top level heading
+  "MD041": false, // would love to do this, but our README files use `<h1 center>` as their heading
+  // MD042/no-empty-links - No empty links
+  "MD042": true,
+  // MD043/required-headings/required-headers - Required heading structure
+  "MD043": false,
+  // MD044/proper-names - Proper names should have the correct capitalization
+  "MD044": {
+    "names": ["JavaScript", "TypeScript", "TSLint", "ESLint"],
+    "code_blocks": false
+  },
+  // MD045/no-alt-text - Images should have alternate text (alt text)
+  "MD045": true,
+  // MD046/code-block-style - Code block style
+  "MD046": { "style": "fenced" },
+  // MD047/single-trailing-newline - Files should end with a single newline character
+  "MD047": false,
+  // MD048/code-fence-style - Code fence style
+  "MD048": { "style": "backtick" }
+}

.markdownlintignore

@@ -0,0 +1,3 @@
+node_modules
+CHANGELOG.md
+tests/integration/fixtures/markdown

.vscode/extensions.json

@@ -3,7 +3,8 @@
       "esbenp.prettier-vscode",
       "dbaeumer.vscode-eslint",
       "editorconfig.editorconfig",
-      "streetsidesoftware.code-spell-checker"
+      "streetsidesoftware.code-spell-checker",
+      "davidanson.vscode-markdownlint"
   ],
   "unwantedRecommendations": ["hookyqr.beautify", "dbaeumer.jshint"]
 }

.vscode/settings.json

@@ -17,5 +17,5 @@
   "typescript.preferences.importModuleSpecifier": "auto",
   "javascript.preferences.quoteStyle": "single",
   "typescript.preferences.quoteStyle": "single",
-  "editor.defaultFormatter": "esbenp.prettier-vscode"
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
 }

CONTRIBUTING.md

@@ -50,6 +50,7 @@ We have a sophisticated CI process setup which gets run on every PR. You must pa
   - Coverage reports should automatically be generated locally, and the `codecov` bot should also comment on your PR with the percentage, as well as links to the line-by-line coverage of each file touched by your PR.
 - Ensure you have no lint errors.
   - You can run `yarn lint` in any package or in the root.
+  - You can run `yarn lint:markdown` in the root.
 - If you have made changes to any markdown documentation, ensure there are no spelling errors
   - You can run `yarn check:spelling` in the root.
   - Or if you are using vscode, you can use [`Code Spell Checker`](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) plugin.
@@ -60,7 +61,7 @@ We have a sophisticated CI process setup which gets run on every PR. You must pa
 
 Once your changes are ready, you can raise a PR. The title of your PR should match the following format:
 
-```
+```text
 <tag>(<package>): <short description>
 ```
 

docs/getting-started/README.md

@@ -6,6 +6,6 @@ The goal of these docs are to give you a quick overview of the project and all o
 
 The docs are broken down into the following categories:
 
-### [I want to lint my TypeScript codebase.](./linting/README.md)
+## [I want to lint my TypeScript codebase.](./linting/README.md)
 
-### [(TODO) I want to write an ESLint plugin in TypeScript.](./plugin-development/README.md)
+## [(TODO) I want to write an ESLint plugin in TypeScript.](./plugin-development/README.md)

package.json

@@ -30,6 +30,8 @@
     "kill-integration-test-containers": "docker-compose -f tests/integration/docker-compose.yml down -v --rmi local",
     "lint": "eslint . --ext .js,.ts",
     "lint-fix": "eslint . --ext .js,.ts --fix",
+    "lint:markdown": "markdownlint '**/*.md' --config=.markdownlint.json --ignore-path=.markdownlintignore",
+    "lint:markdown:fix": "lint:markdown --fix",
     "pre-commit": "yarn lint-staged",
     "pre-push": "yarn format-check",
     "postinstall": "lerna bootstrap && yarn build && lerna link",
@@ -70,6 +72,7 @@
     "jest": "^25.1.0",
     "lerna": "^3.20.2",
     "lint-staged": "^9.4.3",
+    "markdownlint-cli": "^0.22.0",
     "prettier": "^1.19.1",
     "ts-jest": "^25.0.0",
     "ts-node": "^8.5.0",

packages/eslint-plugin/ROADMAP.md

@@ -202,7 +202,7 @@ It lists all TSLint rules along side rules from the ESLint ecosystem that are th
 <sup>[1]</sup> Recommended config: `["error", { blankLine: "always", prev: "*", next: "return" }]`<br>
 <sup>[2]</sup> Doesn't check other control flow statements, such as `break` or `continue`.
 
-## tslint-microsoft-contrib rules
+## `tslint-microsoft-contrib` rules
 
 Rule listing is [here](https://github.com/Microsoft/tslint-microsoft-contrib#supported-rules).
 Deprecated rules are excluded (`missing-jsdoc`, `missing-optional-annotation`, `no-duplicate-case`, `no-duplicate-parameter-names`, `no-function-constructor-with-string-args`, `no-increment-decrement`, `no-empty-interfaces`, `no-missing-visibility-modifiers`, `no-multiple-var-decl`, `no-reserved-keywords`, `no-stateless-class`, `no-var-self`, `no-unnecessary-bind`, and `valid-typeof`). See the docs in the link above to find out what to use instead.
@@ -211,7 +211,7 @@ Deprecated rules are excluded (`missing-jsdoc`, `missing-optional-annotation`, `
 
 Relevant plugins: [`chai-expect-keywords`](https://github.com/gavinaiken/eslint-plugin-chai-expect-keywords), [`chai-expect`](https://github.com/Turbo87/eslint-plugin-chai-expect), [`chai-friendly`](https://github.com/ihordiachenko/eslint-plugin-chai-friendly), [`mocha`](https://github.com/lo1tuma/eslint-plugin-mocha), and [`jest`](https://github.com/jest-community/eslint-plugin-jest)
 
-| tslint-microsoft-contrib rule      |     | ESLint rule               |
+| `tslint-microsoft-contrib` rule    |     | ESLint rule               |
 | ---------------------------------- | :-: | ------------------------- |
 | `chai-prefer-contains-to-index-of` | 🛑  | N/A                       |
 | `chai-vague-errors`                | 🛑  | N/A                       |
@@ -220,16 +220,16 @@ Relevant plugins: [`chai-expect-keywords`](https://github.com/gavinaiken/eslint-
 
 ### TypeScript
 
-| tslint-microsoft-contrib rule |     | ESLint rule                                                |
-| ----------------------------- | :-: | ---------------------------------------------------------- |
-| `prefer-array-literal`        | 🌓  | [`@typescript-eslint/no-array-constructor`] <sup>[1]</sup> |
-| `prefer-type-cast`            | 🛑  | N/A                                                        |
+| `tslint-microsoft-contrib` rule |     | ESLint rule                                                |
+| ------------------------------- | :-: | ---------------------------------------------------------- |
+| `prefer-array-literal`          | 🌓  | [`@typescript-eslint/no-array-constructor`] <sup>[1]</sup> |
+| `prefer-type-cast`              | 🛑  | N/A                                                        |
 
 <sup>[1]</sup> ESLint rule is slightly less strict, allowing `new Array<Foo>()` and `Array(2)`.
 
 ### Miscellaneous
 
-| tslint-microsoft-contrib rule         |     | ESLint rule                                                            |
+| `tslint-microsoft-contrib` rule       |     | ESLint rule                                                            |
 | ------------------------------------- | :-: | ---------------------------------------------------------------------- |
 | `export-name`                         | 🛑  | N/A ([relevant plugin][plugin:import])                                 |
 | `function-name`                       | 🛑  | N/A                                                                    |
@@ -274,7 +274,7 @@ Relevant plugins: [`chai-expect-keywords`](https://github.com/gavinaiken/eslint-
 
 ### Security
 
-| tslint-microsoft-contrib rule   |     | ESLint rule                                        |
+| `tslint-microsoft-contrib` rule |     | ESLint rule                                        |
 | ------------------------------- | :-: | -------------------------------------------------- |
 | `no-disable-auto-sanitization`  | 🛑  | N/A                                                |
 | `no-document-domain`            | 🌓  | Use [`no-restricted-syntax`][no-restricted-syntax] |
@@ -291,7 +291,7 @@ Relevant plugins: [`chai-expect-keywords`](https://github.com/gavinaiken/eslint-
 
 ### Browser
 
-| tslint-microsoft-contrib rule       |     | ESLint rule                                        |
+| `tslint-microsoft-contrib` rule     |     | ESLint rule                                        |
 | ----------------------------------- | :-: | -------------------------------------------------- |
 | `jquery-deferred-must-complete`     | 🛑  | N/A                                                |
 | `no-backbone-get-set-outside-model` | 🛑  | N/A                                                |
@@ -306,7 +306,7 @@ Relevant plugins: [`chai-expect-keywords`](https://github.com/gavinaiken/eslint-
 
 ### React A11y
 
-| tslint-microsoft-contrib rule             |     | ESLint rule                                                |
+| `tslint-microsoft-contrib` rule           |     | ESLint rule                                                |
 | ----------------------------------------- | :-: | ---------------------------------------------------------- |
 | `react-a11y-accessible-headings`          | 🌓  | [`jsx-a11y/heading-has-content`] <sup>[1]</sup>            |
 | `react-a11y-anchors`                      | 🔌  | [`jsx-a11y/anchor-is-valid`]                               |

packages/eslint-plugin/docs/rules/ban-ts-comment.md

@@ -5,7 +5,7 @@ Using these to suppress TypeScript Compiler Errors reduces the effectiveness of
 
 The directive comments supported by TypeScript are:
 
-```
+```ts
 // @ts-expect-error
 // @ts-ignore
 // @ts-nocheck
@@ -19,7 +19,7 @@ By default, only `@ts-check` is allowed, as it enables rather than suppresses er
 
 The configuration looks like this:
 
-```
+```ts
 interface Options {
   'ts-expect-error'?: boolean;
   'ts-ignore'?: boolean;
@@ -31,8 +31,8 @@ const defaultOptions: Options = {
   'ts-expect-error': true,
   'ts-ignore': true,
   'ts-nocheck': true,
-  'ts-check': false
-}
+  'ts-check': false,
+};
 ```
 
 A value of `true` for a particular directive means that this rule will report if it finds any usage of said directive.

packages/eslint-plugin/docs/rules/class-literal-property-style.md

@@ -1,7 +1,7 @@
 # Ensures that literals on classes are exposed in a consistent style (`class-literal-property-style`)
 
 When writing TypeScript applications, it's typically safe to store literal values on classes using fields with the `readonly` modifier to prevent them from being reassigned.
-When writing TypeScript libraries that could be used by Javascript users however, it's typically safer to expose these literals using `getter`s, since the `readonly` modifier is enforced at compile type.
+When writing TypeScript libraries that could be used by JavaScript users however, it's typically safer to expose these literals using `getter`s, since the `readonly` modifier is enforced at compile type.
 
 ## Rule Details
 
@@ -11,7 +11,7 @@ By default this rule prefers the `fields` style as it means JS doesn't have to s
 Note that this rule only checks for constant _literal_ values (string, template string, number, bigint, boolean, regexp, null). It does not check objects or arrays, because a readonly field behaves differently to a getter in those cases. It also does not check functions, as it is a common pattern to use readonly fields with arrow function values as auto-bound methods.
 This is because these types can be mutated and carry with them more complex implications about their usage.
 
-#### The `fields` style
+### The `fields` style
 
 This style checks for any getter methods that return literal values, and requires them to be defined using fields with the `readonly` modifier instead.
 
@@ -50,7 +50,7 @@ class Mx {
 }
 ```
 
-#### The `getters` style
+### The `getters` style
 
 This style checks for any `readonly` fields that are assigned literal values, and requires them to be defined as getters instead.
 This style pairs well with the [`@typescript-eslint/prefer-readonly`](prefer-readonly.md) rule,

packages/eslint-plugin/docs/rules/no-base-to-string.md

@@ -1,6 +1,6 @@
 # Requires that `.toString()` is only called on objects which provide useful information when stringified (`no-base-to-string`)
 
-JavaScript will call `toString()` on an object when it is converted to a string, such as when `+` adding to a string or in <code>`${}`</code> template literals.
+JavaScript will call `toString()` on an object when it is converted to a string, such as when `+` adding to a string or in `${}` template literals.
 
 The default Object `.toString()` returns `"[object Object]"`, so this rule requires stringified objects define a more useful `.toString()` method.
 

packages/eslint-plugin/docs/rules/prefer-as-const.md

@@ -25,4 +25,4 @@ let foo = { bar: 'baz' };
 
 ## When Not To Use It
 
-If you are using typescript < 3.4
+If you are using TypeScript < 3.4

packages/parser/README.md

@@ -67,7 +67,7 @@ Default `false`.
 
 Enable parsing JSX when `true`. More details can be found [here](https://www.typescriptlang.org/docs/handbook/jsx.html).
 
-**NOTE:** this setting does not affect known file types (`.js`, `.jsx`, `.ts`, `.tsx`, `.json`) because the typescript compiler has its own internal handling for known file extensions. The exact behavior is as follows:
+**NOTE:** this setting does not affect known file types (`.js`, `.jsx`, `.ts`, `.tsx`, `.json`) because the TypeScript compiler has its own internal handling for known file extensions. The exact behavior is as follows:
 
 - if `parserOptions.project` is _not_ provided:
   - `.js`, `.jsx`, `.tsx` files are parsed as if this is true.