Skip to main content

Configuration

CSpell's behavior can be controlled through a config file.

By default it looks for any of the following files:

  • .cspell.config.yaml
  • .cspell.config.yml
  • cspell.config.yaml
  • cspell.config.yml
  • .cspell.yaml
  • .cspell.yml
  • cspell.yaml
  • cspell.yml
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.

Or you can specify a path to a config file with the --config <path> argument on the command line.

How Configuration Is Resolved​

Spell checking is a two step process. CSpell first decides which files to check, from command line globs (or --file/--files/--file-list), filtered against ignorePaths and .gitignore. It then determines the settings for each document by merging the default configuration, the configuration loaded at start up, and the configuration nearest the document, before applying overrides, languageSettings, and any in-document directives, in that order. See Configuration Resolution & Overrides for the full precedence order.

cspell.json​

Example cspell.json file​

// cSpell Settings
{
    // Version of the setting file.  Always 0.2
    "version": "0.2",
    // language - current active spelling language
    "language": "en",
    // words - list of words to be always considered correct
    "words": [
        "mkdirp",
        "tsmerge",
        "githubusercontent",
        "streetsidesoftware",
        "vsmarketplacebadge",
        "visualstudio"
    ],
    // flagWords - list of words to be always considered incorrect
    // This is useful for offensive words and common spelling errors.
    // For example "hte" should be "the"
    "flagWords": [
        "hte"
    ]
}

cspell.json sections​

  • version - currently always 0.2 - controls how the settings in the configuration file behave.

  • language - this specifies the language locale to use in choosing the general dictionary. For example: "language": "en-GB" tells cspell to use British English instead of US English.

  • words - a list of words to be considered correct.

  • flagWords - a list of words to be always considered incorrect

  • ignoreWords - a list of words to be ignored (even if they are in the flagWords).

  • ignorePaths - a list of globs to specify which files are to be ignored.

    Example

    "ignorePaths": ["node_modules/**"]

    will cause cspell to ignore anything in the node_modules directory.

  • maxNumberOfProblems - defaults to 100 per file.

  • minWordLength - defaults to 4 - the minimum length of a word before it is checked.

  • allowCompoundWords - defaults to false; set to true to allow compound words by default.

  • dictionaries - list of the names of the dictionaries to use. See Dictionaries.

  • dictionaryDefinitions - this list defines any custom dictionaries to use. This is how you can include other languages like Spanish.

    Example

    "language": "en",
    // Dictionaries "spanish", "ruby", and "corp-terms" will always be checked.
    // Including "spanish" in the list of dictionaries means both Spanish and English
    // words will be considered correct.
    "dictionaries": ["spanish", "ruby", "corp-terms", "fonts"],
    // Define each dictionary:
    //  - Relative paths are relative to the config file.
    //  - URLs will be retrieved via HTTP GET
    "dictionaryDefinitions": [
        { "name": "spanish", "path": "./spanish-words.txt"},
        { "name": "ruby", "path": "./ruby.txt"},
        {
          "name": "corp-terms",
          "path": "https://shared-company-repository/cspell-terms.txt"
        },
    ],

  • ignoreRegExpList - list of patterns to be ignored

  • includeRegExpList - (Advanced) limits the text checked to be only that matching the expressions in the list.

  • patterns - this allows you to define named patterns to be used with ignoreRegExpList and includeRegExpList.

    Example

    "patterns": [
        {
            "name": "comment-single-line",
            "pattern": "/#.*/g"
        },
        {
            "name": "comment-multi-line",
            "pattern": "/(?:\\/\\*[\\s\\S]*?\\*\\/)/g"
        },
        // You can also combine multiple named patterns into one single named pattern
        {
            "name": "comments",
            "pattern": ["comment-single-line", "comment-multi-line"]
        }
    ],

    "ignoreRegExpList": ["comments"]

  • languageSettings - this allow for per programming language configuration settings. See LanguageSettings.

package.json​

It is possible to store CSpell configuration in the package.json file of a project. CSpell looks for the configuration in the cspell field of the package.json file.

{
  "name": "cspell-docs",
  "description": "Documentation for CSpell",
  // ...
  "cspell": {
    "version": "0.2",
    "useGitignore": true
  }
}