Skip to content

docs: Improve Getting started page > 1. Create a configuration file section #7094

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Apr 1, 2025
Merged

docs: Improve Getting started page > 1. Create a configuration file section #7094

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
a5a289b
docs: Add full list of available config file names
tlindsay42 Mar 30, 2025
2355554
docs: Add JavaScript example
tlindsay42 Mar 30, 2025
9578106
docs: Add full list of available config file names
tlindsay42 Mar 31, 2025
9dd8fbb
docs: Add an ESM config file example
tlindsay42 Mar 31, 2025
243134a
docs: Add a package.json config example
tlindsay42 Mar 31, 2025
a828f93
docs: Update CommonJS example
tlindsay42 Mar 31, 2025
d3a0134
docs: Ignore formatting for mdx files
tlindsay42 Apr 1, 2025
539db49
docs: Fix jsdoc comment
tlindsay42 Apr 1, 2025
c23d60c
docs: Fix yaml object array element indent
tlindsay42 Apr 1, 2025
162ffe8
docs: Fix indent + use single quotes
tlindsay42 Apr 1, 2025
b4fb066
docs: Remove $schema where non-applicable
tlindsay42 Apr 1, 2025
6f3dc82
docs: Remove unnecessary 'use strict' for ESM
tlindsay42 Apr 1, 2025
7e05a98
Merge branch 'main' into docs-getting-started-config
Jason3S Apr 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions website/.prettierignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@
coverage
node_modules
**/auto_*
**/*.mdx
117 changes: 114 additions & 3 deletions website/docs/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,60 @@ Steps:

## 1. Create a configuration file.

CSpell can use JSON, Yaml, and JavaScript files for configuration. It automatically searches for one of the following: `cspell.json`, `cspell.config.yaml`, `cspell.config.cjs`.
CSpell can use JSON, Yaml, and JavaScript files for configuration. It automatically searches for one of the following:

{/** @see https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/lib/Settings/Controller/configLoader/configLocations.ts */}

- `package.json`
- `.cspell.json`
- `cspell.json`
- `.cSpell.json`
- `cSpell.json`
- `.cspell.jsonc`
- `cspell.jsonc`
- `.cspell.yaml`
- `cspell.yaml`
- `.cspell.yml`
- `cspell.yml`
- `.cspell.config.json`
- `cspell.config.json`
- `.cspell.config.jsonc`
- `cspell.config.jsonc`
- `.cspell.config.yaml`
- `cspell.config.yaml`
- `.cspell.config.yml`
- `cspell.config.yml`
- `.cspell.config.mjs`
- `cspell.config.mjs`
- `.cspell.config.cjs`
- `cspell.config.cjs`
- `.cspell.config.js`
- `cspell.config.js`
- `.config/.cspell.json`
- `.config/cspell.json`
- `.config/.cSpell.json`
- `.config/cSpell.json`
- `.config/.cspell.jsonc`
- `.config/cspell.jsonc`
- `.config/cspell.yaml`
- `.config/cspell.yml`
- `.config/.cspell.config.json`
- `.config/cspell.config.json`
- `.config/.cspell.config.jsonc`
- `.config/cspell.config.jsonc`
- `.config/.cspell.config.yaml`
- `.config/cspell.config.yaml`
- `.config/.cspell.config.yml`
- `.config/cspell.config.yml`
- `.config/.cspell.config.mjs`
- `.config/cspell.config.mjs`
- `.config/.cspell.config.cjs`
- `.config/cspell.config.cjs`
- `.config/.cspell.config.js`
- `.config/cspell.config.js`
- `.vscode/.cspell.json`
- `.vscode/cSpell.json`
- `.vscode/cspell.json`

For now choose to use either JSON or Yaml. Below are examples of each that include a custom dictionary definition. Both of them are equivalent. If you have both, CSpell will look for the `.json` file first.

Expand Down Expand Up @@ -75,15 +128,73 @@ For now choose to use either JSON or Yaml. Below are examples of each that inclu
version: '0.2'
dictionaryDefinitions:
- name: project-words
path: './project-words.txt'
addWords: true
path: './project-words.txt'
addWords: true
dictionaries:
- project-words
ignorePaths:
- 'node_modules'
- '/project-words.txt'
```
</TabItem>
<TabItem value="esm" label="cspell.config.mjs">
```javascript
import { defineConfig } from 'cspell';

export default defineConfig({
version: '0.2',
dictionaryDefinitions: [
{
name: 'project-words',
path: './project-words.txt',
addWords: true,
},
],
dictionaries: ['project-words'],
ignorePaths: ['node_modules', '/project-words.txt'],
});
```
</TabItem>
<TabItem value="commonjs" label="cspell.config.cjs">
```javascript
'use strict';

const { defineConfig } = require('@cspell/cspell-types');

module.exports = defineConfig({
version: '0.2',
dictionaryDefinitions: [
{
name: 'project-words',
path: './project-words.txt',
addWords: true,
}
],
dictionaries: ['project-words'],
ignorePaths: ['node_modules', '/project-words.txt'],
});
```
</TabItem>
<TabItem value="package.json" label="package.json">
```json
{
...
"cspell": {
"version": "0.2",
"dictionaryDefinitions": [
{
"name": "project-words",
"path": "./project-words.txt",
"addWords": true
}
],
"dictionaries": ["project-words"],
"ignorePaths": ["node_modules", "/project-words.txt"]
}
}
```
</TabItem>

</Tabs>

These configuration files do three things:
Expand Down
Loading