Skip to content

docs: improve parserPreset documentation with examples and options reference #4700

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
escapedcat merged 2 commits into from
Apr 7, 2026
+128 −6
Merged

docs: improve parserPreset documentation with examples and options reference #4700

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1dafe77
docs: improve parserPreset documentation with usage examples and opti…
Chessing234 Apr 4, 2026
9160e50
docs: address review feedback on parserPreset documentation
Chessing234 Apr 6, 2026
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
130 changes: 124 additions & 6 deletions docs/reference/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,13 +192,14 @@ More information can be found in the [Concepts – shareable config section](/co

## Parser presets

The parser preset used to parse commit messages can be configured.
Use ids resolvable by the node resolve algorithm.
The parser preset controls how commit messages are parsed into their component parts (type, scope, subject, body, footer, etc.). By default, commitlint does not ship with a parser preset — it falls back to [`conventional-changelog-angular`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) defaults. When you extend `@commitlint/config-conventional`, the [`conventional-changelog-conventionalcommits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits) preset is applied, which follows the [Conventional Commits specification](https://www.conventionalcommits.org/).

This means installed npm packages and local files can be used.
You can override the parser preset using the `parserPreset` property. It accepts:

:::tabs
== npm
- A **string** referencing an npm package or local file (resolved via Node's module resolution)
- An **object** with a `parserOpts` property for inline configuration

### Using an npm package

```sh
npm install --save-dev conventional-changelog-atom
Expand All @@ -212,7 +213,9 @@ export default {
};
```

== local
:::

### Using a local file

::: code-group

Expand All @@ -233,6 +236,121 @@ export default {

:::

### Inline `parserOpts`

You can also pass `parserOpts` directly without a separate file. This is useful for small adjustments like custom issue prefixes:

::: code-group

```js [commitlint.config.js]
export default {
parserPreset: {
parserOpts: {
issuePrefixes: ["PROJ-", "JIRA-"],
},
},
};
```

:::

### Common `parserOpts`

The parser is powered by [`conventional-commits-parser`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser). Common options include:

| Option | Description |
| ----------------------- | -------------------------------------------------------------------- |
| `headerPattern` | Regex to match the commit header (type, scope, subject) |
| `headerCorrespondence` | Array of field names matching the capture groups in headerPattern |
| `issuePrefixes` | Prefixes to match issue references (e.g. `["#", "PROJ-"]`) |
| `noteKeywords` | Keywords that mark footer notes (e.g. `["BREAKING CHANGE"]`) |
| `breakingHeaderPattern` | Regex to detect breaking changes in the header (e.g. the `!` marker) |

For the complete list of options, see the [`conventional-commits-parser` documentation](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#options).

### `presetConfig`

When using a preset like `conventional-changelog-conventionalcommits`, you can pass a `presetConfig` object to customize the preset's behavior without replacing the entire parser configuration. This is commonly used to set commit types that appear in generated changelogs:

::: code-group

```js [commitlint.config.js]
export default {
parserPreset: {
name: "conventional-changelog-conventionalcommits",
presetConfig: {
types: [
{ type: "feat", section: "Features" },
{ type: "fix", section: "Bug Fixes" },
{ type: "docs", section: "Documentation", hidden: false },
{ type: "chore", hidden: true },
],
},
},
};
```

:::

The available `presetConfig` options depend on the preset you are using. See the [`conventional-changelog-conventionalcommits` documentation](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits#preset-configuration) for details.

### Usage with semantic-release

If you use [semantic-release](https://github.com/semantic-release/semantic-release), both commitlint and semantic-release can share the same `conventional-changelog-conventionalcommits` preset. Keeping `parserOpts` and `presetConfig` consistent across both tools ensures that commits parsed during linting match what semantic-release uses for versioning and changelog generation:

::: code-group

```js [commitlint.config.js]
export default {
extends: ["@commitlint/config-conventional"],
parserPreset: {
name: "conventional-changelog-conventionalcommits",
presetConfig: {
types: [
{ type: "feat", section: "Features" },
{ type: "fix", section: "Bug Fixes" },
{ type: "docs", section: "Documentation", hidden: false },
],
},
},
};
```

:::

```js [.releaserc.js]
export default {
plugins: [
[
"@semantic-release/commit-analyzer",
{
preset: "conventionalcommits",
presetConfig: {
types: [
{ type: "feat", section: "Features" },
{ type: "fix", section: "Bug Fixes" },
{ type: "docs", section: "Documentation", hidden: false },
],
},
},
],
[
"@semantic-release/release-notes-generator",
{
preset: "conventionalcommits",
presetConfig: {
types: [
{ type: "feat", section: "Features" },
{ type: "fix", section: "Bug Fixes" },
{ type: "docs", section: "Documentation", hidden: false },
],
},
},
],
],
};
```

## Formatter

Commitlint can output the issues encountered in different formats, if necessary.
Expand Down
4 changes: 4 additions & 0 deletions docs/reference/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ These examples show common usages of how commitlint can be configured.

## Validate for issue/ticket numbers

This example uses inline `parserOpts` to configure the parser to recognize custom issue prefixes (e.g. `PROJ-123`). The `references-empty` rule then enforces that every commit references a ticket.

Comment on lines +7 to +8
Copy link
Copy Markdown

@qodo-code-review qodo-code-review Bot Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. Examples omit parserpreset name 📎 Requirement gap ≡ Correctness

The updated issue/ticket example explains inline parserOpts but still does not explicitly name
which parserPreset (e.g. conventional-changelog-conventionalcommits) the example assumes. This
leaves users guessing which preset package/name to configure for consistent parsing behavior.
Agent Prompt 
## Issue description
The examples page addition explains inline `parserOpts` but does not explicitly state which `parserPreset` users should configure for the example.

## Issue Context
Compliance requires examples docs to name the preset (e.g. `conventional-changelog-conventionalcommits`) and show how to reference it.

## Fix Focus Areas
- docs/reference/examples.md[7-8]
- docs/reference/examples.md[30-30]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

::: code-group

```jsonc [package.json]
Expand All @@ -25,6 +27,8 @@ These examples show common usages of how commitlint can be configured.

:::

See [Parser presets](/reference/configuration#parser-presets) for common `parserOpts` and configuration examples.

## Customizing Emojis and Alignment in VS Code

Some terminals have trouble correctly calculating the width of Unicode emojis, which can cause a missing space after the emoji, leading to misaligned text in the commit prompt.
Expand Down