docs: add how-to guides for extra dictionaries and pre-commit setup

README.md

@@ -35,37 +35,12 @@ repos:
 
 <!-- x-release-please-end -->
 
-## 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
 

docs/file-or-folder-based-overrides.md

@@ -0,0 +1,48 @@
+# Use an Extra Dictionary Based on the Folder or Filename
+
+<!--- cspell:ignore esac getopts shopt --->
+
+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
+<!--- cspell:dictionaries bash --->
+```
+
+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)

docs/pre-commit-example-setup-for-french.md

@@ -0,0 +1,86 @@
+# Example `pre-commit` Setup for French
+
+<!--- cspell:ignore Voici nous avons française reforme --->
+
+## 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: <https://github.com/streetsidesoftware/cspell-dicts>.
+
+## 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)

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".

docs/use-dictionaries-from-cspell-dicts.md

@@ -0,0 +1,64 @@
+# Using Extra Dictionaries from `cspell-dicts` with `pre-commit`
+
+<!--- cspell:ignore reforme nlnl --->
+
+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: <https://github.com/streetsidesoftware/cspell-dicts>.
+
+## 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/<dictionary-name>/cspell-ext.json`
+
+For example: <https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/public-licenses/cspell-ext.json>
+
+## 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)