Importing Configuration

By default the spell checker searches the current directory and up the hierarchy for the following configuration files.

Yaml

• .cspell.config.yaml
• .cspell.config.yml
• cspell.config.yaml
• cspell.config.yml
• .cspell.yaml
• .cspell.yml
• cspell.yaml
• cspell.yml

Json

• package.json
• .cspell.json
• cspell.json
• .cSpell.json
• cSpell.json
• .cspell.jsonc
• cspell.jsonc
• .cspell.config.json
• .cspell.config.jsonc
• cspell.config.json
• cspell.config.jsonc

JavaScript

• cspell.config.mjs
• cspell.config.cjs
• cspell.config.js
• .cspell.config.mjs
• .cspell.config.cjs
• .cspell.config.js

TypeScript

• cspell.config.mts
• cspell.config.ts
• cspell.config.cts
• .cspell.config.mts
• .cspell.config.ts
• .cspell.config.cts

Toml

• cspell.config.toml
• .cspell.config.toml

.vscode

• .vscode/cspell.json
• .vscode/cSpell.json
• .vscode/.cspell.json

info

cspell configuration files can be prefixed with . and or .config, i.e. .cspell.config.yaml, .config/cspell.config.yaml and .config/.cspell.config.yaml.

info

package.json: Only the cspell field in package.json is considered.

The first configuration file found will be loaded, the others will be ignored. To leverage multiple CSpell configuration files, the spell checker supports an import field. The import field is used to list files to be imported in order.

The spell checker "merges" configuration to build the settings used to check a document.

• import - Each configuration file can import more configuration files. The files listed in the import are merged from first to last with the parent (the one that did the import) merged at the end.

Merging

cspell.yml

language: fr
import:
  - cspell-a.yml
  - cspell-b.yml
words:
  - root

cspell-a.yml

dictionaries:
  - aws # enable aws dictionary
  - '!html' # Disable `html` dictionary
words:
  - apple

cspell-b.yml

language: en
dictionaries:
  - '!softwareTerms' # Disable software-terms dictionary.
  - html # enable html
words:
  - banana

Merged Result:

language: fr
dictionaries:
  - aws
  - '!html'
  - '!softwareTerms'
  - html
words:
  - root
  - apple
  - banana

Dictionary order does not matter. The number of !s is more important. In this case the html and softwareTerms dictionaries will NOT be used, nor will the English dictionary due to the language being fr.

Conditional Configuration

• overrides - Overrides are used to apply settings based upon the file / path name of the file being checked matching the globs defined in filename.
• languageSettings - Language settings are used to apply settings based upon matching the file type (languageId) or locale. A languageId or locale of * will match any file type or natural language respectively. languageId is a bit confusing because it originally referred to programming language, but it is really just a file type like json or python.

Terminology Note

languageId: refers to file types (like javascript, python, markdown), not spoken languages (like English, German or Spanish). For historical reasons languageId was chosen to match VSCode's Language Identifiers in meaning.