From 2dbaa9e0a8bcbd0dabc003d7126c2802b296039f Mon Sep 17 00:00:00 2001 From: Flo Edelmann Date: Fri, 18 Mar 2022 16:13:38 +0100 Subject: [PATCH 01/17] Add rule docs headings checker --- tools/update-docs.js | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/tools/update-docs.js b/tools/update-docs.js index a7b847eee..12deca0ea 100644 --- a/tools/update-docs.js +++ b/tools/update-docs.js @@ -87,6 +87,8 @@ class DocFile { write() { fs.writeFileSync(this.filePath, this.content) + + return this } updateFileIntro() { @@ -225,6 +227,42 @@ ${ return this } + + checkHeadings() { + const headingPattern = /^## .*$/gm + + const knownHeadings = [ + '## :book: Rule Details', + '## :wrench: Options', + '## :rocket: Suggestion', + '## :mute: When Not To Use It', + '## :couple: Related Rules', + '## :books: Further Reading', + '## :rocket: Version', + '## :mag: Implementation' + ] + + const foundHeadings = [...this.content.matchAll(headingPattern)] + + let previousHeadingIndex = -1 + for (const [heading] of foundHeadings) { + const headingIndex = knownHeadings.indexOf(heading) + + if (headingIndex === -1) { + throw new Error(`Unknown heading '${heading}' in '${this.filePath}'`) + } + + if (headingIndex < previousHeadingIndex) { + throw new Error( + `Heading '${heading}' should be above '${knownHeadings[previousHeadingIndex]}' in '${this.filePath}'` + ) + } + + previousHeadingIndex = headingIndex + } + + return this + } } for (const rule of rules) { @@ -235,4 +273,5 @@ for (const rule of rules) { .updateFileIntro() .adjustCodeBlocks() .write() + .checkHeadings() } From cf53447b204c56ac3e50760e565bb4f4055fa2f5 Mon Sep 17 00:00:00 2001 From: Flo Edelmann Date: Fri, 18 Mar 2022 15:50:00 +0100 Subject: [PATCH 02/17] Fix typo in rule docs heading --- docs/rules/new-line-between-multi-line-property.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules/new-line-between-multi-line-property.md b/docs/rules/new-line-between-multi-line-property.md index 4af4e59c3..c8cee19ee 100644 --- a/docs/rules/new-line-between-multi-line-property.md +++ b/docs/rules/new-line-between-multi-line-property.md @@ -75,7 +75,7 @@ export default { -## :wrench: Option +## :wrench: Options ```json { From d368754eefe230b933212fcb6c7966e257883f6f Mon Sep 17 00:00:00 2001 From: Flo Edelmann Date: Fri, 18 Mar 2022 16:31:31 +0100 Subject: [PATCH 03/17] Standardize heading order in rule docs --- docs/rules/custom-event-name-casing.md | 10 ++--- docs/rules/prop-name-casing.md | 8 ++-- docs/rules/require-default-prop.md | 8 ++-- docs/rules/sort-keys.md | 58 +++++++++++++------------- docs/rules/v-on-event-hyphenation.md | 10 ++--- 5 files changed, 47 insertions(+), 47 deletions(-) diff --git a/docs/rules/custom-event-name-casing.md b/docs/rules/custom-event-name-casing.md index ecc130fbe..a2c4d3644 100644 --- a/docs/rules/custom-event-name-casing.md +++ b/docs/rules/custom-event-name-casing.md @@ -163,6 +163,11 @@ export default { +## :couple: Related Rules + +- [vue/v-on-event-hyphenation](./v-on-event-hyphenation.md) +- [vue/prop-name-casing](./prop-name-casing.md) + ## :books: Further Reading - [Guide - Custom Events] @@ -171,11 +176,6 @@ export default { [Guide - Custom Events]: https://vuejs.org/guide/components/events.html [Guide (for v2) - Custom Events]: https://v2.vuejs.org/v2/guide/components-custom-events.html -## :couple: Related Rules - -- [vue/v-on-event-hyphenation](./v-on-event-hyphenation.md) -- [vue/prop-name-casing](./prop-name-casing.md) - ## :rocket: Version This rule was introduced in eslint-plugin-vue v7.0.0 diff --git a/docs/rules/prop-name-casing.md b/docs/rules/prop-name-casing.md index 2cdeec52a..4f32bfa17 100644 --- a/docs/rules/prop-name-casing.md +++ b/docs/rules/prop-name-casing.md @@ -66,15 +66,15 @@ export default { -## :books: Further Reading - -- [Style guide - Prop name casing](https://vuejs.org/style-guide/rules-strongly-recommended.html#prop-name-casing) - ## :couple: Related Rules - [vue/attribute-hyphenation](./attribute-hyphenation.md) - [vue/custom-event-name-casing](./custom-event-name-casing.md) +## :books: Further Reading + +- [Style guide - Prop name casing](https://vuejs.org/style-guide/rules-strongly-recommended.html#prop-name-casing) + ## :rocket: Version This rule was introduced in eslint-plugin-vue v4.3.0 diff --git a/docs/rules/require-default-prop.md b/docs/rules/require-default-prop.md index 4d97e16c7..44fba0f29 100644 --- a/docs/rules/require-default-prop.md +++ b/docs/rules/require-default-prop.md @@ -61,14 +61,14 @@ export default { Nothing. -## :books: Further Reading - -- [Style guide - Prop definitions](https://vuejs.org/style-guide/rules-essential.html#use-detailed-prop-definitions) - ## :couple: Related Rules - [vue/no-boolean-default](./no-boolean-default.md) +## :books: Further Reading + +- [Style guide - Prop definitions](https://vuejs.org/style-guide/rules-essential.html#use-detailed-prop-definitions) + ## :rocket: Version This rule was introduced in eslint-plugin-vue v3.13.0 diff --git a/docs/rules/sort-keys.md b/docs/rules/sort-keys.md index b573e4eaa..b77bf79c7 100644 --- a/docs/rules/sort-keys.md +++ b/docs/rules/sort-keys.md @@ -11,35 +11,6 @@ since: v6.2.0 This rule is almost the same rule as core [sort-keys] rule but it will not error on top component properties allowing that order to be enforced with `order-in-components`. -## :wrench: Options - -```json -{ - "vue/sort-keys": ["error", "asc", { - "caseSensitive": true, - "ignoreChildrenOf": ["model"], - "ignoreGrandchildrenOf": ["computed", "directives", "inject", "props", "watch"], - "minKeys": 2, - "natural": false - }] -} -``` - -The 1st option is `"asc"` or `"desc"`. - -* `"asc"` (default) - enforce properties to be in ascending order. -* `"desc"` - enforce properties to be in descending order. - -The 2nd option is an object which has 5 properties. - -* `caseSensitive` - if `true`, enforce properties to be in case-sensitive order. Default is `true`. -* `ignoreChildrenOf` - an array of properties to ignore the children of. Default is `["model"]` -* `ignoreGrandchildrenOf` - an array of properties to ignore the grandchildren sort order. Default is `["computed", "directives", "inject", "props", "watch"]` -* `minKeys` - Specifies the minimum number of keys that an object should have in order for the object's unsorted keys to produce an error. Default is `2`, which means by default all objects with unsorted keys will result in lint errors. -* `natural` - if `true`, enforce properties to be in natural order. Default is `false`. Natural Order compares strings containing combination of letters and numbers in the way a human being would sort. It basically sorts numerically, instead of sorting alphabetically. So the number 10 comes after the number 3 in Natural Sorting. - -While using this rule, you may disable the normal `sort-keys` rule. This rule will apply to plain js files as well as Vue component scripts. - ## :book: Rule Details This rule forces many dictionary properties to be in alphabetical order while allowing `order-in-components`, property details, @@ -99,6 +70,35 @@ export default { +## :wrench: Options + +```json +{ + "vue/sort-keys": ["error", "asc", { + "caseSensitive": true, + "ignoreChildrenOf": ["model"], + "ignoreGrandchildrenOf": ["computed", "directives", "inject", "props", "watch"], + "minKeys": 2, + "natural": false + }] +} +``` + +The 1st option is `"asc"` or `"desc"`. + +* `"asc"` (default) - enforce properties to be in ascending order. +* `"desc"` - enforce properties to be in descending order. + +The 2nd option is an object which has 5 properties. + +* `caseSensitive` - if `true`, enforce properties to be in case-sensitive order. Default is `true`. +* `ignoreChildrenOf` - an array of properties to ignore the children of. Default is `["model"]` +* `ignoreGrandchildrenOf` - an array of properties to ignore the grandchildren sort order. Default is `["computed", "directives", "inject", "props", "watch"]` +* `minKeys` - Specifies the minimum number of keys that an object should have in order for the object's unsorted keys to produce an error. Default is `2`, which means by default all objects with unsorted keys will result in lint errors. +* `natural` - if `true`, enforce properties to be in natural order. Default is `false`. Natural Order compares strings containing combination of letters and numbers in the way a human being would sort. It basically sorts numerically, instead of sorting alphabetically. So the number 10 comes after the number 3 in Natural Sorting. + +While using this rule, you may disable the normal `sort-keys` rule. This rule will apply to plain js files as well as Vue component scripts. + ## :books: Further Reading - [sort-keys] diff --git a/docs/rules/v-on-event-hyphenation.md b/docs/rules/v-on-event-hyphenation.md index fd8b9f48a..a462e414e 100644 --- a/docs/rules/v-on-event-hyphenation.md +++ b/docs/rules/v-on-event-hyphenation.md @@ -103,17 +103,17 @@ Don't use hyphenated name but allow custom event names +## :couple: Related Rules + +- [vue/custom-event-name-casing](./custom-event-name-casing.md) +- [vue/attribute-hyphenation](./attribute-hyphenation.md) + ## :books: Further Reading - [Guide - Custom Events] [Guide - Custom Events]: https://v3.vuejs.org/guide/component-custom-events.html -## :couple: Related Rules - -- [vue/custom-event-name-casing](./custom-event-name-casing.md) -- [vue/attribute-hyphenation](./attribute-hyphenation.md) - ## :rocket: Version This rule was introduced in eslint-plugin-vue v7.4.0 From bd20167ca4ee88fb7c61c5f31e506dceb14332eb Mon Sep 17 00:00:00 2001 From: Flo Edelmann Date: Fri, 18 Mar 2022 16:49:19 +0100 Subject: [PATCH 04/17] Add markdownlint --- .markdownlint.yml | 23 +++++++++++++++++++++++ .markdownlintignore | 1 + package.json | 5 +++-- 3 files changed, 27 insertions(+), 2 deletions(-) create mode 100644 .markdownlint.yml create mode 100644 .markdownlintignore diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 000000000..cb76e21d5 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,23 @@ +line-length: false +single-title: false +no-inline-html: + allowed_elements: + - badge + - eslint-code-block + - sup + +# enforce consistency +code-block-style: + style: fenced +code-fence-style: + style: backtick +emphasis-style: + style: asterisk +heading-style: + style: atx +hr-style: + style: --- +strong-style: + style: asterisk +ul-style: + style: dash diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 000000000..3c3629e64 --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1 @@ +node_modules diff --git a/package.json b/package.json index 7abecb3f1..4b843c06b 100644 --- a/package.json +++ b/package.json @@ -12,8 +12,8 @@ "cover": "npm run cover:test && npm run cover:report", "cover:test": "nyc npm run test:base -- --timeout 60000", "cover:report": "nyc report --reporter=html", - "lint": "eslint . --rulesdir eslint-internal-rules", - "lint:fix": "eslint . --rulesdir eslint-internal-rules --fix", + "lint": "eslint . --rulesdir eslint-internal-rules && markdownlint \"**/*.md\"", + "lint:fix": "eslint . --rulesdir eslint-internal-rules --fix && markdownlint \"**/*.md\" --fix", "tsc": "tsc", "preversion": "npm test && git add .", "version": "env-cmd -e version npm run update && npm run lint -- --fix && git add .", @@ -79,6 +79,7 @@ "eslint-plugin-vue": "file:.", "espree": "^9.0.0", "lodash": "^4.17.21", + "markdownlint-cli": "^0.31.1", "mocha": "^7.1.2", "nyc": "^15.1.0", "prettier": "^2.4.1", From 20bc1557f99ca09af70729e1534253e65965c59b Mon Sep 17 00:00:00 2001 From: Flo Edelmann Date: Fri, 18 Mar 2022 16:53:58 +0100 Subject: [PATCH 05/17] Use `dash` style for all unordered lists `ul-style` MarkdownLint rule --- .../no-spaces-around-equal-signs-in-attribute.md | 2 +- docs/rules/no-use-v-if-with-v-for.md | 4 ++-- docs/rules/sort-keys.md | 14 +++++++------- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/rules/no-spaces-around-equal-signs-in-attribute.md b/docs/rules/no-spaces-around-equal-signs-in-attribute.md index f13feee2a..bb3a7ff6c 100644 --- a/docs/rules/no-spaces-around-equal-signs-in-attribute.md +++ b/docs/rules/no-spaces-around-equal-signs-in-attribute.md @@ -43,7 +43,7 @@ HTML5 allows spaces around equal signs. But space-less is easier to read, and gr ## :books: Further Reading -* [HTML5 Style Guide - W3Schools *Spaces and Equal Signs*](https://www.w3schools.com/html/html5_syntax.asp) +- [HTML5 Style Guide - W3Schools *Spaces and Equal Signs*](https://www.w3schools.com/html/html5_syntax.asp) ## :rocket: Version diff --git a/docs/rules/no-use-v-if-with-v-for.md b/docs/rules/no-use-v-if-with-v-for.md index b8de1a17f..d5c2fa8aa 100644 --- a/docs/rules/no-use-v-if-with-v-for.md +++ b/docs/rules/no-use-v-if-with-v-for.md @@ -16,8 +16,8 @@ since: v4.6.0 This rule is aimed at preventing the use of `v-for` directives together with `v-if` directives on the same element. There are two common cases where this can be tempting: - * To filter items in a list (e.g. `v-for="user in users" v-if="user.isActive"`). In these cases, replace `users` with a new computed property that returns your filtered list (e.g. `activeUsers`). - * To avoid rendering a list if it should be hidden (e.g. `v-for="user in users" v-if="shouldShowUsers"`). In these cases, move the `v-if` to a container element (e.g. `ul`, `ol`). + - To filter items in a list (e.g. `v-for="user in users" v-if="user.isActive"`). In these cases, replace `users` with a new computed property that returns your filtered list (e.g. `activeUsers`). + - To avoid rendering a list if it should be hidden (e.g. `v-for="user in users" v-if="shouldShowUsers"`). In these cases, move the `v-if` to a container element (e.g. `ul`, `ol`). diff --git a/docs/rules/sort-keys.md b/docs/rules/sort-keys.md index b77bf79c7..26e4e6839 100644 --- a/docs/rules/sort-keys.md +++ b/docs/rules/sort-keys.md @@ -86,16 +86,16 @@ export default { The 1st option is `"asc"` or `"desc"`. -* `"asc"` (default) - enforce properties to be in ascending order. -* `"desc"` - enforce properties to be in descending order. +- `"asc"` (default) - enforce properties to be in ascending order. +- `"desc"` - enforce properties to be in descending order. The 2nd option is an object which has 5 properties. -* `caseSensitive` - if `true`, enforce properties to be in case-sensitive order. Default is `true`. -* `ignoreChildrenOf` - an array of properties to ignore the children of. Default is `["model"]` -* `ignoreGrandchildrenOf` - an array of properties to ignore the grandchildren sort order. Default is `["computed", "directives", "inject", "props", "watch"]` -* `minKeys` - Specifies the minimum number of keys that an object should have in order for the object's unsorted keys to produce an error. Default is `2`, which means by default all objects with unsorted keys will result in lint errors. -* `natural` - if `true`, enforce properties to be in natural order. Default is `false`. Natural Order compares strings containing combination of letters and numbers in the way a human being would sort. It basically sorts numerically, instead of sorting alphabetically. So the number 10 comes after the number 3 in Natural Sorting. +- `caseSensitive` - if `true`, enforce properties to be in case-sensitive order. Default is `true`. +- `ignoreChildrenOf` - an array of properties to ignore the children of. Default is `["model"]` +- `ignoreGrandchildrenOf` - an array of properties to ignore the grandchildren sort order. Default is `["computed", "directives", "inject", "props", "watch"]` +- `minKeys` - Specifies the minimum number of keys that an object should have in order for the object's unsorted keys to produce an error. Default is `2`, which means by default all objects with unsorted keys will result in lint errors. +- `natural` - if `true`, enforce properties to be in natural order. Default is `false`. Natural Order compares strings containing combination of letters and numbers in the way a human being would sort. It basically sorts numerically, instead of sorting alphabetically. So the number 10 comes after the number 3 in Natural Sorting. While using this rule, you may disable the normal `sort-keys` rule. This rule will apply to plain js files as well as Vue component scripts. From 7993a81d804639a16f171975146620d531b7a750 Mon Sep 17 00:00:00 2001 From: Flo Edelmann Date: Fri, 18 Mar 2022 17:27:02 +0100 Subject: [PATCH 06/17] Standardize unordered list indentation `ul-indent` MarkdownLint rule --- docs/rules/html-closing-bracket-newline.md | 8 ++++---- docs/rules/html-closing-bracket-spacing.md | 12 ++++++------ docs/rules/html-comment-content-newline.md | 22 +++++++++++----------- docs/rules/html-comment-content-spacing.md | 14 +++++++------- docs/rules/no-parsing-error.md | 8 ++++---- docs/rules/no-use-v-if-with-v-for.md | 4 ++-- 6 files changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/rules/html-closing-bracket-newline.md b/docs/rules/html-closing-bracket-newline.md index df3a8ac3c..ac6c505d8 100644 --- a/docs/rules/html-closing-bracket-newline.md +++ b/docs/rules/html-closing-bracket-newline.md @@ -66,11 +66,11 @@ This rule aims to warn the right angle brackets which are at the location other ``` - `singleline` ... the configuration for single-line elements. It's a single-line element if the element does not have attributes or the last attribute is on the same line as the opening bracket. - - `"never"` (default) ... disallow line breaks before the closing bracket. - - `"always"` ... require one line break before the closing bracket. + - `"never"` (default) ... disallow line breaks before the closing bracket. + - `"always"` ... require one line break before the closing bracket. - `multiline` ... the configuration for multiline elements. It's a multiline element if the last attribute is not on the same line of the opening bracket. - - `"never"` ... disallow line breaks before the closing bracket. - - `"always"` (default) ... require one line break before the closing bracket. + - `"never"` ... disallow line breaks before the closing bracket. + - `"always"` (default) ... require one line break before the closing bracket. Plus, you can use [`vue/html-indent`](./html-indent.md) rule to enforce indent-level of the closing brackets. diff --git a/docs/rules/html-closing-bracket-spacing.md b/docs/rules/html-closing-bracket-spacing.md index ee2a608d2..6bbbff216 100644 --- a/docs/rules/html-closing-bracket-spacing.md +++ b/docs/rules/html-closing-bracket-spacing.md @@ -55,14 +55,14 @@ This rule aims to enforce consistent spacing style before closing brackets `>` o ``` - `startTag` (`"always" | "never"`) ... Setting for the `>` of start tags (e.g. `
`). Default is `"never"`. - - `"always"` ... requires one or more spaces. - - `"never"` ... disallows spaces. + - `"always"` ... requires one or more spaces. + - `"never"` ... disallows spaces. - `endTag` (`"always" | "never"`) ... Setting for the `>` of end tags (e.g. `
`). Default is `"never"`. - - `"always"` ... requires one or more spaces. - - `"never"` ... disallows spaces. + - `"always"` ... requires one or more spaces. + - `"never"` ... disallows spaces. - `selfClosingTag` (`"always" | "never"`) ... Setting for the `/>` of self-closing tags (e.g. `
`). Default is `"always"`. - - `"always"` ... requires one or more spaces. - - `"never"` ... disallows spaces. + - `"always"` ... requires one or more spaces. + - `"never"` ... disallows spaces. ### `"startTag": "always", "endTag": "always", "selfClosingTag": "always"` diff --git a/docs/rules/html-comment-content-newline.md b/docs/rules/html-comment-content-newline.md index eb543a753..ce7391d21 100644 --- a/docs/rules/html-comment-content-newline.md +++ b/docs/rules/html-comment-content-newline.md @@ -56,21 +56,21 @@ This rule will enforce consistency of line break after the ``. - - `"always"` ... require one line break after the ``. - - `multiline` ... the configuration for multiline comments. - - `"never"` ... disallow line breaks after the ``. - - `"always"` (default) ... require one line break after the ``. + - `singleline` ... the configuration for single-line comments. + - `"never"` (default) ... disallow line breaks after the ``. + - `"always"` ... require one line break after the ``. + - `multiline` ... the configuration for multiline comments. + - `"never"` ... disallow line breaks after the ``. + - `"always"` (default) ... require one line break after the ``. - You can also set the same value for both `singleline` and `multiline` by specifies a string. + You can also set the same value for both `singleline` and `multiline` by specifies a string. - This rule can also take a 2nd option, an object with the following key: `"exceptions"`. - - The `"exceptions"` value is an array of string patterns which are considered exceptions to the rule. + - The `"exceptions"` value is an array of string patterns which are considered exceptions to the rule. - ```json - "vue/html-comment-content-newline": ["error", { ... }, { "exceptions": ["*"] }] - ``` + ```json + "vue/html-comment-content-newline": ["error", { ... }, { "exceptions": ["*"] }] + ``` ### `"always"` diff --git a/docs/rules/html-comment-content-spacing.md b/docs/rules/html-comment-content-spacing.md index 70d6d78a9..771d12ac1 100644 --- a/docs/rules/html-comment-content-spacing.md +++ b/docs/rules/html-comment-content-spacing.md @@ -48,17 +48,17 @@ Whitespace after the `` makes it easier to read text in ``` - The first is a string which be either `"always"` or `"never"`. The default is `"always"`. - - `"always"` (default) ... there must be at least one whitespace at after the ``. - - `"never"` ... there should be no whitespace at after the ``. + - `"always"` (default) ... there must be at least one whitespace at after the ``. + - `"never"` ... there should be no whitespace at after the ``. - This rule can also take a 2nd option, an object with the following key: `"exceptions"`. - - The `"exceptions"` value is an array of string patterns which are considered exceptions to the rule. - Please note that exceptions are ignored if the first argument is `"never"`. + - The `"exceptions"` value is an array of string patterns which are considered exceptions to the rule. + Please note that exceptions are ignored if the first argument is `"never"`. - ```json - "vue/html-comment-content-spacing": ["error", "always", { "exceptions": ["*"] }] - ``` + ```json + "vue/html-comment-content-spacing": ["error", "always", { "exceptions": ["*"] }] + ``` ### `"always"` diff --git a/docs/rules/no-parsing-error.md b/docs/rules/no-parsing-error.md index 811fd06af..61832037f 100644 --- a/docs/rules/no-parsing-error.md +++ b/docs/rules/no-parsing-error.md @@ -16,10 +16,10 @@ This rule reports syntax errors in `