mirror of
https://github.com/DavidAnson/markdownlint.git
synced 2025-09-22 05:40:48 +02:00
Improve README.md/CustomRules.md, add CustomRules.md/Rules.md to tests.
This commit is contained in:
David Anson
parent
e0e5ce555a
commit
94d5432f4d
4 changed files with 58 additions and 11 deletions
|
|
@ -273,7 +273,8 @@ Type: `Array` of `Object`
|
|||
List of custom rules to include with the default rule set for linting.
|
||||
|
||||
Each array element should define a rule. Rules are typically exported by another
|
||||
package, but can be defined inline.
|
||||
package, but can be defined locally. Custom rules are identified by the
|
||||
[keyword `markdownlint-rule` on npm](https://www.npmjs.com/search?q=keywords:markdownlint-rule).
|
||||
|
||||
Example:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,15 @@
|
|||
# Custom Rules
|
||||
|
||||
In addition to its built-in rules, `markdownlint` lets you enhance the linting experience by passing a list of custom rules using the [`options.customRules` property](../README.md#optionscustomrules).
|
||||
Custom rules can do everything the built-in rules can and are defined inline or imported from another package ([keyword `markdownlint-rule` on npm](https://www.npmjs.com/search?q=keywords:markdownlint-rule)).
|
||||
In addition to its built-in rules, `markdownlint` lets you enhance the linting experience by passing a list of custom rules using the
|
||||
[`options.customRules` property](../README.md#optionscustomrules).
|
||||
Custom rules can do everything the built-in rules can and are defined inline or imported from another package
|
||||
([keyword `markdownlint-rule` on npm](https://www.npmjs.com/search?q=keywords:markdownlint-rule)).
|
||||
Custom rules can be disabled, enabled, and customized using the same syntax as built-in rules.
|
||||
|
||||
## Authoring
|
||||
|
||||
Rules are defined by a name (or multiple names), a description, an optional link to more information, one or more tags, and a function that implements the rule's behavior.
|
||||
Rules are defined by a name (or multiple names), a description, an optional link to more information, one or more tags, and a function that implements
|
||||
the rule's behavior.
|
||||
That function is called once for each file/string input and is passed the parsed input and a function to log any violations.
|
||||
|
||||
A simple rule implementation looks like:
|
||||
|
|
@ -58,11 +61,12 @@ A rule is implemented as an `Object` with one optional and four required propert
|
|||
performed before the insert):
|
||||
- `lineNumber` is an optional `Number` specifying the 1-based line number of the edit.
|
||||
- `editColumn` is an optional `Number` specifying the 1-based column number of the edit.
|
||||
- `deleteCount` is an optional `Number` specifying the count of characters to delete.
|
||||
- `deleteCount` is an optional `Number` specifying the number of characters to delete (the value `-1` is used to delete the line).
|
||||
- `insertText` is an optional `String` specifying the text to insert. `\n` is the platform-independent way to add
|
||||
a line break; line breaks should be added at the beginning of a line instead of at the end).
|
||||
|
||||
The collection of helper functions shared by the built-in rules is available for use by custom rules in the [markdownlint-rule-helpers package](https://www.npmjs.com/package/markdownlint-rule-helpers).
|
||||
The collection of helper functions shared by the built-in rules is available for use by custom rules in the
|
||||
[markdownlint-rule-helpers package](https://www.npmjs.com/package/markdownlint-rule-helpers).
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
|
|||
23
doc/Rules.md
23
doc/Rules.md
|
|
@ -388,12 +388,16 @@ with spaces instead.
|
|||
|
||||
Example:
|
||||
|
||||
<!-- markdownlint-disable no-hard-tabs -->
|
||||
|
||||
```markdown
|
||||
Some text
|
||||
|
||||
* hard tab character used to indent the list item
|
||||
```
|
||||
|
||||
<!-- markdownlint-enable no-hard-tabs -->
|
||||
|
||||
Corrected example:
|
||||
|
||||
```markdown
|
||||
|
|
@ -488,8 +492,12 @@ Tags: line_length
|
|||
|
||||
Aliases: line-length
|
||||
|
||||
<!-- markdownlint-disable line-length -->
|
||||
|
||||
Parameters: line_length, heading_line_length, code_block_line_length, code_blocks, tables, headings, headers, strict, stern (number; default 80 for *_length, boolean; default true (except strict/stern which default false))
|
||||
|
||||
<!-- markdownlint-enable line-length -->
|
||||
|
||||
> If `headings` is not provided, `headers` (deprecated) will be used.
|
||||
|
||||
This rule is triggered when there are lines that are longer than the
|
||||
|
|
@ -540,12 +548,16 @@ Fixable: Most violations can be fixed by tooling
|
|||
This rule is triggered when there are code blocks showing shell commands to be
|
||||
typed, and *all* of the shell commands are preceded by dollar signs ($):
|
||||
|
||||
<!-- markdownlint-disable commands-show-output -->
|
||||
|
||||
```markdown
|
||||
$ ls
|
||||
$ cat foo
|
||||
$ less bar
|
||||
```
|
||||
|
||||
<!-- markdownlint-enable commands-show-output -->
|
||||
|
||||
The dollar signs are unnecessary in this situation, and should not be
|
||||
included:
|
||||
|
||||
|
|
@ -1046,7 +1058,10 @@ This rule supports 0-prefixing ordered list items for uniform indentation:
|
|||
...
|
||||
```
|
||||
|
||||
Note: This rule will report violations for cases like the following where an improperly-indented code block (or similar) appears between two list items and "breaks" the list in two:
|
||||
Note: This rule will report violations for cases like the following where an improperly-indented code block (or similar) appears between two list
|
||||
items and "breaks" the list in two:
|
||||
|
||||
<!-- markdownlint-disable code-fence-style -->
|
||||
|
||||
~~~markdown
|
||||
1. First list
|
||||
|
|
@ -1070,6 +1085,8 @@ The fix is to indent the code block so it becomes part of the preceding list ite
|
|||
2. Still first list
|
||||
~~~
|
||||
|
||||
<!-- markdownlint-enable code-fence-style -->
|
||||
|
||||
Rationale: Consistent formatting makes it easier to understand a document.
|
||||
|
||||
<a name="md030"></a>
|
||||
|
|
@ -1755,6 +1772,8 @@ the same document.
|
|||
|
||||
In the default configuration this rule reports a violation for the following document:
|
||||
|
||||
<!-- markdownlint-disable code-block-style -->
|
||||
|
||||
Some text.
|
||||
|
||||
# Indented code
|
||||
|
|
@ -1767,6 +1786,8 @@ In the default configuration this rule reports a violation for the following doc
|
|||
|
||||
More text.
|
||||
|
||||
<!-- markdownlint-enable code-block-style -->
|
||||
|
||||
To fix violations of this rule, use a consistent style (either indenting or code fences).
|
||||
|
||||
The specified style can be specific (`fenced`, `indented`) or simply require that usage
|
||||
|
|
|
|||
|
|
@ -182,18 +182,19 @@ fs.readdirSync("./test")
|
|||
// @ts-ignore
|
||||
.forEach((file) => tape(file, createTestForFile(path.join("./test", file))));
|
||||
|
||||
tape("projectFiles", (test) => {
|
||||
tape("projectFilesNoInlineConfig", (test) => {
|
||||
test.plan(2);
|
||||
const options = {
|
||||
"files": [
|
||||
"README.md",
|
||||
"CONTRIBUTING.md",
|
||||
"doc/CustomRules.md",
|
||||
"helpers/README.md"
|
||||
],
|
||||
"noInlineConfig": true,
|
||||
"config": {
|
||||
"MD013": { "line_length": 150 },
|
||||
"MD024": false
|
||||
"line-length": { "line_length": 150 },
|
||||
"no-duplicate-heading": false
|
||||
}
|
||||
};
|
||||
markdownlint(options, function callback(err, actual) {
|
||||
|
|
@ -201,6 +202,7 @@ tape("projectFiles", (test) => {
|
|||
const expected = {
|
||||
"README.md": [],
|
||||
"CONTRIBUTING.md": [],
|
||||
"doc/CustomRules.md": [],
|
||||
"helpers/README.md": []
|
||||
};
|
||||
test.deepLooseEqual(actual, expected, "Issue(s) with project files.");
|
||||
|
|
@ -208,6 +210,25 @@ tape("projectFiles", (test) => {
|
|||
});
|
||||
});
|
||||
|
||||
tape("projectFilesInlineConfig", (test) => {
|
||||
test.plan(2);
|
||||
const options = {
|
||||
"files": [ "doc/Rules.md" ],
|
||||
"config": {
|
||||
"line-length": { "line_length": 150 },
|
||||
"no-inline-html": false
|
||||
}
|
||||
};
|
||||
markdownlint(options, function callback(err, actual) {
|
||||
test.ifError(err);
|
||||
const expected = {
|
||||
"doc/Rules.md": []
|
||||
};
|
||||
test.deepLooseEqual(actual, expected, "Issue(s) with project files.");
|
||||
test.end();
|
||||
});
|
||||
});
|
||||
|
||||
tape("resultFormattingV0", (test) => {
|
||||
test.plan(4);
|
||||
const options = {
|
||||
|
|
@ -1509,7 +1530,7 @@ tape("readme", (test) => {
|
|||
});
|
||||
});
|
||||
|
||||
tape("doc", (test) => {
|
||||
tape("rules", (test) => {
|
||||
test.plan(336);
|
||||
fs.readFile("doc/Rules.md", helpers.utf8Encoding,
|
||||
(err, contents) => {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue