Make Vale lint the docs

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

@@ -18,7 +18,8 @@ jobs:
         with:
           fetch_depth: 2
           files: |
-            src/content/**/*.{md,mdx}
+            **/*.{md,mdx}
+            *.{md,mdx}
 
       # run reviewdog and the linter
       - name: run reviewdog and linter

.vale.ini

@@ -1,3 +1,7 @@
+# styles/Fly and the fly-terms vocabulary are Fly's own and live here. The
+# three public packages are fetched by `vale sync`, pinned to the releases
+# below so a new upstream version cannot start enforcing rules we have not
+# looked at. superfly/docs uses the same pins.
 StylesPath = styles
 
 Vocab = fly-terms
@@ -6,9 +10,9 @@ MinAlertLevel = suggestion
 
 SkippedScopes = script
 
-Packages = proselint, write-good, Google
+Packages = https://github.com/vale-cli/Google/releases/download/v0.6.3/Google.zip, https://github.com/vale-cli/proselint/releases/download/v0.3.4/proselint.zip, https://github.com/vale-cli/write-good/releases/download/v0.4.1/write-good.zip
 
-[src/content/**/*.{mdx,md}]
+[*.{md,mdx}]
 BasedOnStyles = Fly, Google, proselint, Vale, write-good
 
 # Fly rules that we can turn back on when other things get cleaned up
@@ -18,6 +22,7 @@ Fly.Latin = NO
 Fly.Machine = NO # we can do an initial search and replace and then this rule will be less noisy and more useful
 Fly.OxfordComma = NO
 Fly.SentenceLength = NO # turn on later; then reduce further?
+Fly.Spelling = NO # off until the vocabulary covers these pages: 41 terms, all legitimate (Herdr, zsh, worktree, systemd)
 Fly.Us = NO
 
 # other style stuff turned off temporarily

styles/Fly/Exclamation.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Use exclamation points sparingly."
+nonword: true
+level: suggestion
+action:
+  name: remove
+tokens:
+  - '\w+!(?:\s|$)'

styles/Fly/Headings.yml

@@ -0,0 +1,28 @@
+extends: capitalization
+message: "'%s' should use sentence-style capitalization."
+level: suggestion
+scope: heading
+match: $sentence
+indicators:
+  - ':'
+exceptions:
+  - CLI
+  - Docker
+  - Elixir
+  - Fly
+  - Fly Proxy
+  - gRPC
+  - I
+  - Kubernetes
+  - Linux
+  - Machine
+  - Machines
+  - macOS
+  - MongoDB
+  - Nomad
+  - Rails
+  - Ruby
+  - REPL
+  - TypeScript
+  - URLs
+  - Windows

styles/Fly/Latin.yml

@@ -0,0 +1,13 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+ignorecase: true
+level: suggestion
+nonword: true
+action:
+  name: replace
+swap:
+  '\b(?:eg|e\.g\.)(?=[\s,;])': for example
+  '\b(?:ie|i\.e\.)(?=[\s,;])': that is
+  '\b(?:viz\.)[\s,]': namely
+  '\b(?:ergo)[\s,]': therefore
+

styles/Fly/Machine.yml

@@ -0,0 +1,12 @@
+  # This file tests some combinations of matches to try to avoid errors on proper usage.
+extends: substitution
+
+message: "Use '%s' instead of '%s'."
+
+level: suggestion
+
+swap:
+  '(?<!local|virtual) machine': Machine
+  '(?<!local|virtual) machines': Machines
+  '(?<=local|virtual) Machine': machine
+  '(?<=local|virtual) Machines': machines

styles/Fly/OxfordComma.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Use the Oxford comma in '%s'."
+link: https://docs.microsoft.com/en-us/style-guide/punctuation/commas
+scope: sentence
+level: suggestion
+nonword: true
+tokens:
+  - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]'

styles/Fly/SentenceLength.yml

@@ -0,0 +1,7 @@
+# another experiment. sentences should probably be no more than about 30-35 words, but this rule counts underscored options as multiple words.
+extends: occurrence
+message: "Try to keep sentences short (< 40 words)."
+scope: sentence
+level: suggestion
+max: 40
+token: \b(\w+)\b

styles/Fly/Spelling.yml

@@ -0,0 +1,23 @@
+extends: spelling
+message: "Is '%s' a typo?"
+level: suggestion
+
+# This disables the built-in filters. If you omit this
+# key or set it to false, custom filters (see below) are
+# added on top of the built-in ones.
+#
+# By default, filters for acronyms, abbreviations, and
+# numbers are included.
+custom: false
+
+# A "filter" is a regular expression specifying words
+# to ignore during spell checking.
+# custom Fly.io filters:
+filters:
+
+  - '\w+_\w+' # ignore config option names
+  - '--.' # ignore command options
+  - 'v[0.9].' # ignore flyctl versions
+
+ignore:
+  - words2ignore.txt

styles/Fly/Us.yml

@@ -0,0 +1,11 @@
+extends: existence
+message: "Try to avoid using first-person plural like '%s'."
+link: 'https://developers.google.com/style/pronouns#personal-pronouns'
+level: suggestion
+ignorecase: true
+tokens:
+#  - we
+#  - we'(?:ve|re)
+#  - ours?
+  - us
+  - let's

styles/Fly/WordList.yml

@@ -0,0 +1,43 @@
+extends: substitution
+message: "Consider using '%s' instead of '%s'."
+level: suggestion
+ignorecase: false
+action:
+  name: replace
+swap:
+  "(?:e-mail|E-mail)": email
+  "(?:file ?path|path ?name)": path
+  "(?:ok|Okay)": OK|okay
+  "(?:WiFi|wifi)": Wi-Fi
+  "un(?:check|select)": clear
+  # above: preceding
+  Ajax: AJAX
+  a\.k\.a|aka: or|also known as
+  # application: app
+  approx\.: approximately
+  # below: later|in the following steps
+  check box: checkbox
+  click on: click|click in
+  data are: data is
+  datatype: data type
+  datastore: data store
+  # filesystem: file system
+  firewalls: firewall rules
+  free tier: free allowances
+  functionality: capability|feature
+  healthcheck: health check
+  healthchecks: health checks
+  HTTPs: HTTPS
+  in order to: to
+  # instance: Machine
+  k8s: Kubernetes
+  leverage: use
+  Nodejs: Node.js
+  open-source: open source
+  SHA1: SHA-1|HAS-SHA1
+  sign into: sign in to
+  synch: sync
+  # url: URL
+  utilize: use
+  vs\.: versus
+  World Wide Web: web