Skip to content

Commit 62ad6f9

Browse files
kylemclarenkylemclaren
authored
Add Vale documentation linting (#27)
1 parent 331b101 commit 62ad6f9

File tree

16 files changed

+702
-1
lines changed

16 files changed

+702
-1
lines changed

‎.github/workflows/vale-docs-linter.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Check docs with Vale linter
2+
3+
on: [pull_request]
4+
5+
jobs:
6+
vale:
7+
name: Vale linter
8+
runs-on: ubuntu-latest
9+
steps:
10+
- name: check out repo
11+
uses: actions/checkout@v4
12+
with:
13+
fetch-depth: 2
14+
15+
- name: get changed files
16+
id: changed-files
17+
uses: tj-actions/[email protected]
18+
with:
19+
fetch_depth: 2
20+
files: |
21+
src/content/**/*.{md,mdx}
22+
23+
# run reviewdog and the linter
24+
- name: run reviewdog and linter
25+
if: steps.changed-files.outputs.any_changed == 'true'
26+
uses: errata-ai/vale-action@reviewdog
27+
with:
28+
files: ${{ steps.changed-files.outputs.all_changed_and_modified_files }}
29+
separator: ","
30+
# added, diff_context, file, nofilter
31+
filter_mode: file
32+
# github-pr-check, github-pr-review, github-check
33+
reporter: github-pr-check
34+
fail_on_error: false
35+
env:
36+
# Required, set by GitHub actions automatically:
37+
# https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret
38+
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,8 @@ examples/**/env.d.ts
4747
cypress/screenshots
4848
cypress/videos
4949
cypress/downloads
50+
51+
# Vale - external style packages (synced automatically)
52+
styles/Google/
53+
styles/proselint/
54+
styles/write-good/

‎.vale.ini‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
StylesPath = styles
2+
3+
Vocab = fly-terms
4+
5+
MinAlertLevel = suggestion
6+
7+
SkippedScopes = script
8+
9+
Packages = proselint, write-good, Google
10+
11+
[src/content/**/*.{mdx,md}]
12+
BasedOnStyles = Fly, Google, proselint, Vale, write-good
13+
14+
# Fly rules that we can turn back on when other things get cleaned up
15+
Fly.Exclamation = NO
16+
Fly.Headings = NO
17+
Fly.Latin = NO
18+
Fly.Machine = NO # we can do an initial search and replace and then this rule will be less noisy and more useful
19+
Fly.OxfordComma = NO
20+
Fly.SentenceLength = NO # turn on later; then reduce further?
21+
Fly.Us = NO
22+
23+
# other style stuff turned off temporarily
24+
Google.Contractions = NO
25+
Google.DateFormat = NO
26+
Google.EmDash = NO
27+
Google.EnDash = NO
28+
Google.FirstPerson = NO
29+
Google.HeadingPunctuation = NO
30+
Google.LyHyphens = NO
31+
Google.OptionalPlurals = NO
32+
Google.Ordinal = NO
33+
Google.Periods = NO
34+
Google.Ranges = NO
35+
Google.Slang = NO
36+
Google.Spelling = NO
37+
38+
proselint.But = NO
39+
proselint.Cliches = NO
40+
proselint.Typography = NO
41+
proselint.Very = NO
42+
43+
write-good.Illusions = NO # false positives in code blocks
44+
write-good.Passive = NO
45+
write-good.So = NO
46+
write-good.ThereIs = NO
47+
write-good.TooWordy = NO
48+
49+
50+
# Google style guide stuff that we're turning off or replacing permanently
51+
Google.Acronyms = NO # we don't have a rule for acronyms yet and this is noisy
52+
Google.AMPM = NO # don't need
53+
Google.Colons = NO # don't need
54+
Google.Ellipses = NO # don't need
55+
Google.Exclamation = NO # replaced by Fly.Exclamation
56+
Google.Gender = NO # we don't refer to gender in docs
57+
Google.GenderBias = NO # we don't refer to gender in docs
58+
Google.Headings = NO # replaced by Fly.Headings
59+
Google.Latin = NO # replaced by Fly.Latin
60+
Google.OxfordComma = NO # replaced by Fly.OxfordComma
61+
Google.Parens = NO # triggered by links so not useful right now
62+
Google.Passive = NO # duplicate of write-good.Passive
63+
Google.Quotes = NO # too many false positives
64+
Google.Semicolons = NO # don't need this
65+
Google.Spacing = NO # extra spaces aren't rendered anyway
66+
Google.Units = NO # we don't care about unit spacing right now
67+
Google.We = NO # we are OK with "we" sometimes
68+
Google.Will = NO # TBD whether to use this or not
69+
Google.WordList = NO # replaced by Fly.WordList
70+
71+
# Write good styles turned off permanently
72+
write-good.Cliches = NO # duplicate of proselint.Cliches
73+
write-good.E-Prime = NO # too bossy and weird
74+
write-good.Weasel = NO # too arbitrary
75+
76+
# Vale.Avoid = NO
77+
Vale.Repetition = NO # replaced by good-write.Illusions which has an adjustable error level
78+
Vale.Spelling = NO # replaced by Fly.Spelling
79+
Vale.Terms = NO # too strict for technical docs with code examples
80+
81+
[formats]
82+
mdx = md

‎src/content/docs/quickstart.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,6 @@ func main() {
184184
## Next Steps
185185

186186
- **[Working with Sprites](/working-with-sprites)** - Find out about sessions, ports, persistence, and everything beyond the basics
187-
- **[Core concepts: Lifecycle](/concepts/lifecycle)** - Take a deeper dive into Sprites core concepts, beginning with Lifecyle and Persistence
187+
- **[Core concepts: Lifecycle](/concepts/lifecycle)** - Take a deeper dive into Sprites core concepts, beginning with Lifecycle and Persistence
188188
- **[Billing and Cost Optimization](/reference/billing)** - Learn how Sprites are billed, estimate your costs, and try cost optimization strategies
189189

‎styles/Fly/Exclamation.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
extends: existence
2+
message: "Use exclamation points sparingly."
3+
nonword: true
4+
level: suggestion
5+
action:
6+
name: remove
7+
tokens:
8+
- '\w+!(?:\s|$)'

‎styles/Fly/Headings.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
extends: capitalization
2+
message: "'%s' should use sentence-style capitalization."
3+
level: suggestion
4+
scope: heading
5+
match: $sentence
6+
indicators:
7+
- ':'
8+
exceptions:
9+
- CLI
10+
- Docker
11+
- Elixir
12+
- Fly
13+
- Fly Proxy
14+
- gRPC
15+
- I
16+
- Kubernetes
17+
- Linux
18+
- Machine
19+
- Machines
20+
- macOS
21+
- MongoDB
22+
- Nomad
23+
- Rails
24+
- Ruby
25+
- REPL
26+
- TypeScript
27+
- URLs
28+
- Windows

‎styles/Fly/Latin.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
extends: substitution
2+
message: "Use '%s' instead of '%s'."
3+
ignorecase: true
4+
level: suggestion
5+
nonword: true
6+
action:
7+
name: replace
8+
swap:
9+
'\b(?:eg|e\.g\.)(?=[\s,;])': for example
10+
'\b(?:ie|i\.e\.)(?=[\s,;])': that is
11+
'\b(?:viz\.)[\s,]': namely
12+
'\b(?:ergo)[\s,]': therefore

‎styles/Fly/Machine.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
extends: substitution
2+
3+
message: "Use '%s' instead of '%s'."
4+
5+
level: suggestion
6+
7+
swap:
8+
'(?<!local|virtual) machine': Machine
9+
'(?<!local|virtual) machines': Machines
10+
'(?<=local|virtual) Machine': machine
11+
'(?<=local|virtual) Machines': machines

‎styles/Fly/OxfordComma.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
extends: existence
2+
message: "Use the Oxford comma in '%s'."
3+
link: https://docs.microsoft.com/en-us/style-guide/punctuation/commas
4+
scope: sentence
5+
level: suggestion
6+
nonword: true
7+
tokens:
8+
- '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]'

‎styles/Fly/SentenceLength.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
extends: occurrence
2+
message: "Try to keep sentences short (< 40 words)."
3+
scope: sentence
4+
level: suggestion
5+
max: 40
6+
token: \b(\w+)\b

0 commit comments

Comments
 (0)