Research
Vale for research
Papers, notebooks, and the docs for the software research runs on.
Research produces two kinds of writing, often in the same repository: the paper, and the docs for the code behind it. For the paper, the Journals package turns the conventions every journal shares, the Nature and PLOS ONE guidelines, and the CONSORT, STROBE, and PRISMA checklists into rules read section by section, in Jupyter notebooks, Quarto, R Markdown, Typst, and MyST. For the docs, research groups from rOpenSci to Rubin Observatory already run Vale with a published style or one of their own.
Start with this config
The paper gets the shared conventions, the IMRaD structure, one journal’s guidelines, and the checklist for the study design; the docs get Google’s style, the most common choice among the research groups below. Vale prints a note that the docs section replaces the styles Journals turns on for every Markdown file: that is the point, since a README has no Methods section.
.vale.ini
StylesPath = styles
MinAlertLevel = suggestion
Packages = Journals, Google
Vocab = Journals
[paper/*.{md,qmd,ipynb}]
BasedOnStyles = Journals, IMRaD, PLOS, CONSORT
IMRaD.AbstractLength[max] = 300
[docs/**/*.md]
BasedOnStyles = Vale, Google 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.
Journals
Scientific manuscripts: a core of conventions for units, statistics, figures, and citations, the IMRaD structure, the Nature and PLOS ONE author guidelines, and the CONSORT, STROBE, and PRISMA checklists.
121 rules 1K downloads
A Vale-compatible implementation of the Google Developer Documentation Style Guide.
36 rules 2.2M downloads
Readability
Readability scores: Automated Readability Index, Coleman-Liau, Flesch-Kincaid, Flesch reading ease, Gunning fog, LIX, and SMOG, with a rule that names the polysyllables behind them.
8 rules 288K downloads
proselint
proselint places the world’s greatest writers and editors by your side.
120 rules 890.8K downloads
write-good
Naive linter for English prose for developers who can't write good.
9 rules 1.5M 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
Where it runs
The editors research is written in: VS Code and PyCharm for notebooks and Quarto, Emacs for Org. The same config runs in CI on the docs and the paper.
- VS Code VS Code, Cursor, Windsurf
- JetBrains IntelliJ, PyCharm, WebStorm
- Emacs flymake-vale
- Neovim via nvim-lspconfig
- GitHub Actions vale-cli/vale-action
- pre-commit Local hooks
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 - “set up vale end to end” /vale:onboard Try the style packages against your docs in a temp directory, draft a vocabulary, a decision per noisy rule, and the CI job, and show one proposal with before and after counts.
- “stop flagging our product name” /vale:vocab Add project terms to a vocabulary, import a word list kept for another spell checker, and set up a regional or other-language dictionary.
- “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.
- “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.
Who runs it
Research groups and institutes running Vale on the docs for the software their research depends on. The Journals package is new, so none of them lint papers with it yet.
- Rubin Observatory Lints the Rubin Science Platform docs against the Google style package plus house RSP rules, advisory on every pull request.
- rOpenSci Runs proselint, write-good, and alex over its website and blog.
- pyOpenSci Lints its handbook with a house pyos-styles style.
- nf-core Publishes an nf-core package for its bioinformatics pipeline docs.
- JuMP Lints its mathematical-optimization docs with Google's style across three repos.
- Qiskit The IBMQuantum style, with Latin abbreviations demoted to warnings.
- Mesa Lints its agent-based modeling docs with Google's style and a Mesa style.
- NEST Simulator Lints its reStructuredText docs with its own NEST style.
- OpenSAFELY Lints the docs for its NHS health-records research platform with an OpenSAFELY style.
- Lean Lints the Lean reference manual with proselint and a Lean style.
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 a manuscript Journals is a Vale package for scientific papers: the conventions every journal shares, the Nature and PLOS ONE author guidelines, and the CONSORT, STROBE, and PRISMA checklists, read section by section.
- Case study How Rubin Observatory made Vale advisory on purpose The Rubin Science Platform's docs run Google's style, two house rules, and a vocabulary built from a full spelling pass. Every finding is a suggestion to the writer, never a failed build, and the config explains each choice.
In the docs
- Jupyter notebooks
- Vocabularies
Terms your field accepts
- Spelling
- Scopes
Rules for one section
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 guideCreative
Fiction, essays, and the rules writers have argued over for a century.
Read the guideCode & data
The prose inside files that aren’t prose: comments, API descriptions, and the log.
Read the guideAI & agents
Hold what a model writes, and what you write for one, to a standard.
Read the guide