Added Vale prose linting with a 'Vortex' house style to the documentation and fixed all reported alerts.

.github/workflows/vortex-test-docs.yml

@@ -103,6 +103,10 @@ jobs:
         run: yarn run spellcheck
         working-directory: '${{ github.workspace }}/.vortex/docs'
 
+      - name: Check prose style
+        run: yarn run lint-prose
+        working-directory: '${{ github.workspace }}/.vortex/docs'
+
       # On the main deploy, publish both majors to match the multi-version
       # docs: '/v1/install' and '/v2/install' are the stable per-major pins and
       # the bare '/install' is a copy of the current major's pin (the

.vortex/.ahoy.yml

@@ -107,6 +107,7 @@ commands:
     cmd: |
       yarn --cwd=docs run lint
       yarn --cwd=docs run spellcheck
+      yarn --cwd=docs run lint-prose
 
   lint-docs-fix:
     cmd: yarn --cwd=docs run lint-fix

.vortex/docs/.gitignore

@@ -20,6 +20,11 @@
 # Test outputs
 .logs
 
+# Vale style packages fetched by `vale sync`.
+/.vale/*
+!/.vale/Vortex
+!/.vale/config
+
 # Misc
 .env.local
 .env.development.local

.vortex/docs/.utils/update-docs.sh

@@ -88,6 +88,10 @@ echo >>"${OUTPUT_FILE}"
 
 printf '%s\n' "${table}" >>"${OUTPUT_FILE}"
 
+# The 'Anchor' component registers each link target with the Docusaurus
+# broken-anchor check.
+sed "${sed_opts[@]}" 's/<a id="\([^"]*\)"><\/a>/<Anchor id="\1" \/>/g' "${OUTPUT_FILE}"
+
 sed "${sed_opts[@]}" "s/.vortex\/docs\/.utils\/variables\/extra\/environment.variables.sh/ENVIRONMENT/g" "${OUTPUT_FILE}"
 sed "${sed_opts[@]}" "s/.vortex\/docs\/.utils\/variables\/extra\/acquia.variables.sh/ACQUIA ENVIRONMENT/g" "${OUTPUT_FILE}"
 sed "${sed_opts[@]}" "s/.vortex\/docs\/.utils\/variables\/extra\/lagoon.variables.sh/LAGOON ENVIRONMENT/g" "${OUTPUT_FILE}"

.vortex/docs/.vale.ini

@@ -0,0 +1,36 @@
+StylesPath = .vale
+MinAlertLevel = warning
+Vocab = Vortex
+
+Packages = https://github.com/vale-cli/Google/releases/download/v0.7.1/Google.zip, https://github.com/vale-cli/write-good/releases/download/v0.4.1/write-good.zip
+
+# Blockquotes hold verbatim quotes from upstream projects.
+SkippedScopes = script, style, pre, figure, blockquote
+
+[*.mdx]
+BasedOnStyles = Vale, Google, Vortex
+
+Vale.Spelling = NO
+
+# Replaced by 'Vortex' rules of the same name.
+Google.Acronyms = NO
+Google.Contractions = NO
+Google.Headings = NO
+Google.Latin = NO
+Google.LyHyphens = NO
+Google.OxfordComma = NO
+Google.WordList = NO
+Google.WordListCase = NO
+
+Google.Colons = NO
+Google.FirstPerson = NO
+Google.Parens = NO
+Google.Quotes = NO
+Google.We = NO
+
+write-good.ThereIs = YES
+
+# The variables table is generated from script comments.
+[content/development/variables.mdx]
+BlockIgnores = (?s)## Variables list.*
+Vortex.BoldName = NO

.vortex/docs/.vale/Vortex/Acronyms.yml

@@ -0,0 +1,16 @@
+extends: Google.Acronyms
+exceptions+:
+  - BATS
+  - BDD
+  - FTP
+  - JIRA
+  - MAY
+  - MUST
+  - NOT
+  - PHAR
+  - PHPCS
+  - SDC
+  - SHA
+  - SHOULD
+  - UTC
+  - UUID

.vortex/docs/.vale/Vortex/BoldName.yml

@@ -0,0 +1,55 @@
+extends: script
+message: "Format 'Vortex' in bold in prose: '**Vortex**'."
+level: error
+scope: raw
+script: |
+  text := import("text")
+
+  matches := []
+
+  // Markup that is not rendered as prose, or that is already bold.
+  patterns := [
+    "(?s)\\A---\\n.*?\\n---\\n",
+    "(?ms)^[ \\t]*(```|~~~).*?^[ \\t]*(```|~~~)[ \\t]*$",
+    "(?m)^[ \\t]*#{1,6} .*$",
+    "(?m)^(import|export) .*$",
+    "(?m)^[ \\t]*:::.*$",
+    "(?m)^[ \\t]*>.*$",
+    "(?m)^[ \\t]*<.*$",
+    "`[^`\\n]*`",
+    "\\*\\*[^*\\n]+\\*\\*",
+    "\\[[^\\]\\n]*\\]\\([^)\\n]*\\)",
+    "https?://[^\\s)]+"
+  ]
+
+  ignored := []
+
+  for pattern in patterns {
+    found := text.re_find(pattern, scope, -1)
+
+    if !is_undefined(found) {
+      for groups in found {
+        ignored = append(ignored, groups[0])
+      }
+    }
+  }
+
+  names := text.re_find("\\bVortex\\b", scope, -1)
+
+  if !is_undefined(names) {
+    for groups in names {
+      name := groups[0]
+      is_ignored := false
+
+      for span in ignored {
+        if name.begin >= span.begin && name.end <= span.end {
+          is_ignored = true
+          break
+        }
+      }
+
+      if !is_ignored {
+        matches = append(matches, {begin: name.begin, end: name.end})
+      }
+    }
+  }

.vortex/docs/.vale/Vortex/CodeFormatting.yml

@@ -0,0 +1,10 @@
+extends: existence
+message: "Format '%s' as inline code."
+level: error
+nonword: true
+exceptions:
+  - Node.js
+tokens:
+  - '(?<![\w/.`-])[A-Z][A-Z0-9]+(?:_[A-Z0-9]+)+(?![\w/`-])'
+  - '(?<![\w/.`-])\.?[\w-]+(?:\.[\w-]+)*\.(?:bats|css|ini|js|json|lock|md|mdx|neon|php|sh|sql|twig|xml|ya?ml)(?![\w/`-])'
+  - '(?<![\w/.`-])\.(?:env|gitignore|dockerignore)(?![\w/`-])'

.vortex/docs/.vale/Vortex/Condescending.yml

@@ -0,0 +1,15 @@
+extends: existence
+message: "'%s' can read as condescending. Remove it or state the fact."
+level: error
+scope: ~heading
+ignorecase: true
+tokens:
+  - clearly
+  - easily
+  - easy
+  - everyone knows
+  - just(?![ -](?:\w+ed|as|before|after|now|in case)\b)
+  - obvious
+  - obviously
+  - of course
+  - simply

.vortex/docs/.vale/Vortex/Contractions.yml

@@ -0,0 +1,32 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://developers.google.com/style/contractions'
+level: error
+# Case-sensitive, so the RFC 2119 keywords 'MUST NOT' and 'SHOULD NOT' stay.
+ignorecase: false
+action:
+  name: replace
+# '\s+' between the words matches a phrase split across a wrapped line.
+swap:
+  '[Aa]re\s+not': aren't
+  '[Cc]annot': can't
+  '[Cc]ould\s+not': couldn't
+  '[Dd]id\s+not': didn't
+  '[Dd]o\s+not': don't
+  '[Dd]oes\s+not': doesn't
+  '[Hh]as\s+not': hasn't
+  '[Hh]ave\s+not': haven't
+  '[Hh]ow\s+is': how's
+  '[Ii]s\s+not': isn't
+  '[Ii]t\s+is': it's
+  '[Ss]hould\s+not': shouldn't
+  '[Tt]hat\s+is': that's
+  '[Tt]hey\s+are': they're
+  '[Ww]as\s+not': wasn't
+  '[Ww]e\s+are': we're
+  '[Ww]e\s+have': we've
+  '[Ww]ere\s+not': weren't
+  '[Ww]hat\s+is': what's
+  '[Ww]hen\s+is': when's
+  '[Ww]here\s+is': where's
+  '[Ww]ill\s+not': won't

.vortex/docs/.vale/Vortex/Dashes.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Use a spaced hyphen (' - ') instead of '%s'."
+level: error
+nonword: true
+tokens:
+  - '—'
+  - '–'

.vortex/docs/.vale/Vortex/Headings.yml

@@ -0,0 +1,37 @@
+extends: Google.Headings
+level: error
+exceptions+:
+  - Acquia Cloud
+  - BATS
+  - BDD
+  - CalVer
+  - Config Split
+  - Config Update
+  - CSS
+  - DOM
+  - Drupal Helpers
+  - FAQs
+  - FeatureContext
+  - Generated Content
+  - Gherkin Lint
+  - GitFlow
+  - JavaScript
+  - Migrate Plus
+  - Migrate Tools
+  - Navigation Extra Tools
+  - PHP
+  - PHP Code Sniffer
+  - PR
+  - PRs
+  - Reroute Email
+  - RobotsTxt
+  - SDC Devel
+  - Security Kit
+  - SemVer
+  - Single Directory Components
+  - SSH
+  - Stage File Proxy
+  - Twig CS Fixer
+  - vs
+  - www.vortextemplate.com
+  - XML Sitemap

.vortex/docs/.vale/Vortex/HedgeStacks.yml

@@ -0,0 +1,6 @@
+extends: existence
+message: "'%s' stacks two hedges. Keep one."
+level: error
+ignorecase: true
+tokens:
+  - (?:can|could|may|might) (?:possibly|potentially)

.vortex/docs/.vale/Vortex/Latin.yml

@@ -0,0 +1,13 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://developers.google.com/style/abbreviations'
+level: error
+ignorecase: true
+nonword: true
+action:
+  name: replace
+# The delimiter is a lookahead, so the replacement keeps the punctuation that
+# follows the abbreviation.
+swap:
+  '\b(?:eg|e\.g\.)(?=[\s,;:)]|$)': for example
+  '\b(?:ie|i\.e\.)(?=[\s,;:)]|$)': meaning|in other words

.vortex/docs/.vale/Vortex/LinkText.yml

@@ -0,0 +1,10 @@
+extends: existence
+message: "Vague link text '%s'. Describe the destination."
+level: error
+ignorecase: true
+scope: link
+tokens:
+  - click here
+  - here
+  - read more
+  - this (?:document|article|page|link)

.vortex/docs/.vale/Vortex/LyHyphens.yml

@@ -0,0 +1,3 @@
+extends: Google.LyHyphens
+exceptions:
+  - supply-chain

.vortex/docs/.vale/Vortex/Marketing.yml

@@ -0,0 +1,11 @@
+extends: existence
+message: "'%s' is a marketing adjective. State the fact instead."
+level: error
+ignorecase: true
+tokens:
+  - best-in-class
+  - blazing(?:ly)?
+  - elegant(?:ly)?
+  - powerful
+  - robust
+  - seamless(?:ly)?

.vortex/docs/.vale/Vortex/Numbers.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Write '%s' as a digit."
+level: error
+ignorecase: true
+nonword: true
+tokens:
+  - '(?<![-\w])(?:two|three|four|five|six|seven|eight|nine|ten)(?![-\w])'

.vortex/docs/.vale/Vortex/OxfordComma.yml

@@ -0,0 +1,23 @@
+extends: existence
+message: "Add the Oxford comma before '%s'."
+link: 'https://developers.google.com/style/commas'
+scope: sentence
+level: warning
+nonword: true
+# Only the conjunction is matched, and the list around it sits in lookarounds.
+# Inline code reaches the rule masked with asterisks, and a match that holds
+# masked text cannot be located in a hard-wrapped paragraph, so it is dropped.
+#
+# The guards after each comma skip text that opens a phrase, not a list item:
+# a participle (', ensuring X and Y.'), a preposition (', without X or Y.'), an
+# example (', for example, X and Y.') or an apposition ('2 profiles, X and Y.').
+#
+# '\s+' between words and the '\A' and '\z' anchors keep the match independent
+# of where a paragraph is hard-wrapped.
+tokens:
+  # A list that ends the sentence: ', B and C.'
+  - '(?<=(?<!(?:\A|[:;]\s|\s-\s)\s*(?i:when|whenever|while|if|unless|until|although|though|because|since|after|before|once|whereas|whether|wherever|where|as|in|on|at|by|for|with|without|during|from|to|under|over|per|via)\b[^,]{0,80})(?<!\b(?:for\s+example|for\s+instance|such\s+as|in\s+other\s+words|namely)\s*)(?<!\b(?:2|two|both)\b[^,]{0,40}),\s+(?!(?:which|who|whom|whose|that|where|when|while|because|since|although|though|if|unless|so|but|and|or|however|therefore|thus|specifically|especially|namely|then|take|see|note|consider|make|use|either|neither|whether|without|with|such|including|like|not|rather|instead|even|regardless|always|never|for|from|by|as|to|in|on|at|after|before|during|until|between|through|under|over|via|per|inside|outside|within|across|into|onto|upon|each|both|plus|built|chosen|given|kept|known|made|run|set|shown|taken|written)\b)(?!(?:\w+ly\s+)?\w+(?:ing|ed)\b)(?!(?i:i|you|we|they|he|she|it)\s+(?!(?:and|or)\b))(?:(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+){0,4}\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+)\b(?:and|or)\b(?=\s+(?:(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+){0,4}\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*(?:[.?!:]|\z))'
+  # A list with 2 or more commas, anywhere in the sentence: ', B, C and D'
+  - '(?<=(?<!\b(?:for\s+example|for\s+instance|such\s+as|in\s+other\s+words|namely)\s*),\s+(?!(?:which|who|whom|whose|that|where|when|while|because|since|although|though|if|unless|so|but|and|or|however|therefore|thus|specifically|especially|namely|then|take|see|note|consider|make|use|either|neither|whether|without|with|such|including|like|not|rather|instead|even|regardless|always|never|for|from|by|as|to|in|on|at|after|before|during|until|between|through|under|over|via|per|inside|outside|within|across|into|onto|upon|each|both|plus)\b)(?:(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+){0,3}(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*,\s+(?!(?:which|who|whom|whose|that|where|when|while|because|since|although|though|if|unless|so|but|and|or|however|therefore|thus|specifically|especially|namely|then|take|see|note|consider|make|use|either|neither|whether|without|with|such|including|like|not|rather|instead|even|regardless|always|never|for|from|by|as|to|in|on|at|after|before|during|until|between|through|under|over|via|per|inside|outside|within|across|into|onto|upon|each|both|plus)\b)(?:(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+){0,3}(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+)\b(?:and|or)\b(?=\s+(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*(?![^.!?]*?,\s+(?:and|or)\b))'
+  # A list that is the subject of the clause: ', B and C are'
+  - '(?<=(?<!(?:\A|[:;]\s|\s-\s)\s*(?i:when|whenever|while|if|unless|until|although|though|because|since|after|before|once|whereas|whether|wherever|where|as|in|on|at|by|for|with|without|during|from|to|under|over|per|via|then|otherwise|however|also|finally|first|next|here|there|instead|similarly|likewise|therefore|thus|hence|still|now|today|note|\w+ly)\b[^,]{0,80})(?<!\b(?:for\s+example|for\s+instance|such\s+as|in\s+other\s+words|namely)\s*)(?<!\b(?:2|two|both)\b[^,]{0,40}),\s+(?!(?:which|who|whom|whose|that|where|when|while|because|since|although|though|if|unless|so|but|and|or|however|therefore|thus|specifically|especially|namely|then|take|see|note|consider|make|use|either|neither|whether|without|with|such|including|like|not|rather|instead|even|regardless|always|never|for|from|by|as|to|in|on|at|after|before|during|until|between|through|under|over|via|per|inside|outside|within|across|into|onto|upon|each|both|plus)\b)(?!(?:\w+ly\s+)?\w+(?:ing|ed)\b)(?!(?i:i|you|we|they|he|she|it)\b)(?:(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+){0,3}(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+)\b(?:and|or)\b(?=\s+(?:(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+){0,3}(?!\b(?:and|or|is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\.?[\w*][\w*''’/-]*(?:\.[\w*]+)*\s+(?:is|are|was|were|has|have|had|will|would|can|could|should|may|might|must|do|does|did)\b(?![^.!?]*?,\s+(?:and|or)\b))'

.vortex/docs/.vale/Vortex/SentenceLength.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Long sentence: %d words. Keep sentences to 30 words or fewer."
+level: warning
+scope: sentence
+max: 30
+token: \b\w+(?:['’]\w+)?\b

.vortex/docs/.vale/Vortex/ThroatClearing.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "'%s' delays the point. Remove it."
+level: error
+ignorecase: true
+tokens:
+  - as mentioned above
+  - it should be noted
+  - keep in mind
+  - please note

.vortex/docs/.vale/Vortex/Weasel.yml

@@ -0,0 +1,8 @@
+extends: write-good.Weasel
+message: "'%s' is vague or adds emphasis without facts. Remove it or be specific."
+tokens-:
+  - largely
+  - mostly
+  - relatively
+  - several
+  - usually

.vortex/docs/.vale/Vortex/WordList.yml

@@ -0,0 +1,5 @@
+extends: Google.WordList
+level: error
+swap-:
+  - CLI
+  - Cloud

.vortex/docs/.vale/Vortex/WordListCase.yml

@@ -0,0 +1,12 @@
+extends: Google.WordListCase
+level: error
+swap-:
+  - "(?:e-mail|Email|E-mail)"
+  - "(?:file ?path|path ?name)"
+  - "(?:kill|terminate|abort)"
+  - admin
+  - application
+  - content type
+  - disabled?
+  - stylesheet
+  - tablet