Code & data
Vale for code and data
The prose inside files that aren’t prose: comments, API descriptions, and the log.
A repository has prose all through it that no docs linter reads: doc comments, the descriptions in an OpenAPI spec, a commit’s subject and body. Vale finds it. Tree-sitter grammars lift comments out of source code, a View pulls named fields out of JSON and YAML, and a TextFSM template splits a commit message into its parts, so a rule reaches a commit subject the way it reaches a heading.
Start with this config
Commit messages against Conventional Commits, and doc comments against their language’s conventions. Grammars has vale sync fetch the parsers that find the comments. For the descriptions in an OpenAPI spec, add the View from the Views docs.
.vale.ini
StylesPath = styles
Packages = Commits, Comments
Grammars = go, java, kotlin
[COMMIT_EDITMSG]
BasedOnStyles = Commits, Conventional
[*.{go,java,kt}]
BasedOnStyles = Vale, Comments Then download the packages it names and run Vale over the project:
$ vale sync
$ vale . Packages
Published styles to start from. A package in the Explorer installs by name with Packages and vale sync, one published elsewhere by its release URL, and every rule in either can be turned off or changed in your own config.
Commits
Commit messages: nine conventions and the rule sets of commitlint, gitlint, committed, conform, and commitizen, read through a View.
97 rules 6.8K downloads
Comments
The comments in code: Go doc comments, Javadoc, and KDoc conventions, plus owned TODOs and no commented-out code in any language Vale extracts comments from.
14 rules 922 downloads
TechTerms
A spelling dictionary of 115,000 technical terms, from product and company names to file types and the vocabulary of some 30 programming languages, built from cspell's MIT-licensed word lists. Vale.Spelling uses it beside its own dictionary.
12 downloads
Std
The standard library for Vale: general-purpose rules you extend to build your own style.
14 rules 25.8K downloads
Where it runs
A commit-msg or pre-commit hook checks the message and the comments before they land, CI checks them again, and the language server flags them in any editor that speaks LSP. Qt Creator covers QDoc comments.
- pre-commit Local hooks
- GitHub Actions vale-cli/vale-action
- Language server Any LSP-capable editor
- VS Code VS Code, Cursor, Windsurf
- JetBrains IntelliJ, PyCharm, WebStorm
- Neovim via nvim-lspconfig
- Qt Creator via the Qt wiki
With an agent
All agent toolsThe agent tools install as a Claude Code plugin: skills for setting up and tuning Vale, and hooks that lint each file the assistant writes. Type both lines in Claude Code, then ask for what you need.
/plugin marketplace add vale-cli/agent-tools
/plugin install vale@agent-tools - “lint our commit messages” /vale:commits Score your recent history against the common conventions, set up the one it already follows, and add the hook and the CI check.
- “run this on PRs” /vale:ci Generate the GitHub Actions workflow or the pre-commit entry from what the repository already has. Asks what it should look at, what to report, and when to fail.
- “add prose linting” /vale:setup Install Vale, write a .vale.ini that matches the formats actually present, sync the styles, and get a first run. Covers translated docs and the comments in source code.
- “it’s flagging our shortcodes” /vale:ignore Take text that is not prose out of Vale’s view: shortcodes, templating tags, generated blocks, one quoted passage.
Who runs it
Teams who lint the prose outside their docs: comments in Rust, Go, TypeScript, and Java, Python docstrings, API specs, and changesets.
- pnpm Lints its docs, changesets, and Rust and TypeScript sources with a house pnpm style.
- Renovate Enforces American English and product naming across its docs and TypeScript sources with a Renovate style.
- Gravitee Lints its docs, and comments in source files, with Microsoft's style and its own docs rules.
- pgEdge Lints Markdown docs, llms.txt files, and Go doc comments at error level with its own PgEdge style.
- Veecle Lints Markdown and Rust comments with its own veecle style.
- TestNG Lints its Markdown and Java sources with a TestNG style.
- Workflow Orchestrator Lints Markdown and Python docstrings with Microsoft's style and proselint.
- DigitalService Lints documentation and TypeScript comments in a German federal justice service with the proselint and alex packages and a project vocabulary.
- Open Podcast API Holds its API specs to Google's style and write-good at the error level.
- Marigold Lints its design-system docs, changesets, and READMEs with its own Marigold style, in pre-commit and CI.
Formats
Where this kind of writing lives. Vale parses each one, so rules see the prose and skip the markup, the code, and the URLs.
Read more
On the blog
- Linting commit messages Commits is a Vale package for the log: nine conventions, the rule sets of commitlint, gitlint, committed, conform, and commitizen, spelling on the body, and a hook that runs in 12 ms.
- Vale and the OpenAPI Specification A tutorial on linting OpenAPI Specification files: extract just the prose from a structured file, with errors reported at their exact location.
Other kinds of writing
Technical
Docs, references, and the style guide your team already follows.
Read the guidePublic sector
Plain English for the public, held to a government style guide.
Read the guideResearch
Papers, notebooks, and the docs for the software research runs on.
Read the guideCreative
Fiction, essays, and the rules writers have argued over for a century.
Read the guideAI & agents
Hold what a model writes, and what you write for one, to a standard.
Read the guide