> For the complete documentation index, see [llms.txt](https://docs.vale.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vale.sh/topics/.vale.ini.md).

# .vale.ini

Learn how to configure Vale for your specific needs.

## [Creating a `.vale.ini` File](#creating-a-valeini-file)

After installing Vale, you’ll need to create a `.vale.ini` file in your project’s root directory. This file is used to configure Vale’s behavior and can be used to specify which rules to use, which directories to lint, and more.

The fastest way to get started with Vale is to use the [Config Generator](https://vale.sh/generator) to create a `.vale.ini` configuration file.

Once you have your local `.vale.ini` created in the directory of your choice, run `vale sync` from the command line to initialize it:

```bash
$ cd some-project
# You'll need to create this file
$ cat .vale.ini
...
$ vale sync
...
$ ls styles
...
$ vale README.md
```

Check out our [sample repository](https://github.com/vale-cli/vale-boilerplate) for a complete example of the required components of a Vale configuration.

## [File structure](#file-structure)

Vale’s configuration is read from a `.vale.ini` file. This file is [INI-formatted](https://ini.unknwon.io/docs/intro) and consists of multiple sections: core settings, format associations, and format-specific settings:

```ini
# Core settings appear at the top
# (the "global" section).

[formats]
# Format associations appear under
# the optional "formats" section.

[*]
# Format-specific settings appear
# under a user-provided "glob"
# pattern.
```

### [Core settings](#core-settings)

| Name                                    | Type       | Description                               |
| --------------------------------------- | ---------- | ----------------------------------------- |
| [StylesPath](/keys/stylespath.md)       | `string`   | Path to all Vale-related resources.       |
| [Packages](/keys/packages.md)           | `string[]` | List of packages to download and install. |
| [Vocab](/keys/vocabularies.md)          | `string[]` | List of vocabularies to load.             |
| [MinAlertLevel](/keys/minalertlevel.md) | `enum`     | Minimum alert level to display.           |
| [IgnoredScopes](/keys/ignoredscopes.md) | `enum`     | List of inline-level HTML tags to ignore. |
| [SkippedScopes](/keys/skippedscopes.md) | `enum`     | List of block-level HTML tags to ignore.  |

Core settings appear at the top of the file and apply to the application itself rather than a specific file format.

### [Format associations](#format-associations)

Format associations allow you to associate an “unknown” file extension with a supported one:

```ini
[formats]
txt = md
```

In the example above, we’re telling Vale to treat `.txt` files as Markdown files. Note that this is merely an extension-level substitution and is not a means of adding support for a new file type.

An association changes how Vale *reads* a file, not what it’s called. Sections still match the name on disk, so the example above needs a `[*.txt]` section—`[*.md]` won’t reach those files:

```ini
[formats]
txt = md

[*.{md,txt}]
BasedOnStyles = Vale
```

### [Format-specific settings](#format-specific-settings)

| Name                                            | Type        | Description                                     |
| ----------------------------------------------- | ----------- | ----------------------------------------------- |
| [BasedOnStyles](/keys/basedonstyles.md)         | `string[]`  | List of styles to load.                         |
| [BlockIgnores](/keys/blockignores.md)           | `string[]`  | List regexes to ignore in block-level content.  |
| [TokenIgnores](/keys/tokenignores.md)           | `string[]`  | List regexes to ignore in inline-level content. |
| [CommentDelimiters](/keys/commentdelimiters.md) | `string[2]` | Comment delimiters to replace at runtime.       |
| [Transform](/keys/transform.md)                 | `string`    | A version 1.0 XSL Transformation (XSLT).        |

Format-specific sections apply their settings only to files that match their associated glob pattern. For example, `[*]` matches all files while `[*.{md,txt}]` only matches files that end with either `.md` or `.txt.`

You can have as many format-specific sections as you’d like and settings defined under a more specific section will override those in `[*]`.

A pattern can name a path as well as an extension, so `[docs/src/*.md]` narrows a section to one part of the project:

```ini
[*.md]
BasedOnStyles = Vale

[docs/src/*.md]
TokenIgnores = (\[?-?@[^\s\]]+\]?)
```

A path pattern is matched against the file as Vale was asked for it, so write it relative to where you run Vale. The section above applies to `vale .`, `vale docs`, and `vale docs/src/page.md` run from the project root; it doesn’t match an absolute path such as `vale /home/me/project/docs/src/page.md`.

See [Globbing](/guides/globbing.md) for more information on how to use glob patterns with Vale.

## [Search process](#search-process)

{% hint style="warning" %}
You can override the default search process by manually specifying a path using the `--config` option or by defining a `VALE_CONFIG_PATH` environment variable.
{% endhint %}

![Vale looks for a configuration file in this order: the --config option, then VALE\_CONFIG\_PATH, then a .vale.ini searched for from the working directory upwards. The global configuration is always loaded as well, and is read last so it can override the others.](/files/P7ixPPuII3URk693ccMi)

Vale expects its configuration to be in a file named `.vale.ini` or `_vale.ini`. It’ll start looking for this file in the directory that the `vale` command was run from and then search up the file tree until it finds one.

If no ancestor of the current directory has a configuration file, Vale will use a global configuration file (see below).

## [Global configuration](#global-configuration)

In addition to project-specific configurations, Vale also supports a global configuration file. The expected location of the global configuration depends on your operating system:

| OS      | Search Locations                                   |
| ------- | -------------------------------------------------- |
| Windows | `%LOCALAPPDATA%\vale\.vale.ini`                    |
| macOS   | `$HOME/Library/Application Support/vale/.vale.ini` |
| Unix    | `$XDG_CONFIG_HOME/vale/.vale.ini`                  |

(Run the `vale ls-dirs` command to see the exact locations on your system.)

This is different from the other config-defining options (`--config`, `VALE_CONFIG_PATH`, etc.) in that it’s loaded in addition to, rather than instead of, any other configuration sources.

In other words, this config file is *always* loaded and is read after any other sources to allow for project-agnostic customization.

## [Cascading overrides](#cascading-overrides)

Vale’s configuration system supports using multiple configuration files at the same time. Typically, this is done in cases where you are contributing to a project that already has an established configuration but you want to make local changes.

For example, let’s say you’re working on a project that uses the following configuration:

```ini
StylesPath = styles
MinAlertLevel = error

[*.md]
BasedOnStyles = ProjectStyle
```

Now, let’s say you want to add the `write-good` style to your local configuration.

Create a global configuration file—for macOS, this would be `~/Library/Application Support/vale/.vale.ini` (see above for other OSes).

```ini
StylesPath = localpath

Packages = write-good

[*.md]
BasedOnStyles = write-good
```

Now, when you run Vale, it will show results from both the `ProjectStyle` and `write-good` styles locally.

You’ll notice that multi-valued settings (like `BasedOnStyles`) are merged together, while single-valued settings (like `MinAlertLevel`) are overridden.

This allows you to contribute to projects with established styles while still being able to make local changes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.vale.sh/topics/.vale.ini.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.