Skip to content

Introduce Vale as a linter #986

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
BoHristova wants to merge 9 commits into
base: master
Choose a base branch
from
Open

Introduce Vale as a linter #986

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ab213c1
Initial setup
BoHristova May 15, 2026
43938cd
Change check to fail on error
BoHristova May 15, 2026
bd743c7
Add GH review
BoHristova May 15, 2026
076fde6
Adjust TokenIgnores to not ignore link texts
BoHristova May 15, 2026
dfde900
Add make targets
BoHristova May 19, 2026
2ff7fa0
Fix Vale workflow to lint only changed files
BoHristova May 21, 2026
f96f5db
Fix changed files format for vale-action
BoHristova May 21, 2026
4b113bd
Order terms alphabetically, clean up vocabs
BoHristova May 26, 2026
d6db282
Add comments to dictionaries
BoHristova May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions .github/workflows/vale.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
name: Vale

on:
pull_request:
types: [opened, synchronize, reopened]
paths:
- 'website/**/*.md'
- '.vale.ini'
- '.vale/**'
workflow_dispatch:

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read
checks: write
pull-requests: write

jobs:
vale:
name: Lint prose
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Get changed files
id: changed-files
uses: tj-actions/changed-files@v45
Comment on lines +26 to +31
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

tj-actions/changed-files security incident 2024

💡 Result:

In March 2025, the popular GitHub Action tj-actions/changed-files was the subject of a significant supply chain security incident, tracked as CVE-2025-30066 [1][2][3]. The incident involved an attacker gaining unauthorized access to the tj-actions/changed-files repository and retroactively modifying multiple version tags to point to a malicious commit (0e58ed8671d6b60d0890c21b07f8835ace038e67) [1][3][4]. This malicious code executed a Python script that scanned the memory of the GitHub Runner process to extract CI/CD secrets [1][2][5]. These secrets were then printed to the workflow logs [1][6][7]. If the repository had public workflow logs, these secrets became publicly accessible [1][3][6]. The vulnerability was active between March 14 and March 15, 2025 [1][6]. During this time, it impacted over 23,000 repositories [1][6][5]. The incident was mitigated after GitHub took down the repository briefly to remove the malicious commits and restore legitimate tags [2][7]. It is important to distinguish this 2025 incident from a separate, earlier vulnerability in the same action, CVE-2023-51664, which was disclosed in December 2023 and addressed command injection risks [8][9][7]. Organizations that utilized tj-actions/changed-files during the March 2025 compromise window were advised to rotate any secrets that were accessible to the affected CI/CD environments [2][3][5].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

FILE=".github/workflows/vale.yml"

echo "== File: $FILE =="
nl -ba "$FILE" | sed -n '1,200p'

Repository: gardener/documentation

Length of output: 166

🏁 Script executed:

#!/bin/bash
set -euo pipefail

FILE=".github/workflows/vale.yml"

echo "== File: $FILE =="
cat -n "$FILE" | sed -n '1,200p'

echo
echo "== Grep for relevant inputs/actions =="
rg -n "vale|separator|uses: |persist-credentials|tj-actions/changed-files|actions/checkout" "$FILE" || true

Repository: gardener/documentation

Length of output: 1911

🌐 Web query:

tj-actions/changed-files separator input valid values documentation

💡 Result:

For the tj-actions/changed-files GitHub Action, the separator input does not have a constrained list of valid values [1][2]. Instead, it accepts any string character or sequence of characters that you wish to use as a delimiter for the action's output strings [1][2]. Key details regarding the separator input and related configurations include: - Purpose: The separator input defines the split character used for output strings generated by the action [1][2]. - Default Value: The default value for separator is a single space (" ") [1][2]. - Other Separator Inputs: The action also provides specific separator inputs for other configurations, which default to a newline character ("\n") [1][2]: - files_separator: Used to split the files input [1][2]. - files_from_source_file_separator: Used to split the files_from_source_file input [1][2]. - files_yaml_from_source_file_separator: Used to split the files_yaml_from_source_file input [1][2]. - old_new_separator: Used to split old and new filename pairs, defaulting to a comma (",") [1][2]. - old_new_files_separator: Used to split old and new renamed filename pairs, defaulting to a space (" ") [1][2]. As there is no restricted enum or list of valid values, you can provide any valid string consistent with your workflow's requirements [1][2].

Citations:

🌐 Web query:

vale-cli/vale-action separator input documentation

💡 Result:

In the vale-cli/vale-action GitHub Action, the separator input is an optional parameter used to define the delimiter character for the files input when it is provided as a character-delimited list [1][2][3]. When you provide the files input as a string of files (e.g., 'input1,input2'), the action uses the separator input to determine how to split that string into individual file or directory arguments for the Vale CLI [1][3]. Example usage from the official documentation: yaml - uses: vale-cli/vale-action@v2.1.1 with: files: 'input1,input2' separator: "," In this configuration, the action effectively runs vale input1 input2 [1][3]. If the separator input is not explicitly defined, the default behavior for the files input varies based on the format supplied (e.g., it defaults to 'all' if no value is provided, or you can provide a JSON-formatted list as an alternative to the delimited string approach) [1][3].

Citations:

🌐 Web query:

actions/checkout v4.2.2 commit SHA 11bd71901bbe5b1630ceea73d27597364c9af683

💡 Result:

The commit SHA 11bd71901bbe5b1630ceea73d27597364c9af683 corresponds to the official release of actions/checkout version 4.2.2 [1][2]. This release was prepared on October 23, 2024 [1], and included updates to url-helper.ts to leverage well-known environment variables, as well as expanded unit test coverage for isGhes [1][2]. Users frequently pin this action to specific commit SHAs like this one as a security best practice to ensure the integrity of the code being executed in CI/CD pipelines [3][4][5].

Citations:

🌐 Web query:

tj-actions/changed-files v45.0.4 commit SHA 4edd678ac3f81e2dc578756871e4d00c19191daf

💡 Result:

The commit SHA 4edd678ac3f81e2dc578756871e4d00c19191daf is a specific, valid commit referenced in various GitHub Actions workflows, including those using the tj-actions/changed-files action [1][2]. It is not, however, a release tag for the tj-actions/changed-files repository itself, which uses versioning formats such as v45.0.4 [3]. This specific commit hash appears in technical documentation and configuration files for multiple projects (e.g., Kong/sdk-portal-js, and various CI/CD templates) [1][2]. Contextual Note: The tj-actions/changed-files repository experienced a notable supply chain incident in March 2025 [4][5]. During this event, malicious commits were injected into the repository, and tags were manipulated to point to rogue commits, potentially affecting users who pinned actions to tags or branches [4]. Security researchers and community advisories emphasize that when using third-party GitHub Actions, pinning to a specific, verified commit SHA is a recommended security practice to mitigate the risk of tag-poisoning or "imposter commit" attacks [6][4][7]. Users encountering this specific hash (4edd678ac3f81e2dc578756871e4d00c19191daf) in their workflows should verify it against the source repository's official commit history to ensure its integrity before continued use.

Citations:

🌐 Web query:

tj-actions/changed-files v45.0.4 commit hash

💡 Result:

tj-actions/changed-files v45.0.4 resolves to commit 6809677b7a5911221b35d87417198c8a289e34ec [1].

Citations:

🌐 Web query:

vale-cli/vale-action v2.1.1 commit SHA

💡 Result:

The release v2.1.1 of vale-cli/vale-action (formerly errata-ai/vale-action) was published on October 15, 2024 [1][2]. The specific commit SHA associated with the v2.1.1 tag in the vale-cli/vale-action repository is 0a56e0d. Note: While public GitHub repository interfaces frequently provide the latest release and recent commit logs [1][3], specific tag SHAs can be verified directly via the Git repository metadata (e.g., using git show v2.1.1). Users are encouraged to pin GitHub Actions to specific commit SHAs (e.g., uses: vale-cli/vale-action@0a56e0d) to ensure consistency and security, especially given recent concerns regarding tag-based reference vulnerabilities in supply chains [4].

Citations:

🌐 Web query:

actions/checkout v4.2.2 commit SHA 11bd71901bbe5b1630ceea73d27597364c9af683

💡 Result:

The commit SHA 11bd71901bbe5b1630ceea73d27597364c9af683 corresponds to the release of actions/checkout version 4.2.2 [1][2]. This specific commit was authored by John Wesley Walker III on October 23, 2024, and was used to prepare the v4.2.2 release [1][2]. The changes included in this version were: * Improvements to url-helper.ts, allowing it to better leverage well-known environment variables [1][2]. * Expanded unit test coverage for the isGhes (GitHub Enterprise Server) function [1][2]. Because this SHA refers to the actual source code and bundled JavaScript for the action, it is frequently used by developers to pin workflows to a specific, immutable version of the action to ensure consistency and security [3]. Users occasionally reference this SHA directly in their workflow files, for example: uses: actions/checkout@11bd719 [4][3].

Citations:

🌐 Web query:

actions/checkout v4 commit SHA currently points to

💡 Result:

actions/checkout@v4 currently resolves to commit SHA fd084cde189b7b76ec305d52e27be545a0172823 in the actions/checkout repo [1]. Note: “v4” is a moving ref (tag/branch) and can be repointed; pinning to the full 40-character commit SHA is recommended if you need immutability.

Citations:

🌐 Web query:

tj-actions/changed-files v45 commit SHA currently points to

💡 Result:

The tag tj-actions/changed-files@v45 currently points to commit SHA 0e58ed8671d6b60d0890c21b07f8835ace038e67. [1][2] Reasoning (brief): Multiple security writeups of the incident state that the compromised commit hash is 0e58ed8671d6b60d0890c21b07f8835ace038e67, and that (at least at the time of investigation) affected tag pointers—including v45—point to that same malicious commit. [1][2] Note: The official project also has releases/tags and later security guidance indicates tags were updated after the compromise; however, the sources above explicitly identify the compromised commit SHA as the one the v45 tag pointed to during the incident window. [1][2][3]

Citations:

🌐 Web query:

vale-cli/vale-action v2.1.1 commit SHA currently points to

💡 Result:

As of May 26, 2026, the vale-cli/vale-action version v2.1.1 refers to a release in the GitHub repository. While the repository provides the tag v2.1.1, the specific commit SHA associated with this tag can be verified directly on the repository's GitHub release page [1]. To confirm the exact, immutable commit SHA currently associated with the v2.1.1 tag, you should navigate to the vale-cli/vale-action releases page and click on the "v2.1.1" tag or release. This will display the associated commit hash, which is the most authoritative way to identify the code linked to that version. It is important to note that GitHub Actions are susceptible to tag-based redirection [2]. Security best practices, particularly following recent industry incidents involving malicious tag rewrites [3][2], recommend pinning actions to an immutable commit SHA in your workflow configuration (e.g., uses: vale-cli/vale-action@<COMMIT_SHA>) rather than relying on a mutable version tag [2].

Citations:

🌐 Web query:

GHSA-mw4p-6x4p-x5m5 tj-actions changed-files fixed commit sha

💡 Result:

The security advisory GHSA-mw4p-6x4p-x5m5 pertains to a supply chain compromise of the tj-actions/changed-files GitHub Action, which occurred between March 14 and March 15, 2025 [1]. During this incident, attackers retroactively modified multiple existing version tags to point to a malicious commit with the SHA 0e58ed8671d6b60d0890c21b07f8835ace038e67 [1][2]. This malicious commit executed a Python script that extracted CI/CD secrets from the Runner Worker process memory and printed them to the GitHub Actions logs, exposing them publicly [1][2]. The vulnerability affected versions up to 45.0.7 [1]. The incident was mitigated by updating the affected tags to point to legitimate, secure commits [1]. Users are strongly advised to pin GitHub Actions to full-length, immutable commit SHAs rather than relying on mutable version tags to prevent similar supply chain attacks where tags are redirected to malicious code [2][3].

Citations:

🌐 Web query:

actions/checkout persist-credentials default value

💡 Result:

The default value for the persist-credentials input in the actions/checkout GitHub Action is true [1][2][3]. When set to true (the default), the action automatically configures the local Git repository's configuration with the authentication token or SSH key used for the checkout [1][2]. This allows subsequent steps in the same job to execute authenticated Git commands [1][3]. The token is removed during the post-job cleanup process [1][2]. If you wish to prevent this behavior—for example, to avoid the credentials being exposed to other processes or inadvertently included if the workspace is archived—you can explicitly set this input to false [1][4][5]: - uses: actions/checkout@v4 with: persist-credentials: false

Citations:

Pin GitHub Actions to commit SHAs (and disable checkout credential persistence)

  • tj-actions/changed-files@v45 is a mutable tag; it was involved in the documented compromise (malicious commit 0e58ed8671d6b60d0890c21b07f8835ace038e67), so pin it (and ideally actions/checkout@v4 and vale-cli/vale-action@v2.1.1) to immutable commit SHAs instead of version tags.
  • Add with: persist-credentials: false to the actions/checkout step (default is true).
  • separator: "," is valid for both tj-actions/changed-files and vale-cli/vale-action; no change needed there.
🧰 Tools
🪛 zizmor (1.25.2)

[warning] 26-27: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

[error] 27-27: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

[error] 31-31: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/vale.yml around lines 26 - 31, Pin mutable GitHub Action
tags to immutable commit SHAs and disable credential persistence on checkout:
replace uses: actions/checkout@v4 with the actions/checkout commit SHA and add
with: persist-credentials: false in the "Checkout" step; replace uses:
tj-actions/changed-files@v45 with that action's specific commit SHA; likewise
pin vale-cli/vale-action@v2.1.1 to its immutable commit SHA; keep existing
separator: "," settings unchanged.

with:
files: |
website/**/*.md
files_ignore: |
website/about/legal-disclosure.md
website/archived/**
separator: ","

- name: Vale
if: steps.changed-files.outputs.any_changed == 'true'
uses: vale-cli/vale-action@v2.1.1
with:
files: '${{ steps.changed-files.outputs.all_changed_files }}'
vale_flags: "--minAlertLevel=warning"
reporter: github-pr-review
fail_on_error: true
filter_mode: file
separator: ","
19 changes: 19 additions & 0 deletions .vale.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
StylesPath = .vale/styles
MinAlertLevel = warning

Vocab = GardenerTerms, ThirdPartyProducts, TechJargon, General
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Check if Places vocabulary file exists and is referenced in Spelling.yml

# Check if Places vocabulary directory and file exist
fd -t d "Places" .vale/styles/config/vocabularies/

# Verify reference in Spelling.yml
rg -n "Places/accept.txt" .vale/styles/Gardener/Spelling.yml

Repository: gardener/documentation

Length of output: 90

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Show .vale.ini around the Vocab line
echo "=== .vale.ini ==="
nl -ba .vale.ini | sed -n '1,120p'

# Locate Vale vocab directories/files
echo
echo "=== .vale vocabularies dir listing (first 200 entries) ==="
ls -la .vale/styles/config/vocabularies/ | head -n 200

echo
echo "=== fd matches for 'Places' (case-sensitive) ==="
fd -t d "Places" .vale/styles/config/vocabularies/ || true

echo
echo "=== fd matches for 'Places' (case-insensitive) ==="
fd -it "places" -t d .vale/styles/config/vocabularies/ || true

echo
echo "=== Spelling.yml reference ==="
rg -n "Places/accept\.txt" .vale/styles/Gardener/Spelling.yml

Repository: gardener/documentation

Length of output: 145

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== .vale.ini (full) ==="
sed -n '1,200p' .vale.ini || true
echo
echo "=== .vale.ini Vocab line(s) ==="
rg -n '^\s*Vocab\s*=' .vale.ini || true

echo
echo "=== vocabularies dir exists? ==="
ls -la .vale/styles/config/vocabularies/ || true

echo
echo "=== fd matches for 'Places' (exact) ==="
fd -t d "Places" .vale/styles/config/vocabularies/ || true

echo
echo "=== fd matches for 'places' (case-insensitive) ==="
fd -it "places" -t d .vale/styles/config/vocabularies/ || true

echo
echo "=== list vocab directories (names only) ==="
ls -1 .vale/styles/config/vocabularies/ | head -n 200 || true

echo
echo "=== Spelling.yml reference ==="
rg -n "Places/accept\.txt" .vale/styles/Gardener/Spelling.yml || true

Repository: gardener/documentation

Length of output: 1519

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== Find occurrences of Places/accept.txt ==="
rg -n "Places/accept\.txt" .vale || true

echo
echo "=== Find accept.txt files under .vale ==="
fd -t f "accept\.txt" .vale || true

echo
echo "=== Find any vocab directories/files mentioning Places under .vale ==="
rg -n "Places" .vale/styles/config/vocabularies .vale/styles/Gardener .vale/styles -S || true

echo
echo "=== List .vale/styles directory (top-level) ==="
ls -la .vale/styles || true

echo
echo "=== List .vale/styles/Gardener (top-level) ==="
ls -la .vale/styles/Gardener || true

echo
echo "=== Show Spelling.yml ==="
sed -n '1,160p' .vale/styles/Gardener/Spelling.yml || true

Repository: gardener/documentation

Length of output: 2507

🌐 Web query:

Vale configuration Vocaboptionspellingruleignoreentries likePlaces/accept.txt behavior when file/directory is missing

💡 Result:

Vale “Vocabularies” don’t provide any documented behavior for an accept.txt/reject.txt entry path like Places/accept.txt when that file/directory is missing; the official docs only describe that a Vocab is a folder containing accept.txt and reject.txt with one regex per line, and that comments (#) are ignored. There is no mention in the docs of a “missing file => ignore/skip silently” fallback, so you should assume Vale expects the files to exist (and you may see a config/load error if they don’t). [1][2] For the analogous spelling rule ignore: mechanism: it is defined as a relative path (from StylesPath) to a file “consisting of one word per line to ignore”; the docs likewise do not describe special handling for missing ignore files. [3] What to do if you’re trying to make the rule tolerant of missing vocab/ignore files: - Prefer ensuring the referenced Vocab folder (and its accept.txt/reject.txt) exists in all environments. - If you need optional behavior, gate it in your CI/build tooling (e.g., only run Vale with that config when the vocab files exist), because Vale’s docs don’t document a built-in “ignore missing file” switch for either Vocab or spelling ignore:. [1][3] If you want, paste your exact .vale.ini (or the relevant YAML rule) and the Vale version; I can look for code/test evidence of the exact failure mode (error vs silent skip) for missing vocab files in that release line.

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== Check if ignore paths exist under .vale/styles/<Name>/accept.txt ==="
for name in GardenerTerms General TechJargon ThirdPartyProducts Places; do
  p=".vale/styles/$name/accept.txt"
  if [ -f "$p" ]; then
    echo "FOUND: $p"
  else
    echo "MISSING: $p"
  fi
done

echo
echo "=== Check if accept.txt exists under .vale/styles/config/vocabularies/<Name>/accept.txt ==="
for name in GardenerTerms General TechJargon ThirdPartyProducts Places; do
  p=".vale/styles/config/vocabularies/$name/accept.txt"
  if [ -f "$p" ]; then
    echo "FOUND: $p"
  else
    echo "MISSING: $p"
  fi
done

echo
echo "=== Verify .vale.ini StylesPath and Vocab ==="
sed -n '1,10p' .vale.ini

Repository: gardener/documentation

Length of output: 1005

Add missing Places vocabulary to Vale config (or remove its reference)

.vale/styles/Gardener/Spelling.yml references Places/accept.txt in ignore (line 9), but .vale.ini’s Vocab list omits Places and there is no .vale/styles/config/vocabularies/Places/accept.txt directory/file. Add the Places vocab (with accept.txt) and include Places in Vocab, or remove the ignore entry if it’s not needed.

🔧 Proposed fix 
-Vocab = GardenerTerms, ThirdPartyProducts, TechJargon, General
+Vocab = GardenerTerms, ThirdPartyProducts, TechJargon, General, Places
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Vocab = GardenerTerms, ThirdPartyProducts, TechJargon, General
Vocab = GardenerTerms, ThirdPartyProducts, TechJargon, General, Places
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.vale.ini at line 4, The Vale config references a missing vocabulary:
.vale/styles/Gardener/Spelling.yml uses "Places/accept.txt" in its ignore list
but .vale.ini's Vocab omits "Places" and the Places vocabulary directory/file
doesn't exist; either add a new vocabulary directory
.vale/styles/config/vocabularies/Places with an accept.txt file and add "Places"
to the Vocab line in .vale.ini, or remove the "Places/accept.txt" entry from
.vale/styles/Gardener/Spelling.yml if that ignore is not needed. Ensure the
Vocab list includes the exact token "Places" and that the accept.txt path
matches the referenced "Places/accept.txt".


IgnoredScopes = code, tt, code block

[*.md]
BasedOnStyles = Gardener

TokenIgnores = (`[^`]+`), (<[^>]+>), (v[0-9]+(?:\.[0-9]+)*(?:alpha[0-9]+|beta[0-9]+)?), (/[^\s]+), (https?://\S+), ([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]+), (\w+\(s\)), (\*+\w+\**|\w+\*+)

BlockIgnores = (?s)(\{\{.*?\}\})

[website/about/legal-disclosure.md]
BasedOnStyles =

[website/archived/**]
BasedOnStyles =
40 changes: 40 additions & 0 deletions .vale/styles/Gardener/Articles.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
extends: substitution
message: "Use '%s' instead of '%s'. The article depends on pronunciation, not spelling."
link: https://github.com/gardener/documentation/blob/master/website/documentation/contribute/documentation/style-guide/_index.md
level: warning
ignorecase: false
action:
name: replace
swap:
# Acronyms starting with vowel-sound letters that need "an"
# A (ay), E (ee), F (ef), H (aitch), I (eye), L (el), M (em), N (en), O (oh), R (ar), S (es), X (ex)
'a OS': an OS
'a HA': an HA
'a HTTP': an HTTP
'a HTML': an HTML
'a SSH': an SSH
'a SSL': an SSL
'a API': an API
'a OIDC': an OIDC
'a OCI': an OCI
'a SSD': an SSD
'a SDK': an SDK
'a XML': an XML
'a IDE': an IDE
'a IAM': an IAM
'a HPA': an HPA
'a FAQ': an FAQ
'a ETCD': an ETCD
'a NFS': an NFS
'a RBAC': an RBAC
# Acronyms starting with consonant-sound letters that need "a"
# U (yoo), V (vee), W (double-yoo), C (see) when starts acronym
'an VM': a VM
'an VPA': a VPA
'an VPC': a VPC
'an VPN': a VPN
'an URL': a URL
'an URI': a URI
'an GPU': a GPU
'an CPU': a CPU
'an SIG': a SIG
8 changes: 8 additions & 0 deletions .vale/styles/Gardener/CommandPrompt.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
extends: existence
message: "Don't include the command prompt '%s' in code blocks. Show only the command itself."
level: error
link: https://github.com/gardener/documentation/blob/master/website/documentation/contribute/documentation/formatting-guide.md
scope: raw
tokens:
- '```[a-z]*\n\$\s'
- '`\$\s\w'
13 changes: 13 additions & 0 deletions .vale/styles/Gardener/Links.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
extends: existence
message: "Avoid generic link text '%s'. Use a descriptor of the link's destination instead."
level: warning
link: https://github.com/gardener/documentation/blob/master/website/documentation/contribute/documentation/style-guide/_index.md
scope: raw
nonword: true
tokens:
- '\[here\]\('
- '\[click here\]\('
- '\[this link\]\('
- '\[this page\]\('
- '\[read more\]\('
- '\[learn more\]\('
15 changes: 15 additions & 0 deletions .vale/styles/Gardener/SecondPerson.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
extends: substitution
message: "Use '%s' instead of '%s'. Address the reader directly as 'you'."
level: warning
link: https://github.com/gardener/documentation/blob/master/website/documentation/contribute/documentation/style-guide/_index.md
action:
name: replace
ignorecase: true
swap:
'the user can': 'you can'
'the user must': 'you must'
'the user should': 'you should'
'the user needs to': 'you need to'
'the user has to': 'you have to'
'the user is': 'you are'
'the user wants': 'you want'
28 changes: 28 additions & 0 deletions .vale/styles/Gardener/Spelling.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
extends: spelling
message: "Did you really mean '%s'?"
level: error
append: true
ignore:
- GardenerTerms/accept.txt
- ThirdPartyProducts/accept.txt
- TechJargon/accept.txt
- Places/accept.txt
- General/accept.txt
filters:
# Uppercase acronyms (e.g. HTTP, YAML, REST)
- '[A-Z]{2,}'
# Uppercase acronym plurals (e.g. CAs, VMs, CRDs, APIs)
- '[A-Z]{2,}s\b'
# camelCase and PascalCase identifiers (e.g. kubeConfig, GardenNamespace)
- '[a-z]+[A-Z][a-zA-Z]+'
- '[A-Z][a-z]+[A-Z][a-zA-Z]+'
# Tokens with digits (e.g. IPv4, log4j, int64, v1alpha1)
- '[a-zA-Z]*[0-9]+[a-zA-Z0-9]*'
# CLI flags (e.g. --flag, -f)
- '--?[a-zA-Z][a-zA-Z0-9-]+'
# File extensions and dot-separated identifiers (e.g. .yaml, cert.gardener.cloud)
- '\.[a-zA-Z]{1,6}\b'
# Underscore-separated identifiers (e.g. config_key, _source)
- '_?[a-zA-Z]+_[a-zA-Z0-9_]+'
# Version strings (e.g. v1, v1.2, v1alpha1, v2beta1)
- '[vV][0-9]+(?:\.[0-9]+)*(?:alpha[0-9]+|beta[0-9]+)?'
17 changes: 17 additions & 0 deletions .vale/styles/Gardener/Terms.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
action:
name: replace
ignorecase: false
swap:
'(?<![a-zA-Z0-9_./@])[Gg]it[Hh]ub(?![a-zA-Z0-9_.com-])': GitHub
'(?<![a-zA-Z0-9_./@])[Gg]it[Ll]ab(?![a-zA-Z0-9_.-])': GitLab
'(?<![a-zA-Z0-9_./@])kubernetes(?![a-zA-Z0-9_.-])': Kubernetes
'(?<![a-zA-Z0-9_./@])gardener(?![a-zA-Z0-9_@.-])': Gardener
'(?<![a-zA-Z0-9_./@])gardenlet(?![a-zA-Z0-9_.-])': gardenlet
'(?<![a-zA-Z0-9_./@])openstack(?![a-zA-Z0-9_.-])': OpenStack
'(?<![a-zA-Z0-9_./@])vsphere(?![a-zA-Z0-9_.-])': vSphere
'(?<![a-zA-Z0-9_./@])stackit(?![a-zA-Z0-9_.-])': STACKIT
'(?<![a-zA-Z0-9_./@])controlplane(?![a-zA-Z0-9_.-])': control plane
'(?<![a-zA-Z0-9_./@])controlplanes(?![a-zA-Z0-9_.-])': control planes
10 changes: 10 additions & 0 deletions .vale/styles/Gardener/WordChoice.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
extends: substitution
message: "Use '%s' instead of '%s'. Prefer inclusive and modern terminology."
level: warning
action:
name: replace
ignorecase: false
swap:
# Not covered by Elastic's WordChoice rule
greylist: graylist
grey-list: gray-list
14 changes: 14 additions & 0 deletions .vale/styles/config/vocabularies/GardenerTerms/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Gardener-specific CRDs, APIs, tools, and project names.
# Use (?i) prefix for terms that appear in mixed capitalizations in prose.
Diki
(?i)docforge
etcd-druid
gardenadm
gardenctl
Gardener
gardenlet
Garden Linux
GEP
(?i)kubeception
Podrick
Terraformer
27 changes: 27 additions & 0 deletions .vale/styles/config/vocabularies/General/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# General English words, loanwords, and place names missing from Vale's built-in dictionary
Augustiner
Bourgon
Brussel
decentrally
Freizeitheim
Hirschegg
homogenous
homogenously
Kunstlaan
Leverkusen
matcha
Mesnerhof
nonobvious
overconsumption
re-enable
reenable
Rofan
Schelklingen
Schlosshof
uncompromised
updateability
toolbelt
Vitosha
Walldorf
Westeurope
Weyhe
Loading