Vale Linting

Vale Style Linting Workflow

Purpose

This skill covers the complete Vale linting workflow for InfluxData documentation, including running Vale, understanding the rule configuration, adding vocabulary terms, and creating custom rules.

Use this skill when:

• Running Vale style checks on documentation
• Debugging Vale warnings or errors
• Adding terms to the vocabulary (accept/ignore lists)
• Creating or modifying custom Vale rules
• Understanding why certain patterns are flagged

Quick Reference

# Run Vale on specific files
.ci/vale/vale.sh --config=.vale.ini content/influxdb3/core/**/*.md

# Run with minimum alert level
.ci/vale/vale.sh --config=.vale.ini --minAlertLevel=warning content/path/

# Sync Vale packages (after .vale.ini changes)
.ci/vale/vale.sh sync

# Show Vale configuration
.ci/vale/vale.sh ls-config

Part 1: How Vale Runs

Execution via .ci/vale/vale.sh

The wrapper script .ci/vale/vale.sh runs Vale using:

1. Local binary (preferred) — if vale is installed and version >= 3.x
2. Docker fallback — jdkato/vale:v${VALE_VERSION} (pinned version), only if the Docker daemon is running
3. Graceful skip — if neither is available, the wrapper prints a warning and exits 0 so other pre-commit hooks still run

# The wrapper handles binary vs Docker automatically
.ci/vale/vale.sh --config=.vale.ini content/path/

# In CI, the pr-vale-check.yml workflow installs the Vale binary
# directly (reads version from vale.sh), so Docker is not needed.

Sandboxed agent sessions (no Docker daemon, GitHub release downloads blocked): Vale can't run locally, so the wrapper skips it (exit 0) with a warning. Do NOT use git commit --no-verify — that bypasses all hooks, not just Vale. Let the commit proceed normally; the pr-vale-check.yml workflow is the authoritative gate and blocks merge on errors. It sets VALE_STRICT=1, which makes the wrapper fail instead of skip if Vale is ever unavailable in CI. To run Vale in a sandbox anyway, ask an environment admin to allowlist the Vale release host (github.com/vale-cli/vale) in the environment's network policy.

Critical limitation: Only files inside the repository are accessible when using Docker fallback. Files in /tmp or other external paths will silently fail.

macOS note: The CI script .github/scripts/vale-check.sh uses declare -A (associative arrays) which requires bash 4+. macOS ships bash 3.2. Use /opt/homebrew/bin/bash or run tests in CI instead.

Configuration Files

Part 2: Understanding Vale Rules

Rule Sources

Vale uses multiple rule sources, configured in .vale.ini:

BasedOnStyles = Vale, InfluxDataDocs, Google, write-good

1. Vale - Built-in rules (Spelling, Terms, Repetition)
2. InfluxDataDocs - Custom rules for this repo
3. Google - Google Developer Documentation Style Guide
4. write-good - Plain English suggestions

Disabled Rules (and Why)

Rules are disabled in two categories across .vale.ini and all product configs:

Mechanical rules disabled (replaced by custom equivalents or incompatible with InfluxDB syntax):

Style rules disabled (high false-positive rate in technical docs):

Active Custom Rules

Part 3: Adding Vocabulary Terms

Accept List (Technical Terms)

Add terms to .ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt:

# Case-insensitive by default
CPUs
systemd
preconfigured

# Regex patterns for variations
[Dd]ownsampl(e|ed|es|ing)
subprocess(es)?

# Exact case matching (regex)
(?i)InfluxQL

Ignore List (Spelling Only)

Add terms to .ci/vale/styles/InfluxDataDocs/Terms/ignore.txt:

# Simple words (case-insensitive)
cgroup
humantime
deadman

# The ignore.txt is referenced by Spelling.yml

Key difference in this repo:

• accept.txt - Terms that are part of the shared spelling vocabulary (via Vocab = InfluxDataDocs). In this repository, it does not currently create substitution rules because Vale.Terms is disabled in .vale.ini. If Vale.Terms is enabled in the future, these terms may also drive substitution behavior.
• ignore.txt - Additional terms to skip in spell checking only (an ignore list layered on top of the shared vocabulary; no substitution rules).

When to Use Each

Part 4: Creating Custom Rules

This section covers where rules live in this repo and shows two real examples. For the rule-authoring deep dive — rule types, the regexp2 engine, PCRE lookarounds, and testing patterns in isolation — use the vale-rule-config skill.

Rule File Location

Custom rules go in .ci/vale/styles/InfluxDataDocs/:

.ci/vale/styles/InfluxDataDocs/
├── Acronyms.yml
├── Branding.yml
├── Capitalization.yml
├── Ellipses.yml
├── Spelling.yml
├── Units.yml          # Custom: allows duration literals
├── WordList.yml
└── Terms/
    ├── ignore.txt
    └── query-functions.txt

Example: Custom Units Rule

This rule validates byte units while allowing InfluxDB duration literals:

# .ci/vale/styles/InfluxDataDocs/Units.yml
extends: existence
message: "Put a nonbreaking space between the number and the unit in '%s'."
link: "https://developers.google.com/style/units-of-measure"
nonword: true
level: warning
# Only check byte units. Duration units (ns, ms, s, min, h, d) are excluded
# because InfluxDB duration literals use no space (e.g., 30d, 24h, 1h).
tokens:
  - \b\d+(?:B|kB|MB|GB|TB|PB)

Example: Spelling Rule with Scope Exclusions

# .ci/vale/styles/InfluxDataDocs/Spelling.yml
extends: spelling
message: "Did you really mean '%s'?"
level: warning
# Exclude from spell checking:
scope:
  - ~code        # Fenced code blocks
  - ~raw         # Inline code
  - ~table.header
  - ~table.cell
ignore:
  - InfluxDataDocs/Terms/ignore.txt
  - InfluxDataDocs/Terms/query-functions.txt
filters:
  # Ignore URL paths
  - '/[a-zA-Z0-9/_\-\.\{\}]+'
  # Ignore full URLs
  - 'https?://[^\s\)\]>"]+'

Part 5: Debugging Vale Issues

Common Problems

"0 errors in stdin"

• File is outside the repository (Docker can't access it)
• Solution: Use files inside the repo for testing

Rule not triggering

• Check if rule is disabled in .vale.ini
• Verify rule file has valid YAML syntax
• Run vale sync after adding new packages

False positives in URLs/code

• Add patterns to TokenIgnores in .vale.ini
• Add scope exclusions (~code, ~raw) to the rule
• Add terms to ignore.txt

Debugging Commands

# Show all configuration
.ci/vale/vale.sh ls-config

# Validate YAML syntax
node -e "require('js-yaml').load(require('fs').readFileSync('path/to/rule.yml'))"

# Test specific file
.ci/vale/vale.sh --config=.vale.ini --minAlertLevel=suggestion path/to/file.md

Part 6: Vale Cannot Inspect URLs

TokenIgnores in .vale.ini strips all URLs before any rules run:

TokenIgnores = https?://[^\s\)\]>"]+

This means no Vale rule can match URL content. An earlier attempt to create a SupportLink.yml rule to validate support.influxdata.com URL patterns failed for this reason — the URLs were stripped before the rule could see them. Support URL validation uses a separate shell script (.ci/scripts/check-support-links.sh) instead.

Keep this in mind when designing rules: if the pattern to match is inside a URL, use a shell script or pre-commit hook, not a Vale rule.

Part 7: TokenIgnores vs Rule Filters

TokenIgnores (in .vale.ini)

Applied globally to all rules. Matches whole tokens:

TokenIgnores = /[a-zA-Z0-9/_\-\.]+, \
  https?://[^\s\)\]>"]+, \
  `[^`]+`

Limitation: Cannot match substrings within words. If "api" appears in /api/v3/write, the URL pattern must match the entire URL to exclude it.

Rule Filters (in rule YAML)

Applied to specific rules. Can match patterns within text:

filters:
  - '[Ss]erverless'  # Allow both cases
  - '/[a-zA-Z0-9/_\-\.\{\}]+'  # URL paths

When to Use Each

Part 7: Workflow Examples

Adding a New Technical Term

# 1. Identify the term and its usage
grep -r "systemd" content/

# 2. Add to ignore list (spelling only)
echo "systemd" >> .ci/vale/styles/InfluxDataDocs/Terms/ignore.txt

# 3. Or add to accept.txt (if it should influence Vale.Terms)
echo "systemd" >> .ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt

# 4. Test the change
.ci/vale/vale.sh --config=.vale.ini content/path/with/term.md

Creating a Product-Specific Override

[!Important] Product-specific .vale.ini files must include the same disabled rules as the root .vale.ini. Rules disabled in the root config are not inherited by product-specific configs. Omitting them re-enables the rules for those products. For example, omitting Google.Units = NO causes duration literals like 7d, 24h to be flagged as errors in product-specific linting runs.

# 1. Create product-specific .vale.ini
cat > content/influxdb3/cloud-dedicated/.vale.ini << 'EOF'
StylesPath = ../../../.ci/vale/styles
MinAlertLevel = warning
Vocab = InfluxDataDocs

Packages = Google, write-good, Hugo

[*.md]
BasedOnStyles = Vale, InfluxDataDocs, Cloud-Dedicated, Google, write-good

# --- Disabled mechanical rules ---
Google.Acronyms = NO
Google.DateFormat = NO
Google.Ellipses = NO
Google.Headings = NO
Google.WordList = NO
Google.Units = NO
Vale.Spelling = NO
Vale.Terms = NO

# --- Disabled style rules (high false-positive rate in technical docs) ---
Google.Contractions = NO
Google.FirstPerson = NO
Google.Passive = NO
Google.We = NO
Google.Will = NO
write-good.Cliches = NO
write-good.Passive = NO
write-good.So = NO
write-good.ThereIs = NO
write-good.TooWordy = NO
write-good.Weasel = NO

TokenIgnores = /[a-zA-Z0-9/_\-\.]+, \
  https?://[^\s\)\]>"]+, \
  `[^`]+`
EOF

# 2. Run Vale with product config
.ci/vale/vale.sh --config=content/influxdb3/cloud-dedicated/.vale.ini \
  content/influxdb3/cloud-dedicated/**/*.md

Debugging Why a Pattern is Flagged

# 1. Check which rule is triggering
.ci/vale/vale.sh --config=.vale.ini path/to/file.md
# Output shows: InfluxDataDocs.WordList, Vale.Terms, etc.

# 2. Read the rule file
cat .ci/vale/styles/InfluxDataDocs/WordList.yml

# 3. Check if term is in vocabulary
grep -i "term" .ci/vale/styles/config/vocabularies/InfluxDataDocs/*.txt

# 4. Check TokenIgnores patterns
grep TokenIgnores .vale.ini

Checklist: Before Committing Vale Changes

• Ran vale sync if packages changed
• Tested changes on sample files
• Verified no unexpected rules are disabled
• Added comments explaining why rules are disabled
• Kept vocabulary files alphabetized
• Used ignore.txt for spelling-only terms
• Used accept.txt for terms that should influence substitution

Related Files