Skip to content

Conversation

@jstirnaman
Copy link
Contributor

Summary

Adds Vale prose linting to complement the existing markdownlint setup. While markdownlint checks Markdown formatting, Vale checks prose style, grammar, and terminology consistency.

Changes

  • .vale.ini: Configuration using Google Developer Documentation Style Guide
  • .vale/styles/Telegraf/: Custom rules for Telegraf documentation:
    • Latin.yml: Flags Latin abbreviations (e.g., i.e., etc.) - suggest plain English
    • Grammar.yml: Flags common grammar issues ("allows to", "in order to", "In case")
    • Terms.yml: Enforces correct product name capitalization (InfluxDB, Telegraf)
  • .github/workflows/vale.yml: Runs Vale on PR changes to Markdown files
  • docs/developers/PROSE_STYLE.md: Documentation for contributors
  • CONTRIBUTING.md: Updated with Vale reference

How it works

  • Runs automatically on PRs that modify .md files
  • Only lints changed files (not entire codebase)
  • Reports issues as PR annotations
  • Currently configured as non-blocking (fail_on_error: false)

Running locally

# Install Vale
brew install vale  # macOS

# Download style packages
vale sync

# Lint files
vale plugins/inputs/cpu/README.md

Test plan

  • Vale configuration validates (vale ls-config)
  • Custom rules are syntactically correct
  • Workflow file is valid YAML
  • Documentation is complete and accurate

Add Vale linter configuration for checking prose style, grammar, and
terminology in Markdown documentation. This complements the existing
markdownlint setup by checking the quality of written content.

Changes:
- Add .vale.ini configuration with Google style guide
- Add custom Telegraf style rules:
  - Latin.yml: Avoid Latin abbreviations (e.g., i.e., etc.)
  - Grammar.yml: Fix common grammar issues (allows to, in order to)
  - Terms.yml: Enforce correct product name capitalization
- Add GitHub Actions workflow to run Vale on PRs
- Add docs/developers/PROSE_STYLE.md documentation
- Update CONTRIBUTING.md with Vale reference

The workflow runs only on changed Markdown files and reports issues
as PR annotations without failing the build.
@srebhan srebhan changed the title ci: Add Vale prose linting for documentation chore(ci): Add Vale prose linting for documentation Dec 4, 2025
@telegraf-tiger telegraf-tiger bot added the chore label Dec 4, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant