brew/docs/vale-styles/Homebrew/Titles.yml

extends: capitalization
message: "'%s' should be in title case"
level: error
scope: heading.h1
match: $title
style: AP
exceptions:
  - brew(1)
  - macOS
  - Homebrew/brew
  - Homebrew/homebrew-core
  - Homebrew/homebrew-cask
  - (or Linux)
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). 2019-12-09 18:42:14 +00:00			`extends: capitalization`
Use Title Case in h1 headings and sentence case in all others - I wrote about the implications of (not) doing this in the PR (https://github.com/Homebrew/brew/pull/6826#issuecomment-564273209), but in summary: - It looks like pretty much the only place we've ever adhered to the sentence case rule is the Prose Guidelines itself. - Correcting all these to sentence case would be a lot of work (and sometimes not even make sense). - Admittedly, some of the title case ones look a bit horrible, but even with some allowed exceptions, but it's better than being consistently inconsistent. - Only lint for title case in h1 headings. H2s and H3s etc. can be sentence case. There's not currently a lint for that. 2019-12-10 22:29:55 +00:00			`message: "'%s' should be in title case"`
vale-styles: Upgrade all checks to "error" level - I added these all the way back in December 2019 in #6826, but only today realised that things have been failing unnoticeably because "warning" level exits with status code 0, so doesn't fail CI. - Upgrading to "error" level will enable us to see the style errors in our docs and fix them faster. - My editor also auto-formatted the YAML to have double quotes instead of single. 2020-10-17 21:47:58 +01:00			`level: error`
Use Title Case in h1 headings and sentence case in all others - I wrote about the implications of (not) doing this in the PR (https://github.com/Homebrew/brew/pull/6826#issuecomment-564273209), but in summary: - It looks like pretty much the only place we've ever adhered to the sentence case rule is the Prose Guidelines itself. - Correcting all these to sentence case would be a lot of work (and sometimes not even make sense). - Admittedly, some of the title case ones look a bit horrible, but even with some allowed exceptions, but it's better than being consistently inconsistent. - Only lint for title case in h1 headings. H2s and H3s etc. can be sentence case. There's not currently a lint for that. 2019-12-10 22:29:55 +00:00			`scope: heading.h1`
			`match: $title`
			`style: AP`
			`exceptions:`
			`- brew(1)`
vale-styles: Add "macOS" to the titlecase exceptions list - Otherwise this surfaces an error and suggests a fix that doesn't match Apple's branding. 2020-10-17 21:45:15 +01:00			`- macOS`
docs: update vale config with new titles 2021-05-14 14:04:09 -04:00			`- Homebrew/brew`
Use Title Case in h1 headings and sentence case in all others - I wrote about the implications of (not) doing this in the PR (https://github.com/Homebrew/brew/pull/6826#issuecomment-564273209), but in summary: - It looks like pretty much the only place we've ever adhered to the sentence case rule is the Prose Guidelines itself. - Correcting all these to sentence case would be a lot of work (and sometimes not even make sense). - Admittedly, some of the title case ones look a bit horrible, but even with some allowed exceptions, but it's better than being consistently inconsistent. - Only lint for title case in h1 headings. H2s and H3s etc. can be sentence case. There's not currently a lint for that. 2019-12-10 22:29:55 +00:00			`- Homebrew/homebrew-core`
docs: update vale config with new titles 2021-05-14 14:04:09 -04:00			`- Homebrew/homebrew-cask`
docs/vale-styles/Homebrew/Titles: fix Linux reference. 2020-11-16 13:59:45 +00:00			`- (or Linux)`