Table of contents
- What are proselint and vale?
- Proselint vs Vale: the comparison
- Question 1: do your docs live in markup?
- Question 2: whose style are you enforcing - yours, or someone else’s?
- Conclusion: the verdict
- Work with Weesho Lapara
- Additional resources
If you write documentation the way your team writes code, in Markdown, in a Git repo, reviewed through pull requests, then “which prose linter is better” is the wrong question. The better question is: do you want a spell-checker that lives on your laptop, or a quality gate that runs on every change before it ships?
That framing decides the whole thing. proselint and Vale are both good, and they’re built for different jobs. Here’s how I choose between them.
What are proselint and vale?
Proselint is a Python-based linter for prose. It applies a curated set of rules drawn from established writing wisdom, so its feedback is consistent and authoritative out of the box. You install it through Python and pip and run it against your text with no configuration. Proselint’s biggest strength is also its biggest drawback: what you see is what you get. It doesn’t understand Markdown or HTML formatting, and because it isn’t extensible, you can’t add your own custom house rules. You just have to play by its rules.
Vale is a linter written in Go and distributed as a standalone binary. It is markup-aware, so it can lint Markdown, AsciiDoc, HTML, and XML without tripping over the syntax. It is extensible through YAML rules, and it supports popular style guides out of the box, which lets you enforce a specific house style. Vale also offers a hosted option for teams. The trade-off is that Vale is less opinionated by default and expects you to bring or configure a style, which means a little YAML knowledge and some setup.
That’s the surface. But the choice comes down to two questions.
Proselint vs Vale: the comparison
The table below compares the two tools across key dimensions that matter for documentation teams.
| proselint | Vale | |
|---|---|---|
| Extensibility | Not extensible | Extensible via YAML rules |
| Markup support | Not markup-aware | Markdown, AsciiDoc, HTML, XML |
| Installation | Python and pip | Standalone binary |
| Style guides | Built-in defaults | Supports popular style guides and allows building custom rules |
| License | Open source | Open source |
| Best for | Solo writers who don’t mind quick and smart prose check | Writers of all size who want maximum control over the rules and work with markups regularly |
Question 1: do your docs live in markup?
proselint reads plain text, so it can’t tell a fenced code block from a paragraph. Run it on real .md files and it flags variable names, CLI flags, and JSON keys as prose errors. You end up preprocessing your files or wading through false positives.
Vale parses the markup. It lints your sentences and leaves your code samples, links, and headings alone, and it can apply different rules to different elements. For anything that lives in a repo full of Markdown, that single difference is usually decisive.
Question 2: whose style are you enforcing - yours, or someone else’s?
This is the real fork.
proselint’s rules are hard-coded. You can switch checks on and off, but you can’t teach it that your product name is lowercase, or that “simply” is banned in your tutorials.
Vale lets you encode your house style as rules and run them like tests, and you can set it up as a GitHub Actions merge gate to enforce those rules on every pull request. A rule is just a few lines of YAML. That’s the entire reason most documentation teams adopt Vale: the style guide stops being a PDF nobody reads and becomes something that flags its own violations.
Conclusion: the verdict
Proselint is excellent at the thing it’s built for: a sharp, authoritative second read on a single piece of writing. Drafting a blog post or an essay and want an editor’s reflexes pointed at your prose with zero configuration? proselint draft.md is hard to beat, and its opinions are sound. The catch is that you can’t bend it to a team’s needs, and it doesn’t understand the files documentation actually lives in.
For any team shipping documentation alongside software i.e., product docs, API references, runbooks, anything that moves through pull requests: Vale. It’s markup-aware, it allows enforcing custom rules instead of someone else’s, and you can load proselint’s checks inside it as one package among several. So it isn’t really an either/or. Vale can give you proselint’s taste plus everything proselint can’t do.
Work with Weesho Lapara
Want help choosing and rolling out a linter across your docs? Book a consult or get in touch and we will set it up around your style guide.