Skip to content

Commit e027874

Browse files
ethanpalmethanpalm
authored
Add auto-review documentation (github#39820)
1 parent 2ed088d commit e027874

File tree

2 files changed

+136
-0
lines changed

2 files changed

+136
-0
lines changed

‎content/contributing/collaborating-on-github-docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,6 @@ children:
99
- /about-contributing-to-github-docs
1010
- /using-git-on-github-docs
1111
- /using-the-todocs-placeholder-to-leave-notes
12+
- /using-the-content-linter
1213
- /label-reference
1314
---

‎content/contributing/collaborating-on-github-docs/using-the-content-linter.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Using the content linter
3+
intro: 'You can use content linter to check your contributions for errors.'
4+
product: '{% data reusables.contributing.product-note %}'
5+
versions:
6+
feature: 'contributing'
7+
---
8+
9+
## About the {% data variables.product.prodname_docs %} content linter
10+
11+
Our content linter enforces style guide rules in our Markdown content.
12+
13+
The linter uses [`markdownlint`](https://github.com/DavidAnson/markdownlint) as the framework to perform checks, report flaws, and automatically fix content, when possible. This framework flexibly runs specific rules, gives descriptive error messages, and fixes errors. The {% data variables.product.prodname_docs %} content linter uses several existing `markdownlint` rules and additional custom rules to check the Markdown content in our `content` and `data` directories. Our custom rules implement checks that are either not yet available in the `markdownlint` framework or are specific to {% data variables.product.prodname_docs %} content. Rules check the syntax for both Markdown and Liquid.
14+
15+
## Running the {% data variables.product.prodname_docs %} content linter
16+
17+
The {% data variables.product.prodname_docs %} content linter will run automatically on pre-commit, but you can also run it manually.
18+
19+
### Automatically run the linter on pre-commit
20+
21+
The content linter rules that are marked with a severity of `error` run on a pre-commit Git hook. For a list of the rules that will run on the pre-commit hook, see "[Errors](#errors)."
22+
23+
When you are writing content locally and commit files using the command line, those staged files will automatically be linted by the content linter. If any errors are reported, your commit will not complete. Fix the reported errors, and then commit your changes again. Any errors that are reported must be fixed to prevent introducing errors in the content that are in violation of the {% data variables.product.prodname_docs %} style guide.
24+
25+
If you are editing a file in the {% data variables.product.prodname_dotcom %} UI, you will not be able to automatically run the linter on a commit.
26+
27+
### Manually run the linter
28+
29+
#### Run the linter on staged and changed files
30+
31+
Use the following command to run the linter locally on your staged and changed files. It will output both `warning` and `error` severity flaws.
32+
33+
```shell
34+
npm run lint-content
35+
```
36+
37+
#### Run the linter on staged and changed files and only report errors
38+
39+
Use the following command to run the linter locally on your staged and changed files, and report only `error` severity flaws.
40+
41+
```shell
42+
npm run lint-content -- --errors
43+
```
44+
45+
#### Run the linter on specific files or directories
46+
47+
Use the following command to run the linter locally on specific files or directories. Separate multiple paths with a space. You can include both files and directories in the same command.
48+
49+
```shell
50+
npm run lint-content -- --paths content/FILENAME.md content/DIRECTORY
51+
```
52+
53+
#### Automatically fix errors that can be fixed
54+
55+
If an error has `fixable: true` in its description, you can use the following commands to automatically fix them.
56+
57+
Run this command to fix staged and changed files only:
58+
59+
```shell
60+
npm run lint-content -- --fix
61+
```
62+
63+
Run this command to fix specific files or directories:
64+
65+
```shell
66+
npm run lint-content -- --fix --paths content/FILENAME.md content/DIRECTORY
67+
```
68+
69+
#### Run a specific set of linter rules
70+
71+
Use the following command to run one or more specific linter rules. These examples run the `heading-increment` and `code-fence-line-length` rules. Replace `heading-increment code-fence-line-length` with one or more linter aliases that you would like to run. To see the list of linter rules you can pass to this option, run `npm run lint-content -- --help`. You can use either the short name (for example, `MD001`) or long name (for example, `heading-increment`) of a linter rule.
72+
73+
Run the specified linter rules on all staged and changed files:
74+
75+
```shell
76+
npm run lint-content -- --rules heading-increment code-fence-line-length
77+
```
78+
79+
Run the specified linter rules on specific files or directories:
80+
81+
```shell
82+
npm run lint-content -- --rules heading-increment code-fence-line-length --path content/FILENAME.md content/DIRECTORY
83+
```
84+
85+
### Display the help menu for the content linter script
86+
87+
```shell
88+
npm run lint-content -- --help
89+
```
90+
91+
## Linting rules
92+
93+
Each rule is configured in a file in [`src/content-linter/style`](https://github.com/github/docs/tree/main/src/content-linter/style), which is where the severities of rules are defined.
94+
95+
### Errors
96+
97+
These rules must be fixed before merging content into the `main` branch.
98+
99+
| **Rule ID** | **Description** |
100+
|---|---|
101+
| [MD004](https://github.com/DavidAnson/markdownlint/blob/main/doc/md004.md) | Unordered list style must be a dash. |
102+
| [MD011](https://github.com/DavidAnson/markdownlint/blob/main/doc/md011.md) | Make sure that link syntax is not reversed. |
103+
| [MD012](https://github.com/DavidAnson/markdownlint/blob/main/doc/md012.md) | No unnecessary blank lines. |
104+
| [MD014](https://github.com/DavidAnson/markdownlint/blob/main/doc/md014.md) | Dollar signs should not be used before commands without showing output. |
105+
| [MD018](https://github.com/DavidAnson/markdownlint/blob/main/doc/md018.md) | Must have one space after a hash style heading. |
106+
| [MD019](https://github.com/DavidAnson/markdownlint/blob/main/doc/md019.md) | Must not have spaces after a hash style heading. |
107+
| [MD022](https://github.com/DavidAnson/markdownlint/blob/main/doc/md022.md) | Headings must be surrounded by a blank line. |
108+
| [MD023](https://github.com/DavidAnson/markdownlint/blob/main/doc/md023.md) | Headings must start at the beginning of the line. |
109+
| [MD027](https://github.com/DavidAnson/markdownlint/blob/main/doc/md027.md) | Catches multiple spaces after blockquote symbol. |
110+
| [MD029](https://github.com/DavidAnson/markdownlint/blob/main/doc/md029.md) | All ordered lists should be prefixed with `1.`. |
111+
| [MD030](https://github.com/DavidAnson/markdownlint/blob/main/doc/md030.md) | Only allow one space after list markers. |
112+
| [MD037](https://github.com/DavidAnson/markdownlint/blob/main/doc/md037.md) | Remove extra spacing inside emphasis markers. |
113+
| [MD039](https://github.com/DavidAnson/markdownlint/blob/main/doc/md039.md) | Remove spacing around image text. |
114+
| [MD042](https://github.com/DavidAnson/markdownlint/blob/main/doc/md042.md) | Do not allow empty links. |
115+
| [MD050](https://github.com/DavidAnson/markdownlint/blob/main/doc/md050.md) | All strong styling should use asterisks. |
116+
| [GHD002](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/image-alt-text-end-punctuation.js) | Images alternate text should end with a punctuation. |
117+
| [GHD005](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/internal-links-lang.js) | Internal links must not have a hardcoded language code. |
118+
| [GHD006](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/image-file-kebab.js) | Image file names should be lowercase kebab case. |
119+
120+
### Warnings
121+
122+
These rules should be fixed before merging content into the `main` branch, but they won't prevent committing changes to your local branch.
123+
124+
| **Rule ID** | **Description** |
125+
|---|---|
126+
| [MD001](https://github.com/DavidAnson/markdownlint/blob/main/doc/md001.md) | Header levels can only increments by one level at a time. |
127+
| [MD002](https://github.com/DavidAnson/markdownlint/blob/main/doc/md002.md) | Ensure that headings start with an H2 heading. |
128+
| [MD009](https://github.com/DavidAnson/markdownlint/blob/main/doc/md009.md) | No unnecessary whitespace from the end of the line. |
129+
| [MD031](https://github.com/DavidAnson/markdownlint/blob/main/doc/md031.md) | Fenced code blocks must be surrounded by blank lines. |
130+
| [MD040](https://github.com/DavidAnson/markdownlint/blob/main/doc/md040.md) | Code fences must have a language specified. |
131+
| [MD047](https://github.com/DavidAnson/markdownlint/blob/main/doc/md047.md) | All files should end with a new line character. |
132+
| [MD049](https://github.com/DavidAnson/markdownlint/blob/main/doc/md049.md) | All emphasis styling should use underscores. |
133+
| [GHD001](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/code-fence-line-length.js) | Code fence content should be 60 lines or less in length. |
134+
| [GHD003](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/image-alt-text-length.js) | Images alternate text should be between 40-150 characters. |
135+
| [GHD004](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/internal-links-slash.js) | Internal links must start with a `/`. |

0 commit comments

Comments
 (0)