diff --git a/README.md b/README.md index 8b8b1fd..9612efc 100644 --- a/README.md +++ b/README.md @@ -35,37 +35,12 @@ repos: -## Setup Custom Dictionary +## How-To Guides and Configuration Examples -To use a custom dictionary with the `pre-commit` hook, create either a `cspell.config.yaml` or `cspell.json` file in your project's root directory. - -`cspell.config.yaml` - -```yaml -dictionaryDefinitions: - - name: myWords - path: ./path/to/cSpell_dict.txt - addWords: true -dictionaries: - - myWords -``` - -`cSpell.json` - -```json -{ - "dictionaryDefinitions": [ - { - "name": "myWords", - "path": "./path/to/cSpell_dict.txt", - "addWords": true - } - ], - "dictionaries": ["myWords"] -} -``` - -If you installed the [Code Spell Checker extension](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) for VS Code, this can be done automatically from the command palette by running "Spell: Create a CSpell configuration file". +- [Use Dictionaries from `cspell-dicts`](docs/use-dictionaries-from-cspell-dicts.md) +- [Use a Custom Dictionary](docs/use-a-custom-dictionary.md) +- [Use an Extra Dictionary Based on the Folder or Filename](docs/file-or-folder-based-overrides.md) +- [Example `pre-commit` Setup for French](docs/pre-commit-example-setup-for-french.md) ## Install from GitHub diff --git a/docs/file-or-folder-based-overrides.md b/docs/file-or-folder-based-overrides.md new file mode 100644 index 0000000..67006c7 --- /dev/null +++ b/docs/file-or-folder-based-overrides.md @@ -0,0 +1,48 @@ +# Use an Extra Dictionary Based on the Folder or Filename + + + +By default, the [Bash dictionary](https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/bash/cspell-ext.json) is only applied to files of type `shellscript`. This example shows how to enable the Bash dictionary for specific folders or filenames using `overrides` in your cspell configuration. + +> **Note:** `pre-commit` uses the same cspell configuration, so `overrides` work identically when running cspell via `pre-commit`. + +## Example: Enable the Bash Dictionary for Markdown Files + +Consider a project where Markdown files contain Bash code blocks. Words like `esac`, `getopts`, and `shopt` will be flagged as unknown because the Bash dictionary is not active for `.md` files by default. + +### Configuration + +Add an `overrides` section to your `cspell.json`: + +```json +{ + "overrides": [ + { + "filename": ["**/bash_docs/**/*.md", "**/bash_examples/**"], + "dictionaries": ["bash"] + } + ], + "version": "0.2" +} +``` + +With this configuration: + +- `docs/bash_docs/pipes.md` — **will** use the Bash dictionary (no errors for bash words) +- `docs/about.md` — will **not** use the Bash dictionary (bash words flagged as errors) + +### Alternative: Enable the Dictionary in a Single File + +For a single file, use an inline directive instead of configuring `overrides`: + +```markdown + +``` + +This is useful when only one or two files need the extra dictionary. + +## See Also + +- [Use Dictionaries from `cspell-dicts`](use-dictionaries-from-cspell-dicts.md) +- [Use a Custom Dictionary](use-a-custom-dictionary.md) +- [Setup pre-commit Hook](../README.md#setup-pre-commit-hook) diff --git a/docs/pre-commit-example-setup-for-french.md b/docs/pre-commit-example-setup-for-french.md new file mode 100644 index 0000000..bee94e5 --- /dev/null +++ b/docs/pre-commit-example-setup-for-french.md @@ -0,0 +1,86 @@ +# Example `pre-commit` Setup for French + + + +## Configuration + +### `.pre-commit-config.yaml` + +Add French dictionary packages using `additional_dependencies`: + +```yaml +# .pre-commit-config.yaml +repos: + - repo: https://github.com/streetsidesoftware/cspell-cli + rev: v10.0.1 + hooks: + - id: cspell + additional_dependencies: + - '@cspell/dict-fr-fr' + - '@cspell/dict-fr-reforme' +``` + +For a complete list of available dictionaries, see: . + +## Using French as the Default Locale + +Use a `cspell.json` such as: + +```json +{ + "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json", + "import": [ + "@cspell/dict-fr-fr/cspell-ext.json", + "@cspell/dict-fr-reforme/cspell-ext.json" + ], + "language": "fr", + "version": "0.2" +} +``` + +A file `mots-française.md` containing: + +```markdown +# Testing French in Markdown + +## Les mots + +Voici, nous avons les mots française. +``` + +With this configuration, `mots-française.md` will not show spelling errors. + +## Applying French to Specific Files + +To apply French dictionaries only to `.md` files while leaving other file types checked in English: + +```json +{ + "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json", + "import": [ + "@cspell/dict-fr-fr/cspell-ext.json", + "@cspell/dict-fr-reforme/cspell-ext.json" + ], + "overrides": [ + { + "filename": "**/*.md", + "language": "fr,fr-fr,fr-90" + } + ], + "version": "0.2" +} +``` + +With this configuration: + +``` +project/ +├── mots-française.md ← uses French dictionary (no errors) +└── mots-française.err ← uses English dictionary (French words flagged) +``` + +## See Also + +- [Use Dictionaries from `cspell-dicts`](use-dictionaries-from-cspell-dicts.md) +- [Use an Extra Dictionary Based on the Folder or Filename](file-or-folder-based-overrides.md) +- [Setup pre-commit Hook](../README.md#setup-pre-commit-hook) diff --git a/docs/use-a-custom-dictionary.md b/docs/use-a-custom-dictionary.md new file mode 100644 index 0000000..7443416 --- /dev/null +++ b/docs/use-a-custom-dictionary.md @@ -0,0 +1,31 @@ +# Use a Custom Dictionary + +To use a custom dictionary with the `pre-commit` hook, create either a `cspell.config.yaml` or `cspell.json` file in your project's root directory. + +`cspell.config.yaml` + +```yaml +dictionaryDefinitions: + - name: myWords + path: ./path/to/cSpell_dict.txt + addWords: true +dictionaries: + - myWords +``` + +`cspell.json` + +```json +{ + "dictionaryDefinitions": [ + { + "name": "myWords", + "path": "./path/to/cSpell_dict.txt", + "addWords": true + } + ], + "dictionaries": ["myWords"] +} +``` + +If you installed the [Code Spell Checker extension](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) for VS Code, this can be done automatically from the command palette by running "Spell: Create a cSpell configuration file". diff --git a/docs/use-dictionaries-from-cspell-dicts.md b/docs/use-dictionaries-from-cspell-dicts.md new file mode 100644 index 0000000..f6c2fc8 --- /dev/null +++ b/docs/use-dictionaries-from-cspell-dicts.md @@ -0,0 +1,64 @@ +# Using Extra Dictionaries from `cspell-dicts` with `pre-commit` + + + +Most dictionaries bundled with `cspell` are active by default in appropriate contexts (e.g., the public-licenses dictionary is enabled automatically). Non-English language dictionaries are not enabled by default and must be explicitly added. + +To use a language dictionary: + +1. Add it as an `additional_dependency` in `.pre-commit-config.yaml` +2. Import it in `cspell.json` + +For a complete list of available dictionaries, see: . + +## Checking a Dictionary's Default Context + +View the `cspell-ext.json` for any dictionary to see when it is applied by default: + +`https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries//cspell-ext.json` + +For example: + +## Example: Adding a Dutch Dictionary + +### `.pre-commit-config.yaml` + +```yaml +# .pre-commit-config.yaml +repos: + - repo: https://github.com/streetsidesoftware/cspell-cli + rev: v10.0.1 + hooks: + - id: cspell + additional_dependencies: + - '@cspell/dict-nl-nl' +``` + +### `cspell.json` + +To make the `nl-nl` dictionary available: + +```json +{ + "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json", + "import": ["@cspell/dict-nl-nl/cspell-ext.json"], + "version": "0.2" +} +``` + +To also set Dutch as the default locale: + +```json +{ + "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json", + "import": ["@cspell/dict-nl-nl/cspell-ext.json"], + "language": "nl-nl", + "version": "0.2" +} +``` + +## See Also + +- [Example `pre-commit` Setup for French](pre-commit-example-setup-for-french.md) +- [Use an Extra Dictionary Based on the Folder or Filename](file-or-folder-based-overrides.md) +- [Setup pre-commit Hook](../README.md#setup-pre-commit-hook)