Skip to content
Snippets Groups Projects
Unverified Commit 2a534486 authored by Issy Long's avatar Issy Long
Browse files

Add Vale linting for our docs

- I noticed that another open source project had taken the Homebrew
  style guide and made it into [Vale linting
  rules](https://github.com/testthedocs/vale-styles/tree/master/Homebrew).
  This copies them into here, so that we can make use of them. Thanks!
- What use is a style guide if our own docs don't at least try to
  adhere to it? This aims to make the rules more visible to all
  contributors.
- In order for these to do anything, you'll have to `brew install vale`
  and run `vale` in the root of this repo. It will look for Markdown
  files.
- A next step would be adding this as a pre-commit hook, or...
- The GitHub Action would have been really good, but [it doesn't support
  forks](https://github.com/errata-ai/vale-action#limitations).
parent 205a0865
No related branches found
No related tags found
No related merge requests found
......@@ -7,6 +7,7 @@ exclude:
- bin
- CNAME
- Gemfile*
- vale-styles
- vendor
plugins:
......
---
extends: substitution
message: Use '%s'
ignorecase: false
link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#style-and-usage'
level: error
nonword: true
swap:
'\beg\b': e.g.
'\bie\b': i.e.
'e\.g\.,': e.g.
'i\.e\.,': i.e.
---
extends: existence
message: 'No Oxford commas!'
link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions'
scope: sentence
level: warning
tokens:
- '(?:[^,]+,){1,}\s\w+,\sand'
---
extends: existence
message: Avoid gender-specific language when not necessary.
link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#personal-pronouns'
level: warning
ignorecase: true
tokens:
- him
- her
- she
- he
- his
- hers
- himself
- herself
Based on Homebrew's [Prose Style Guidelines](http://docs.brew.sh/Prose-Style-Guidelines.html).
---
extends: existence
message: "'%s' should have one space."
link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions'
level: error
nonword: true
tokens:
- '[a-z][.?!][A-Z]'
- '[.?!] {2,}[A-Z]'
---
extends: substitution
message: Use '%s' instead of '%s'.
link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#terminology-words-and-word-styling'
level: error
swap:
Pull Request: pull request
repo: repository
Rubocop: RuboCop
---
extends: capitalization
message: "'%s' should be in sentence case"
level: warning
scope: heading
match: $sentence
---
extends: existence
message: 'No "TM", ™, SM, ©, ®, or other explicit indicators of rights ownership or trademarks'
link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions'
level: error
nonword: true
tokens:
- \bTM\b
-
- \bSM\b
- ©
- ®
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment