Skip to content

Add Vale prose linter for documentation quality via Trunk#3822

Open
elviskahoro wants to merge 1 commit intodlt-hub:develfrom
SanhedrinTech:chore/add-trunk-linter-config
Open

Add Vale prose linter for documentation quality via Trunk#3822
elviskahoro wants to merge 1 commit intodlt-hub:develfrom
SanhedrinTech:chore/add-trunk-linter-config

Conversation

@elviskahoro
Copy link
Copy Markdown
Contributor

@elviskahoro elviskahoro commented Apr 1, 2026

Description

Part of the Docs as a product initiative. This PR introduces Vale to enforce consistent writing style and terminology across our documentation β€” a gap called out explicitly in our docs strategy.

Why Vale

Inconsistent terminology and style drift across docs contributed by different teams (product, DevRel, SolEng) erodes user trust, hurts SEO, and causes AI coding assistants to produce unreliable output. Vale is the industry standard prose linter used by GitLab, Spotify, and Linode to solve exactly this problem β€” configurable, CI-friendly, and extensible with custom vocabulary rules.

Why Trunk as the runner

Rather than adding Vale as a standalone tool with its own config, CI step, and install process, this PR uses Trunk as a managed wrapper.

  • Trunk only flags issues in new or changed lines, not the entire file β€” a concept they call "hold the line." This means enabling Vale doesn't halt engineering with thousands of pre-existing warnings. Teams can adopt linting incrementally without a "fix the world" prerequisite.
  • Trunk runs all enabled linters against your files in parallel, so a single trunk check invocation runs everything without sequential scripts or glue code.
  • Trunk has out-of-the-box support for dozens of linters. Starting with Vale today doesn't preclude adding markdownlint, semgrep, or other tools tomorrow β€” they all compose under the same trunk check command. See this config for an example of a multi-linter setup.
  • Trunk pins and downloads the exact Vale version (v3.14.1), so every contributor and CI runner uses the same binary without "works on my machine" issues.
  • Trunk is purely a runner β€” the Vale config (.vale.ini, style rules) is fully portable. If we later decide against Trunk, we keep all the Vale work and just change how we invoke it.

Scope

  • Vale is scoped exclusively to docs/** β€” zero impact on source code.
  • trunk-fmt-pre-commit is disabled to preserve existing ruff/black workflows.

Changes

  • .trunk/trunk.yaml β€” Trunk CLI config (v1.25.0) with Vale v3.14.1, scoped to docs/** only
  • .trunk/configs/.vale.ini β€” Vale style config with markdoc format support
  • .trunk/.gitignore β€” excludes Trunk build artifacts and user-local config from version control

Next steps

  • Add custom Vale style rules for dlt-specific terminology (e.g. dlt casing, product names, API terms)
  • Integrate into CI for docs-only PRs

- Add .trunk/trunk.yaml with Vale v3.14.1 linter configured for docs/
- Add .trunk/configs/.vale.ini with markdown linting rules
- Add .trunk/.gitignore to exclude trunk-generated files
@elviskahoro elviskahoro changed the title chore: add trunk linter configuration Add Vale prose linter for documentation quality via Trunk Apr 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant