This is what an AI/RAG pipeline sees when it indexes this page — the same output served at https://camelmind-docs.vercel.app/api/llms/features/vale-integration.Back to doc
Rendered doc
Vale Integration
Lint your documentation for spelling, terminology, clarity, tone, and AI-writing artifacts with Vale, then customize the built-in style guide or replace it with your own.
CamelMind integrates with Vale, an open-source, configuration-driven prose linter that helps you catch writing issues before you publish your documentation.
Vale checks your .mdx files against a collection of styles and rules. Depending on the rules you enable, it can flag:
- Spelling and terminology issues
- Passive voice and wordiness
- Weasel words and clichés
- Inconsistent headings, acronyms, and terminology
- Jargon and corporate language
- Common artifacts of unedited AI-generated prose
CamelMind includes several styles out of the box and provides cm-light, a small built-in style that you can customize for your project's writing conventions.
CamelMind vendors its style packages under styles/vale/ instead of downloading them with vale sync. This keeps your linting rules in version control and ensures every author uses the same rules without depending on a network connection.
Default Vale style packages in CamelMind
CamelMind enables these default Vale style packages to check your documentation:
| Style | What it checks |
|---|---|
Vale | Spelling, using the project's vocabulary. |
write-good | Common prose issues such as passive voice, weasel words, wordiness, and clichés. |
Microsoft | Rules based on the Microsoft Writing Style Guide, including headings, contractions, acronyms, and dates. |
cm-light | CamelMind's opinionated style for common documentation issues. Use it as a starting point and customize it for your project. |
proselint | Additional prose-quality issues such as jargon, hedging, corporate language, and hyperbole. |
signs-of-ai-writing | Common artifacts of unedited AI-generated prose, such as citation markers, knowledge-cutoff disclaimers, and formulaic phrasing. |
You can configure these styles in .vale.ini at the root of your project:
StylesPath = styles/vale
MinAlertLevel = warning
Vocab = CamelMind
Packages = MDX
[*.mdx]
BasedOnStyles = Vale, write-good, Microsoft, cm-light, proselint, signs-of-ai-writing
# This codebase uses a spaced em dash (" — "), which conflicts
# with Microsoft's no-space convention.
Microsoft.Dashes = NO
The BasedOnStyles setting determines which styles Vale applies to your .mdx files.
You can also disable individual rules from a style without disabling the entire style. For example, Microsoft.Dashes = NO disables only the Microsoft Dashes rule.
Set up Vale for prose linting
Follow these steps to install and configure Vale prose linting for your CamelMind project:
Install Vale
Vale is a standalone CLI, not an npm package. Install it with your preferred package manager.
For example, on macOS:
brew install vale
For Windows and Linux installation options, see the Vale installation documentation.
Sync the MDX package
CamelMind vendors its style files, but the MDX package referenced by Packages = MDX is managed by Vale.
Run the following command once on your machine:
vale sync
You only need to run vale sync when the Vale package configuration changes or when setting up a new development environment.
Run a Vale check
Run the built-in linting script to check all documentation in the /content directory.
npm run lint:prose
To check an individual file, run:
node scripts/vale-preprocess.mjs content/[path-to-mdx-file]
For example:
node scripts/vale-preprocess.mjs content/getting-started/installation.mdx
Below is an example finding:
content/features/vale-integration.mdx 24:1 warning Do not use 'click' at the end of headings. cm-light.HeadingsPunctuation 41:12 error Do not use 'here' as the content of a link. cm-light.Link
To see all alerts, including suggestions, run:
node scripts/vale-preprocess.mjs --minAlertLevel=suggestion
Configure the built-in style
cm-light is CamelMind's lightweight, opinionated style, starting as a baseline rather than a fixed set of rules. CamelMind stores these rules in:
styles/vale/cm-light/
Each rule is a YAML file. For example, styles/vale/cm-light/Link.yml contains:
---
message: "Do not use '%s' as the content of a link."
extends: existence
ignorecase: true
scope: link
level: error
tokens:
- here
Change an existing Vale rule severity
To change the severity level of an existing Vale rule, update its level setting:
level: warning
Supported levels are:
suggestionwarningerror
To change what a rule detects, update its tokens or raw expression.
For example, you can change the link rule to flag additional vague link text:
tokens:
- here
- this page
- click here
Run the linter again to verify your changes:
npm run lint:prose
Add a new rule
Create a new YAML file in styles/vale/cm-light/.
For example, to flag unnecessary uses of "really," create styles/vale/cm-light/Really.yml with:
---
extends: existence
message: "Consider removing 'really' — it rarely adds meaning."
level: suggestion
ignorecase: true
tokens:
- really
Vale automatically discovers .yml rule files in the style directory. You do not need to register the new rule.
Run the linter again:
npm run lint:prose
If the word "really" appears in your documentation, Vale reports it as a suggestion.
Disable individual Vale style rules
You can disable an individual Vale linting rule without removing its entire parent style from your project.
Disable an individual rule in .vale.ini using the style and rule name:
[*.mdx]
BasedOnStyles = Vale, write-good, Microsoft, cm-light, proselint, signs-of-ai-writing
Microsoft.Dashes = NO
The Microsoft.Dashes = NO setting disables only the Dashes rule from the Microsoft style.
This approach is useful when you want a style's guidance but have a specific project convention that conflicts with one rule.
Manage your Vale project vocabulary
Vale uses a custom project vocabulary to recognize and verify terms specific to your CamelMind documentation.
CamelMind configures the vocabulary with:
Vocab = CamelMind
CamelMind stores the vocabulary in:
styles/vale/config/vocabularies/CamelMind/
It contains two files:
Use accept.txt for terms that Vale should recognize as valid and not flag as misspellings.
CamelMind's vocabulary already includes project-specific terms such as:
CamelMind
Next\.js
camelmind\.config\.ts
Since Vale supports regular expressions, escape literal periods when necessary. Add one term or pattern per line:
# styles/vale/config/vocabularies/CamelMind/accept.txt
MyProductName
API-Gateway
Use reject.txt for terms that you want Vale to flag wherever they appear. This is useful for:
- Deprecated product names
- Terms your team no longer uses
- Words that require replacement with preferred terminology
For example:
# styles/vale/config/vocabularies/CamelMind/reject.txt
old-product-name
whitelist
The file is empty by default.
Replace the built-in style
If cm-light does not match your team's writing conventions, you can replace it with your own style.
Create a style
Create a directory under styles/vale/:
styles/vale/my-style/
Add one YAML rule file for each rule you want to use.
You can write your own rules or vendor rules from an existing Vale style by copying their .yml files into your style directory.
Update .vale.ini
Replace cm-light with your style in BasedOnStyles:
[*.mdx]
BasedOnStyles = Vale, write-good, Microsoft, my-style, proselint, signs-of-ai-writing
You can also keep cm-light and add your own style alongside it:
[*.mdx]
BasedOnStyles = Vale, write-good, Microsoft, cm-light, my-style, proselint, signs-of-ai-writing
Remove cm-light if you do not need it
If you're fully replacing the built-in style, remove its directory:
styles/vale/cm-light/
If you are keeping it alongside your custom style, no changes are needed.
Run the linter
Run the check again:
npm run lint:prose
Confirm that your new rules are being applied and that .vale.ini contains no unintended references to the old style.
Add an existing Vale style
You can also extend CamelMind's configuration with an existing Vale style.
If you vendor the style into your project, place its rule files under styles/vale/ and add the style name to BasedOnStyles.
For example:
[*.mdx]
BasedOnStyles = Vale, write-good, Microsoft, cm-light, proselint, signs-of-ai-writing, my-style
Keeping style files in your repository versions the rules alongside your documentation and ensures consistency across development environments.
Use Vale in CI
Running Vale locally catches writing issues before they reach your pull request. You can also run the same check in CI to enforce your documentation standards.
Use:
npm run lint:prose
A typical workflow is:
- Authors run Vale locally while writing.
- Pull requests run the same linting command automatically.
error-level findings block the merge.- Authors review
warning-level findings without blocking the pipeline merge. - The style configuration and vocabulary remain version-controlled with the documentation.
This gives your documentation team a consistent writing quality gate without requiring an external service.
Troubleshoot Vale
Vale command not found
If you see an error such as:
vale: command not found
Vale is not installed or is not available on your PATH.
Install Vale using your package manager and verify the installation:
vale --version
MDX package not found
If Vale reports that the MDX package cannot be found, run:
vale sync
The Packages = MDX setting in .vale.ini tells Vale which package to load for MDX-aware linting.
A custom rule isn't being detected
Check that:
- The rule is stored under the configured
StylesPath. - The rule file has a
.ymlextension. - The style containing the rule appears in
BasedOnStyles. - The rule's
levelisn't below the configuredMinAlertLevel.
For example:
StylesPath = styles/vale
MinAlertLevel = warning
[*.mdx]
BasedOnStyles = cm-light
If your rule uses:
level: suggestion
it won't appear with MinAlertLevel = warning.
To test it explicitly:
node scripts/vale-preprocess.mjs --minAlertLevel=suggestion
How Vale fits into CamelMind
Vale focuses on prose quality and writing consistency. CamelMind's other AI-focused tools address different parts of the documentation pipeline.
| Tool | Purpose |
|---|---|
| Vale | Lint prose for spelling, terminology, style, clarity, and common AI-writing artifacts. |
| AI View | Preview the AI-readable representation of a documentation page. |
| Run RAG Check | Test chunking, retrieval, and AI-readiness using a local heuristic evaluation. |
| llms.txt | Publish AI-readable documentation in the llms.txt format. |
Together, these tools help you review documentation from both sides:
- Vale checks whether the content is well written.
- AI View checks what an AI system actually receives.
- Run RAG Check verifies that retrieval systems can chunk and retrieve your content.
- llms.txt makes the resulting documentation available in an AI-friendly format.
Related
- Writing Content — Learn the general MDX authoring conventions that your Vale configuration helps enforce.
- AI View — Preview the AI-readable version of your documentation.
- Run RAG Check — Check how your documentation performs when chunked and retrieved.
- llms.txt — Learn how CamelMind generates AI-readable documentation.
- Vale documentation — See the complete reference for Vale rules, styles, and configuration.