diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 26869378e6..b8c3f856ea 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -38,7 +38,7 @@ Please consider these guidelines when filing a pull request:
_ What you added
_ What you removed
-## Coding Rules
+### Coding Rules
To keep the code base of commitlint neat and tidy the following rules apply to every change
@@ -48,7 +48,7 @@ To keep the code base of commitlint neat and tidy the following rules apply to e
- Favor micro library over swiss army knives (rimraf, ncp vs. fs-extra)
- Be awesome
-## Commit Rules
+### Commit Rules
To help everyone with understanding the commit history of commitlint the following commit rules are enforced.
To make your life easier commitlint is commitizen-friendly and provides the npm run-script `commit`.
@@ -61,17 +61,43 @@ To make your life easier commitlint is commitizen-friendly and provides the npm
- maximum of 100 characters
- message format of `$type($scope): $message`
-## Testing
+### Environment setup
-From the project root directory, use the following commands to run the test suite
+This project uses `yarn`, so be sure that it is available in your shell environment.
+
+After cloning the repo run
```sh
-yarn clean
yarn install
+```
+
+### Testing
+
+From the project root directory, use the following commands to run the test suite
+
+```sh
yarn build
yarn test
```
+### Documentation updates
+
+Documentation uses `vitepress`.
+To run and edit the documentation locally run:
+
+```sh
+yarn docs-dev
+```
+
+To have a preview of the deployed doc run:
+
+```sh
+yarn docs-build
+yarn docs-serve
+```
+
+For more information refer to [vitepress documentation](https://vitepress.dev).
+
## Package dependency overview
![commitlint-dependencies](https://user-images.githubusercontent.com/4248851/58385093-34b79780-7feb-11e9-8f27-bffc4aca3eba.png)
diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml
new file mode 100644
index 0000000000..0f12591899
--- /dev/null
+++ b/.github/workflows/docs-deploy.yml
@@ -0,0 +1,61 @@
+name: Deploy docs site to Pages
+
+on:
+ push:
+ branches: [main]
+
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+concurrency:
+ group: pages
+ cancel-in-progress: false
+
+jobs:
+ # Build job
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: 18
+ cache: yarn
+
+ - name: Setup Pages
+ uses: actions/configure-pages@v4
+
+ - name: Install dependencies
+ run: yarn install
+
+ - name: Build with VitePress
+ run: |
+ yarn docs-build
+ touch ./docs/.vitepress/dist/.nojekyll
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: ./docs/.vitepress/dist
+
+ # Deployment job
+ deploy:
+ environment:
+ name: docs
+ url: ${{ steps.deployment.outputs.page_url }}
+ needs: build
+ runs-on: ubuntu-latest
+ name: Deploy
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index c74ceef1f1..3074bd3428 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,5 +13,8 @@ package.json.lerna_backup
tsconfig.tsbuildinfo
coverage
+docs/.vitepress/dist
+docs/.vitepress/cache
+
# For testing nested workspaces does not have the package's dependencies name in the scope
!**/config-lerna-scopes/fixtures/nested-workspaces/**/node_modules
diff --git a/@commitlint/cli/README.md b/@commitlint/cli/README.md
index 75f3b0fa4c..d05f13f175 100644
--- a/@commitlint/cli/README.md
+++ b/@commitlint/cli/README.md
@@ -1,16 +1,11 @@
-> Lint commit messages
+# @commitlint/cli
-
+
-# @commitlint/cli
-
-## Getting started
+Lint commit messages
-```
-npm install --save-dev @commitlint/cli @commitlint/config-angular
-echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
-```
+## Documentation
-Consult [docs/cli](https://conventional-changelog.github.io/commitlint/#/reference-cli) for comprehensive documentation.
+Consult [CLI reference](https://commitlint.js.org/reference/cli) for comprehensive documentation.
diff --git a/@commitlint/cli/src/cli.ts b/@commitlint/cli/src/cli.ts
index 8c10e7a1ba..367a5186d5 100644
--- a/@commitlint/cli/src/cli.ts
+++ b/@commitlint/cli/src/cli.ts
@@ -306,7 +306,7 @@ async function main(args: MainArgs): Promise {
name: 'empty-rules',
message: [
'Please add rules to your `commitlint.config.js`',
- ' - Getting started guide: https://commitlint.js.org/#/?id=getting-started',
+ ' - Getting started guide: https://commitlint.js.org/guides/getting-started',
' - Example config: https://github.com/conventional-changelog/commitlint/blob/master/%40commitlint/config-conventional/src/index.ts',
].join('\n'),
},
diff --git a/@commitlint/config-angular/README.md b/@commitlint/config-angular/README.md
index 82e558702f..43d0d7731f 100644
--- a/@commitlint/config-angular/README.md
+++ b/@commitlint/config-angular/README.md
@@ -1,7 +1,7 @@
-> Lint your commits, angular-style
-
# @commitlint/config-angular
+Lint your commits, angular-style
+
Shareable `commitlint` config enforcing the [Angular commit convention](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit).
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
@@ -9,7 +9,7 @@ Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
```sh
npm install --save-dev @commitlint/config-angular @commitlint/cli
-echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
+echo "export default {extends: ['@commitlint/config-angular']};" > commitlint.config.js
```
## Rules
@@ -17,7 +17,7 @@ echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.
### Problems
The following rules are considered problems for `@commitlint/config-angular` and will yield a non-zero exit code when not met.
-Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
+Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
#### type-enum
diff --git a/@commitlint/config-conventional/README.md b/@commitlint/config-conventional/README.md
index 966679eff0..f83e2028e7 100644
--- a/@commitlint/config-conventional/README.md
+++ b/@commitlint/config-conventional/README.md
@@ -1,7 +1,7 @@
-> Lint your conventional commits
-
# @commitlint/config-conventional
+Lint your conventional commits
+
Shareable `commitlint` config enforcing [conventional commits](https://conventionalcommits.org/).
Use with [@commitlint/cli](https://npm.im/@commitlint/cli) and [@commitlint/prompt-cli](https://npm.im/@commitlint/prompt-cli).
@@ -9,7 +9,7 @@ Use with [@commitlint/cli](https://npm.im/@commitlint/cli) and [@commitlint/prom
```sh
npm install --save-dev @commitlint/config-conventional @commitlint/cli
-echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
+echo "export default {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
```
## Rules
@@ -18,7 +18,7 @@ echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commit
The following rules are considered problems for `@commitlint/config-conventional` and will yield a non-zero exit code when not met.
-Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
+Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
#### type-enum
diff --git a/@commitlint/config-lerna-scopes/readme.md b/@commitlint/config-lerna-scopes/readme.md
index 41ab597339..ef818933d5 100644
--- a/@commitlint/config-lerna-scopes/readme.md
+++ b/@commitlint/config-lerna-scopes/readme.md
@@ -1,20 +1,20 @@
-> Lint your lerna project commits
-
# @commitlint/config-lerna-scopes
+Lint your lerna project commits
+
Shareable `commitlint` config enforcing lerna package and workspace names as scopes.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
## Getting started
-```
+```sh
npm install --save-dev @commitlint/config-lerna-scopes @commitlint/cli
-echo "module.exports = {extends: ['@commitlint/config-lerna-scopes']};" > commitlint.config.js
+echo "export default {extends: ['@commitlint/config-lerna-scopes']};" > commitlint.config.js
```
## Examples
-```
+```text
❯ cat commitlint.config.js
{
extends: ['@commitlint/config-lerna-scopes']
@@ -41,4 +41,4 @@ packages
✔ found 0 problems, 0 warnings
```
-Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
+Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
diff --git a/@commitlint/config-nx-scopes/readme.md b/@commitlint/config-nx-scopes/readme.md
index 00027dd92e..a8fba5c400 100644
--- a/@commitlint/config-nx-scopes/readme.md
+++ b/@commitlint/config-nx-scopes/readme.md
@@ -1,7 +1,7 @@
-> Lint your nx project commits
-
# @commitlint/config-nx-scopes
+Lint your nx project commits
+
Shareable `commitlint` config enforcing nx project and workspace names as scopes.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
@@ -98,4 +98,4 @@ packages
✔ found 0 problems, 0 warnings
```
-Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
+Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
diff --git a/@commitlint/config-patternplate/README.md b/@commitlint/config-patternplate/README.md
index 708c933be8..66b46901b7 100644
--- a/@commitlint/config-patternplate/README.md
+++ b/@commitlint/config-patternplate/README.md
@@ -1,7 +1,7 @@
-> Lint your commits, patternplate-style
-
# @commitlint/config-patternplate
+Lint your commits, patternplate-style
+
Shareable `commitlint` config enforcing the patternplate commit convention.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
@@ -27,4 +27,4 @@ The following rules are considered problems for `@commitlint/config-patternplate
- **rule**: `always`
- **value**: determined based on pattern tree. `system` and all pattern ids present in `patterns` are allowed
-Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
+Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
diff --git a/@commitlint/config-pnpm-scopes/readme.md b/@commitlint/config-pnpm-scopes/readme.md
index 9e4316163d..45d65af9dc 100644
--- a/@commitlint/config-pnpm-scopes/readme.md
+++ b/@commitlint/config-pnpm-scopes/readme.md
@@ -1,7 +1,7 @@
-> Lint your pnpm workspaces project commits
-
# @commitlint/config-pnpm-scopes
+Lint your pnpm workspaces project commits
+
Shareable `commitlint` config enforcing pnpm workspaces names as scopes.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
@@ -41,4 +41,4 @@ packages
✔ found 0 problems, 0 warnings
```
-Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
+Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
diff --git a/@commitlint/config-rush-scopes/readme.md b/@commitlint/config-rush-scopes/readme.md
index c6199783ce..505b681720 100644
--- a/@commitlint/config-rush-scopes/readme.md
+++ b/@commitlint/config-rush-scopes/readme.md
@@ -1,20 +1,20 @@
-> Lint your rush project commits
-
# @commitlint/config-rush-scopes
+Lint your rush project commits
+
Shareable `commitlint` config enforcing rush package and workspace names as scopes.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
## Getting started
-```
+```sh
npm install --save-dev @commitlint/config-rush-scopes @commitlint/cli
-echo "module.exports = {extends: ['@commitlint/config-rush-scopes']};" > commitlint.config.js
+echo "export default {extends: ['@commitlint/config-rush-scopes']};" > commitlint.config.js
```
## Examples
-```
+```text
❯ cat commitlint.config.js
{
extends: ['@commitlint/config-rush-scopes']
@@ -41,4 +41,4 @@ packages
✔ found 0 problems, 0 warnings
```
-Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
+Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
diff --git a/@commitlint/cz-commitlint/README.md b/@commitlint/cz-commitlint/README.md
index 6af8498fc0..4f01db7e8e 100644
--- a/@commitlint/cz-commitlint/README.md
+++ b/@commitlint/cz-commitlint/README.md
@@ -58,4 +58,4 @@ yarn commit
## Related
-- [Commitlint Reference Prompt](https://commitlint.js.org/#/reference-prompt) - How to customize prompt information by setting commitlint.config.js
+- [Commitlint Reference Prompt](https://commitlint.js.org/reference/prompt) - How to customize prompt information by setting commitlint.config.js
diff --git a/@commitlint/format/README.md b/@commitlint/format/README.md
index b815fb89fd..66de357636 100644
--- a/@commitlint/format/README.md
+++ b/@commitlint/format/README.md
@@ -1,65 +1,15 @@
-> Format commitlint reports
-
# @commitlint/format
+Format commitlint reports
+
## Getting started
```shell
npm install --save @commitlint/format
```
-## Example
-
-```js
-const format = require('@commitlint/format').default;
+## Documentation
-const output = format(
- {
- valid: false,
- errorCount: 1,
- warningCount: 1,
- results: [
- {
- valid: false,
- input: 'some: commit message',
- errors: [
- {
- valid: false,
- level: 2,
- name: 'some-error',
- message: 'This will show up red as it has level 2',
- },
- ],
- warnings: [
- {
- valid: true,
- level: 0,
- name: 'some-hint',
- message: 'This will not show up as it has level 0',
- },
- {
- valid: false,
- level: 1,
- name: 'some-warning',
- message: 'This will show up yellow as it has level 1',
- },
- ],
- },
- ],
- },
- {
- color: false,
- }
-);
-
-process.stdout.write(output);
-
-/* => [
- '✖ This will show up red as it has level 2 [some-error]',
- ' This will not show up as it has level 0 [some-hint]',
- '⚠ This will show up yellow as it has level 1 [some-warning]',
- '✖ found 1 problems, 2 warnings'
-] */
-```
+Consult [API docs](https://commitlint.js.org/api/format) for comprehensive documentation.
-Consult [docs/api](https://conventional-changelog.github.io/commitlint/#/reference-api) for comprehensive documentation.
+Documentation generated from [`docs` folder](../../docs/api/format.md).
diff --git a/@commitlint/lint/README.md b/@commitlint/lint/README.md
index a863241afd..7849251ff7 100644
--- a/@commitlint/lint/README.md
+++ b/@commitlint/lint/README.md
@@ -1,35 +1,15 @@
-> Lint a string against commitlint rules
-
# @commitlint/lint
+Lint a string against commitlint rules
+
## Getting started
```shell
npm install --save @commitlint/lint
```
-## Example
-
-```js
-const lint = require('@commitlint/lint').default;
+## Documentation
-lint('foo: bar', {'type-enum': [1, 'always', ['foo']]}).then((report) =>
- console.log(report)
-);
-// => { valid: true, errors: [], warnings: [] }
-
-lint('foo: bar', {'type-enum': [1, 'always', ['bar']]}).then((report) =>
- console.log(report)
-);
-/* =>
- { valid: true,
- errors: [],
- warnings:
- [ { level: 1,
- valid: false,
- name: 'type-enum',
- message: 'type must be one of [bar]' } ] }
- */
-```
+Consult [API docs](https://commitlint.js.org/api/lint) for comprehensive documentation.
-Consult [docs/api](https://conventional-changelog.github.io/commitlint/#/reference-api) for comprehensive documentation.
+Documentation generated from [`docs` folder](../../docs/api/format.md).
diff --git a/@commitlint/load/README.md b/@commitlint/load/README.md
index 9488693304..a65da640c0 100644
--- a/@commitlint/load/README.md
+++ b/@commitlint/load/README.md
@@ -1,20 +1,15 @@
-> Load shared commitlint configuration
-
# @commitlint/load
+Load shared commitlint configuration
+
## Getting started
```shell
npm install --save-dev @commitlint/load
```
-## Example
+## Documentation
-```js
-const load = require('@commitlint/load').default;
-
-load({extends: ['./package']}).then((config) => console.log(config));
-// => { extends: ['./package', './package-b'], rules: {} }
-```
+Consult [API docs](https://commitlint.js.org/api/load) for comprehensive documentation.
-Consult [docs/api](https://conventional-changelog.github.io/commitlint/#/reference-api) for comprehensive documentation.
+Documentation generated from [`docs` folder](../../docs/api/format.md).
diff --git a/@commitlint/prompt-cli/README.md b/@commitlint/prompt-cli/README.md
index 82273bc612..49457f8196 100644
--- a/@commitlint/prompt-cli/README.md
+++ b/@commitlint/prompt-cli/README.md
@@ -1,17 +1,17 @@
-> commit prompt using commitlint.config.js
-
# @commitlint/prompt-cli
+commit prompt using commitlint.config.js
+
## Getting started
-```bash
-npm install --g @commitlint/prompt-cli @commitlint/config-angular
-echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
+```sh
+npm install -g @commitlint/prompt-cli @commitlint/config-angular
+echo "export default {extends: ['@commitlint/config-angular']};" > commitlint.config.js
```
-```bash
+```sh
git add .
commit
```
-A full usage guide is available at [docs/prompt](https://conventional-changelog.github.io/commitlint/#/guides-use-prompt).
+A full usage guide is available at [docs/prompt](https://commitlint.js.org/guides/use-prompt).
diff --git a/@commitlint/prompt/README.md b/@commitlint/prompt/README.md
index 261d09f10f..64090b4001 100644
--- a/@commitlint/prompt/README.md
+++ b/@commitlint/prompt/README.md
@@ -1,10 +1,10 @@
-> commitizen adapter using commitlint.config.js
-
# @commitlint/prompt
+commitizen adapter using commitlint.config.js
+
This is the library and commitizen adapter version of commitlint prompt.
A ready-to-use cli version is available at [@commitlint/prompt-cli](../prompt-cli).
-Learn how to use it at [docs/prompt](https://conventional-changelog.github.io/commitlint/#/guides-use-prompt).
+Learn how to use it in this [guide](https://commitlint.js.org/guides/use-prompt).
## Getting started
diff --git a/@commitlint/read/README.md b/@commitlint/read/README.md
index acb77a6bb9..3d8c06e1a5 100644
--- a/@commitlint/read/README.md
+++ b/@commitlint/read/README.md
@@ -1,25 +1,15 @@
-> Read commit messages from a specified range or last edit
-
# @commitlint/read
+Read commit messages from a specified range or last edit
+
## Getting started
```shell
npm install --save @commitlint/read
```
-## Example
-
-```js
-const read = require('@commitlint/read').default;
+## Documentation
-// Read last edited commit message
-read({edit: true}).then((messages) => console.log(messages));
-// => ['I did something\n\n']
-
-// Read from the third to second commit message from HEAD
-read({from: 'HEAD~2', to: 'HEAD~1'}).then((messages) => console.log(messages));
-// => ['Initial commit\n\n']
-```
+Consult [API docs](https://commitlint.js.org/api/read) for comprehensive documentation.
-Consult [docs/api](https://conventional-changelog.github.io/commitlint/#/reference-api) for comprehensive documentation.
+Documentation generated from [`docs` folder](../../docs/api/read.md).
diff --git a/@commitlint/rules/src/index.test.ts b/@commitlint/rules/src/index.test.ts
index cd9c13716c..822fd53c73 100644
--- a/@commitlint/rules/src/index.test.ts
+++ b/@commitlint/rules/src/index.test.ts
@@ -22,13 +22,13 @@ test('rules export functions', () => {
test('all rules are present in documentation', () => {
const file = fs.readFileSync(
- path.join(__dirname, '../../../docs/reference-rules.md'),
+ path.join(__dirname, '../../../docs/reference/rules.md'),
'utf-8'
);
const results = file
.split(/(\n|\r)/)
- .filter((s) => s.startsWith('####') && !s.includes('`deprecated`'))
- .map((s) => s.replace('#### ', ''));
+ .filter((s) => s.startsWith('##') && !s.includes('`deprecated`'))
+ .map((s) => s.replace('## ', ''));
expect(Object.keys(rules)).toEqual(expect.arrayContaining(results));
});
diff --git a/README.md b/README.md
index 1b3c8367cd..bb7852ec85 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# [Get Started](https://conventional-changelog.github.io/commitlint/#/?id=getting-started) | [Website](https://conventional-changelog.github.io/commitlint)
+# [Get Started](https://commitlint.js.org/guides/getting-started) | [Website](https://commitlint.js.org)
> Lint commit messages
@@ -86,8 +86,8 @@ These can be modified by [your own configuration](#config).
## Getting started
-- [Local setup](https://conventional-changelog.github.io/commitlint/#/guides-local-setup) - Lint messages on commit with husky
-- [CI setup](https://conventional-changelog.github.io/commitlint/#/guides-ci-setup) - Lint messages during CI builds
+- [Local setup](https://commitlint.js.org/guides/local-setup) - Lint messages on commit with husky
+- [CI setup](https://commitlint.js.org/guides/ci-setup) - Lint messages during CI builds
## CLI
@@ -114,7 +114,7 @@ These can be modified by [your own configuration](#config).
- `commitlint.config.cts`
- `commitlint` field in `package.json`
- Packages: [cli](./@commitlint/cli), [core](./@commitlint/core)
-- See [Rules](./docs/reference-rules.md) for a complete list of possible rules
+- See [Rules](./docs/reference/rules.md) for a complete list of possible rules
- An example configuration can be found at [@commitlint/config-conventional](./@commitlint/config-conventional/src/index.ts)
## Shared configuration
@@ -144,7 +144,7 @@ Check the [main website](https://commitlint.js.org/).
- [lint](./@commitlint/lint) - Lint a string against commitlint rules
- [load](./@commitlint/load) - Load shared commitlint configuration
- [read](./@commitlint/read) - Read commit messages from a specified range or last edit
-- See [API](./docs/reference-api.md) for a complete list of methods and examples
+- See [API](./docs/api) for a complete list of methods and examples
## Tools
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
new file mode 100644
index 0000000000..41e98b80b8
--- /dev/null
+++ b/docs/.vitepress/config.ts
@@ -0,0 +1,98 @@
+import {defineConfig} from 'vitepress';
+import {tabsMarkdownPlugin} from 'vitepress-plugin-tabs';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+ title: 'commitlint',
+ description: 'Lint commit messages',
+
+ head: [['link', {rel: 'icon', type: 'image/png', href: '/assets/icon.png'}]],
+
+ themeConfig: {
+ // https://vitepress.dev/reference/default-theme-config
+ logo: '/assets/icon.png',
+
+ nav: [
+ {text: 'Home', link: '/'},
+ {text: 'Guides', link: '/guides/getting-started'},
+ {text: 'Reference', link: '/reference/configuration'},
+ ],
+
+ sidebar: [
+ {
+ text: 'Guides',
+ base: '/guides',
+ items: [
+ {text: 'Getting started', link: '/getting-started'},
+ {text: 'Local setup', link: '/local-setup'},
+ {text: 'CI setup', link: '/ci-setup'},
+ {text: 'Use prompt', link: '/use-prompt'},
+ ],
+ },
+ {
+ text: 'Reference',
+ base: '/reference',
+ items: [
+ {text: 'CLI', link: '/cli'},
+ {text: 'Configuration', link: '/configuration'},
+ {text: 'Rules configuration', link: '/rules-configuration'},
+ {text: 'Rules', link: '/rules'},
+ {text: 'Plugins', link: '/plugins'},
+ {text: 'Prompt', link: '/prompt'},
+ {text: 'Examples', link: '/examples'},
+ {text: 'Community projects', link: '/community-projects'},
+ ],
+ },
+ {
+ text: 'API',
+ base: '/api',
+ collapsed: true,
+ items: [
+ {text: '@commitlint/load', link: '/load'},
+ {text: '@commitlint/read', link: '/read'},
+ {text: '@commitlint/lint', link: '/lint'},
+ {text: '@commitlint/format', link: '/format'},
+ ],
+ },
+ {
+ text: 'Concepts',
+ base: '/concepts',
+ collapsed: true,
+ items: [
+ {text: 'Commit-conventions', link: '/commit-conventions'},
+ {text: 'Shareable config', link: '/shareable-config'},
+ ],
+ },
+ {
+ text: 'Support',
+ base: '/support',
+ collapsed: true,
+ items: [
+ {text: 'Releases', link: '/releases'},
+ {text: 'Upgrade commitlint', link: '/upgrade'},
+ ],
+ },
+ {
+ text: 'Attributions',
+ link: '/attributions',
+ },
+ ],
+
+ socialLinks: [
+ {
+ icon: 'github',
+ link: 'https://github.com/conventional-changelog/commitlint',
+ },
+ ],
+
+ search: {
+ provider: 'local',
+ },
+ },
+
+ markdown: {
+ config(md) {
+ md.use(tabsMarkdownPlugin);
+ },
+ },
+});
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
new file mode 100644
index 0000000000..c1b1900e45
--- /dev/null
+++ b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,11 @@
+// .vitepress/theme/index.ts
+import type {Theme} from 'vitepress';
+import DefaultTheme from 'vitepress/theme';
+import {enhanceAppWithTabs} from 'vitepress-plugin-tabs/client';
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({app}) {
+ enhanceAppWithTabs(app);
+ },
+} satisfies Theme;
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index 58b572c9a7..0000000000
--- a/docs/README.md
+++ /dev/null
@@ -1,70 +0,0 @@
-> Lint commit messages
-
-
-
-
-
-> Demo generated with [svg-term-cli](https://github.com/marionebl/svg-term-cli)
-
-# commitlint [![slack][11]][12]
-
-[![npm latest][2]][3] [![Github Actions][4]][5]
-
-`commitlint` helps your team adhere to a commit convention. By supporting npm-installed configurations it makes sharing of commit conventions easy.
-
-# Getting started
-
-## Install
-
-```bash
-npm install -g @commitlint/cli @commitlint/config-conventional
-```
-
-## Configure
-
-```bash
-echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
-```
-
-## Test
-
-```bash
-# Lint from stdin
-echo 'foo: bar' | commitlint
-⧗ input: foo: bar
-✖ type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]
-
-✖ found 1 problems, 0 warnings
-ⓘ Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
-```
-
-```bash
-# Lint last commit from history
-commitlint --from=HEAD~1
-```
-
-?> To get the most out of `commitlint` you'll want to automate it in your project lifecycle. See our [Local setup guide](./guides-local-setup.md?id=guides-local-setup) for next steps.
-
-## Documentation
-
-- **Guides** - Common use cases explained in a step-by-step pace
-- **Concepts** - Overarching topics important to understand the use of `commitlint`
-- **Reference** - Mostly technical documentation
-
-## Attributions
-
-- `commitlint` is possible because of the hard work of the folks of the `conventional-changelog` project
-- Thanks [@markusoelhafen](https://github.com/markusoelhafen) for providing
- the `commitlint` icon
-
-[0]: https://img.shields.io/badge/stability-stable-green.svg?style=flat-square
-[1]: https://nodejs.org/api/documentation.html#documentation_stability_index
-[2]: https://img.shields.io/npm/v/@commitlint/cli.svg?style=flat-square
-[3]: https://npmjs.org/package/@commitlint/cli
-[4]: https://github.com/conventional-changelog/commitlint/actions/workflows/CI.yml/badge.svg
-[5]: https://github.com/conventional-changelog/commitlint/actions/workflows/CI.yml
-[8]: https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square
-[9]: https://nodejs.org/api/documentation.html#documentation_stability_index
-[10]: https://img.shields.io/npm/v/@commitlint/cli/next.svg?style=flat-square
-[11]: https://devtoolscommunity.herokuapp.com/badge.svg?style=flat-square
-[12]: https://devtoolscommunity.herokuapp.com
diff --git a/docs/_navbar.md b/docs/_navbar.md
deleted file mode 100644
index e5de6f9755..0000000000
--- a/docs/_navbar.md
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-
-
-
-
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
deleted file mode 100644
index 1bcd799e03..0000000000
--- a/docs/_sidebar.md
+++ /dev/null
@@ -1,22 +0,0 @@
-- **Guides**
-
- - [Local setup](guides-local-setup.md)
- - [CI setup](guides-ci-setup.md)
- - [Use prompt](guides-use-prompt.md)
- - [Releases](guides-releases.md)
- - [Upgrade commitlint](guides-upgrade.md)
-
-- **Concepts**
-
- - [Commit conventions](concepts-commit-conventions)
- - [Shareable configuration](concepts-shareable-config.md)
-
-- **Reference**
- - [CLI](reference-cli.md)
- - [Configuration](reference-configuration.md)
- - [Rules](reference-rules.md)
- - [API](reference-api.md)
- - [Plugins](reference-plugins.md)
- - [Prompt](reference-prompt.md)
- - [Examples](reference-examples.md)
- - [Community projects](reference-community-projects.md)
diff --git a/docs/api/format.md b/docs/api/format.md
new file mode 100644
index 0000000000..b490bb972a
--- /dev/null
+++ b/docs/api/format.md
@@ -0,0 +1,128 @@
+# @commitlint/format
+
+Format commitlint reports
+
+## Install
+
+```sh
+npm install --save @commitlint/format
+```
+
+## Signature
+
+```ts
+type Problem = {
+ /*
+ * Level of the problem hint | warning | error
+ */
+ level: 0 | 1 | 2;
+ /*
+ * Name of the problem to annotate the message with
+ */
+ name: string;
+ /*
+ * Message to print
+ */
+ message: string;
+}
+
+type Report = {
+ results: ReportResult[];
+}
+
+type ReportResult = {
+ errors: Problem[];
+ warnings: Problem[];
+}
+
+type formatOptions = {
+ /**
+ * Color the output
+ **/
+ color: boolean = true;
+
+ /**
+ * Signs to use as decoration for messages with severity 0, 1, 2
+ **/
+ signs: readonly [string; string; string] = [' ', '⚠', '✖'];
+
+ /**
+ * Colors to use for messages with severity 0, 1, 2
+ **/
+ colors: readonly [string; string; string] = ['white', 'yellow', 'red'];
+
+ /**
+ * Print summary and inputs for reports without problems
+ **/
+ verbose: boolean = false;
+
+ /**
+ * URL to print as help for reports with problems
+ **/
+ helpUrl: string;
+}
+
+format(report?: Report = {}, options?: formatOptions = {}) => string[];
+```
+
+## Import
+
+```js
+import format from '@commitlint/format';
+```
+
+## Examples
+
+### Empty usage (no error founds with colors)
+
+```js
+format();
+/* =>
+[
+ '\u001b[1m\u001b[32m✔\u001b[39m found 0 problems, 0 warnings\u001b[22m'
+]
+*/
+```
+
+### Without colors
+
+```js
+format(
+ {
+ results: [
+ {
+ warnings: [
+ {
+ level: 0,
+ name: 'some-hint',
+ message: 'This will not show up as it has level 0',
+ },
+ {
+ level: 1,
+ name: 'some-warning',
+ message: 'This will show up yellow as it has level 1',
+ },
+ ],
+ errors: [
+ {
+ level: 2,
+ name: 'some-error',
+ message: 'This will show up red as it has level 2',
+ },
+ ],
+ },
+ ],
+ },
+ {
+ color: false,
+ }
+);
+/* =>
+[
+ '✖ This will show up red as it has level 2 [some-error]',
+ ' This will not show up as it has level 0 [some-hint]',
+ '⚠ This will show up yellow as it has level 1 [some-warning]',
+ '✖ found 1 problems, 2 warnings'
+]
+*/
+```
diff --git a/docs/api/lint.md b/docs/api/lint.md
new file mode 100644
index 0000000000..fc50cff6c8
--- /dev/null
+++ b/docs/api/lint.md
@@ -0,0 +1,172 @@
+# @commitlint/lint
+
+Lint a string against commitlint rules
+
+## Install
+
+```sh
+npm install --save @commitlint/lint
+```
+
+## Signature
+
+```ts
+type RuleLevel = 0 | 1 | 2;
+type RuleCondition = 'always' | 'never';
+type RuleOption = any;
+type PrimitiveRule = [RuleLevel, RuleCondition, RuleOption?];
+type AsyncRule = Promise;
+type FunctionRule = () => PrimitiveRule;
+type AsyncFunctionRule = () => Promise;
+type Rule = PrimitiveRule | FunctionRule | AsyncFunctionRule;
+
+type Problem = {
+ level: number;
+ valid: boolean;
+ name: string;
+ message: string;
+}
+
+type Report = {
+ valid: boolean;
+ errors: Problem[];
+ warnings: Problem[];
+}
+
+type Options = {
+ parserOpts?: any;
+};
+
+lint(message: string, rules: {[ruleName: string]: Rule}, opts?: Options) => Promise;
+```
+
+## Basic Examples
+
+### Import
+
+```js
+import lint '@commitlint/lint';
+```
+
+### Usage without config
+
+```js
+const report = await lint('foo: bar');
+console.log(report);
+// => { valid: true, errors: [], warnings: [] }
+```
+
+### Usage with type-enum rules and valid message
+
+```js
+const report = await lint('foo: bar', {'type-enum': [1, 'always', ['foo']]});
+console.log(report);
+// => { valid: true, errors: [], warnings: [] }
+```
+
+### Usage with type-enum rules and invalid message
+
+```js
+const report = await lint('foo: bar', {'type-enum': [1, 'always', ['bar']]});
+console.log(report);
+/* =>
+{
+ valid: false,
+ errors: [],
+ warnings: [
+ {
+ level: 1,
+ valid: false,
+ name: 'type-enum',
+ message: 'type must be one of [bar]'
+ }
+ ]
+}
+*/
+```
+
+### Usage with custom parser options
+
+```js
+const opts = {
+ parserOpts: {
+ headerPattern: /^(\w*)-(\w*)/,
+ headerCorrespondence: ['type', 'scope'],
+ },
+};
+
+const report = await lint(
+ 'foo-bar',
+ {'type-enum': [2, 'always', ['foo']]},
+ opts
+);
+console.log(report);
+// => { valid: true, errors: [], warnings: [] }
+```
+
+## Load configuration
+
+```js
+import load from '@commitlint/load';
+import lint from '@commitlint/lint';
+
+const CONFIG = {
+ extends: ['@commitlint/config-conventional'],
+};
+
+const opts = await load(CONFIG);
+const report = await lint(
+ 'foo: bar',
+ opts.rules,
+ opts.parserPreset ? {parserOpts: opts.parserPreset.parserOpts} : {}
+);
+console.log(report);
+/* =>
+{
+ valid: false,
+ errors: [
+ {
+ level: 2,
+ valid: false,
+ name: 'type-enum',
+ message: 'type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test]'
+ }
+ ],
+ warnings: []
+}
+*/
+```
+
+## Read git history
+
+```js
+import lint from '@commitlint/lint';
+import read from '@commitlint/read';
+
+const RULES = {
+ 'type-enum': [2, 'always', ['foo']],
+};
+
+const commits = await read({to: 'HEAD', from: 'HEAD~2'});
+
+console.info(commits.map((commit) => lint(commit, RULES)));
+```
+
+## Simplified last-commit checker
+
+```js
+import load from '@commitlint/load';
+import read from '@commitlint/read';
+import lint from '@commitlint/lint';
+
+const {rules, parserPreset} = load();
+const [commit] = await read({from: 'HEAD~1'});
+
+const report = await lint(
+ commit,
+ rules,
+ parserPreset ? {parserOpts: parserPreset.parserOpts} : {}
+);
+
+console.log(JSON.stringify(result.valid));
+```
diff --git a/docs/api/load.md b/docs/api/load.md
new file mode 100644
index 0000000000..b8d917233a
--- /dev/null
+++ b/docs/api/load.md
@@ -0,0 +1,188 @@
+# @commitlint/load
+
+Load shared commitlint configuration
+
+## Install
+
+```sh
+npm install --save @commitlint/load
+```
+
+## Signature
+
+```ts
+/**
+ * How to handle violation of rule
+ * 0 - ignore
+ * 1 - warn
+ * 2 - throw
+ */
+type RuleLevel = 0 | 1 | 2;
+
+/*
+ * Application of rule
+ * always - positive
+ * never - negative
+ */
+type RuleCondition = 'always' | 'never';
+
+/*
+ * Additional, optional options to pass to rule
+ */
+type RuleOption = any;
+
+/**
+ * Basic complete rule definition
+ */
+type PrimitiveRule = [RuleLevel, RuleCondition, RuleOption?];
+
+/*
+ * Async rules are resolved during config lookup.
+ * They can be used to set up linting rules based on e.g. the project fs
+ */
+type AsyncRule = Promise;
+
+/*
+ * Function rules are executed during config lookup.
+ * They can be used to set up linting rules based on e.g. the project fs
+ */
+type FunctionRule = () => PrimitiveRule;
+
+/*
+ * Async function rules are executed and awaited during config lookup.
+ * They can be used to set up linting rules based on e.g. the project fs
+ */
+type AsyncFunctionRule () => Promise;
+
+/*
+ * Polymorphic rule struct
+ */
+type Rule = PrimitiveRule | FunctionRule | AsyncFunctionRule;
+
+/*
+ * Parser preset for conventional commits
+ */
+type ParserPreset = {
+ name: string;
+ path: string;
+ opts: any;
+};
+
+type Seed = {
+ /*
+ * ids resolvable from cwd or configuration file.
+ * Imported and merged into configuration
+ * with increasing precedence, with top level config taking the highest.
+ */
+ extends?: string[];
+ /*
+ * id resolvable from cwd or configuration file.
+ * Imported and expanded to {ParserPreset}.
+ * Top level parserPresets override presets in extended configuration.
+ */
+ parserPreset?: string;
+ /**
+ * Initial map of rules to check against
+ */
+ rules?: {[ruleName: string]: Rule};
+ /**
+ * URL to print as help for reports with problems
+ */
+ helpUrl?: string;
+};
+
+type Config = {
+ /*
+ * Relatives path to all extended configurations.
+ */
+ extends: string[];
+ /*
+ * Expanded parser preset, if any
+ */
+ parserPreset?: ParserPreset;
+ /*
+ * Merged map of rules to check against
+ */
+ rules: {[ruleName: string]: Rule};
+ /**
+ * URL to print as help for reports with problems
+ */
+ helpUrl?: string;
+};
+
+type LoadOptions = {
+ /*
+ * Path to the config file to load.
+ */
+ file?: string;
+ /*
+ * The cwd to use when loading config from file parameter.
+ */
+ cwd: string;
+};
+
+load(seed: Seed = {}, options?: LoadOptions = {cwd: process.cwd()}) => Promise;
+```
+
+## Import
+
+```js
+import load from '@commitlint/load';
+```
+
+## Examples
+
+### Inline rules
+
+```js
+const config = await load({
+ rules: {
+ 'body-leading-blank': [2, 'always'],
+ },
+});
+console.log(config);
+// => { extends: [], rules: { 'body-leading-blank': [ 2, 'always' ] } }
+```
+
+### Reference a file
+
+```js
+const config = await load({extends: ['./package']});
+console.log(config);
+// => { extends: ['./package', './package-b'], rules: {} }
+```
+
+### Inline `parserPreset`
+
+```js
+const config = await load({parserPreset: './parser-preset.js'});
+console.log(config);
+/* =>
+{
+ extends: [],
+ rules: {},
+ parserPreset: {
+ name: './parser-preset.js',
+ path: './parser-preset.js',
+ opts: {}
+ }
+}
+*/
+```
+
+### Config file with with current working directory
+
+```js
+const config = await load({}, {file: '.commitlintrc.yml', cwd: process.cwd()});
+console.log(config);
+/* =>
+{
+ extends: [],
+ rules: {
+ 'body-leading-blank': [ 1, 'always' ]
+ },
+ formatter: '@commitlint/format',
+ plugins: {}
+}
+*/
+```
diff --git a/docs/api/read.md b/docs/api/read.md
new file mode 100644
index 0000000000..6cfaab96e9
--- /dev/null
+++ b/docs/api/read.md
@@ -0,0 +1,69 @@
+# @commitlint/read
+
+Read commit messages from a specified range or disk
+
+## Install
+
+```sh
+npm install --save @commitlint/read
+```
+
+## Signature
+
+```ts
+type Range = {
+ /* Lower end of the commit range to read */
+ from: string;
+ /* Upper end of the commit range to read */
+ to: string;
+ /* Whether (boolean) to read from ./.git/COMMIT_EDITMSG or where to read from (string) */
+ edit?: boolean | string;
+};
+
+read(range: Range) => Promise
+```
+
+## Import
+
+```js
+import read from '@commitlint/read';
+```
+
+## Examples
+
+Consider to have a repository with two commits:
+
+1. Initial commit
+2. I did something
+
+### Using `edit: true`
+
+```js
+const result = await read({edit: true});
+console.info(result);
+// => ['I did something\n\n']
+```
+
+### Read last two commits
+
+```js
+const result = await read({from: 'HEAD~2'});
+console.info(result);
+// => ['I did something\n\n', 'Initial commit\n\n']
+```
+
+### Read commits within a range
+
+```js
+const result = await read({from: 'HEAD~2', to: 'HEAD~1'});
+console.info(result);
+// => ['Initial commit\n\n']
+```
+
+### Read commit message from git gui file
+
+```js
+const result = await read({edit: './git/GITGUI_EDITMESSAGE'});
+console.info(result);
+// => ['I did something via git gui\n\n']
+```
diff --git a/docs/attributions.md b/docs/attributions.md
new file mode 100644
index 0000000000..f46a3f9c51
--- /dev/null
+++ b/docs/attributions.md
@@ -0,0 +1,12 @@
+# Attributions
+
+`commitlint` is possible because of the hard work of the folks of the `conventional-changelog` project
+
+---
+
+Thanks [@markusoelhafen](https://github.com/markusoelhafen) for providing
+the `commitlint` icon
+
+---
+
+Homepage SVG Demo generated with [svg-term-cli](https://github.com/marionebl/svg-term-cli)
diff --git a/docs/concepts-commit-conventions.md b/docs/concepts/commit-conventions.md
similarity index 98%
rename from docs/concepts-commit-conventions.md
rename to docs/concepts/commit-conventions.md
index 4f6b85020a..a35a4a277c 100644
--- a/docs/concepts-commit-conventions.md
+++ b/docs/concepts/commit-conventions.md
@@ -10,7 +10,7 @@ With this additional information tools can derive useful human-readable informat
The most common commit conventions follow this pattern:
-```
+```text
type(scope?): subject
body?
footer?
diff --git a/docs/concepts-shareable-config.md b/docs/concepts/shareable-config.md
similarity index 75%
rename from docs/concepts-shareable-config.md
rename to docs/concepts/shareable-config.md
index 326e5472b9..95b2689a40 100644
--- a/docs/concepts-shareable-config.md
+++ b/docs/concepts/shareable-config.md
@@ -3,16 +3,23 @@
Most commonly shareable configuration is delivered as npm package exporting
an object containing `.rules` as default. To use shared configuration you specify it as item in the `.extends` array:
-```js
-// commitlint.config.js
-module.exports = {
+::: code-group
+
+```js [commitlint.config.js]
+/**
+ * @type {import('@commitlint/types').UserConfig}
+ */
+export default {
extends: ['example'], // => commitlint-config-example
};
```
-This causes `commitlint` to pick up `commitlint-config-example`. Make it available by installing it.
+:::
+
+This causes `commitlint` to pick up `commitlint-config-example`.
+Make it available by installing it.
-```bash
+```sh
npm install --save-dev commitlint-config-example
```
@@ -24,37 +31,49 @@ This works recursively, enabling shareable configuration to extend on an indefin
You can also load local configuration by using a relative path to the file.
-> This must always start with a `.` (dot).
+::: warning
+This must always start with a `.` (dot).
+:::
-```js
-// commitlint.config.js
-module.exports = {
+::: code-group
+
+```js [commitlint.config.js]
+export default {
extends: ['./example'], // => ./example.js
};
```
+:::
+
## Scoped packages
When using scoped packages you have two options.
You can provide the full path of the package like:
-```js
-// commitlint.config.js
-module.exports = {
+::: code-group
+
+```js [commitlint.config.js]
+export default {
extends: ['@commitlint/config-conventional'], // => @commitlint/config-conventional
};
```
+:::
+
Or just the scope/owner of the package.
+> [!TIP]
> Just like "normal" extends listed above, this will add `/commitlint-config`.
-```js
-// commitlint.config.js
-module.exports = {
+::: code-group
+
+```js [commitlint.config.js]
+export default {
extends: ['@coolcompany'], // => @coolcompany/commitlint-config
};
```
+:::
+
If you don't use the exact `/commitlint-config` pattern, you have to provide the full name of the package.
diff --git a/docs/guides-publish-config.md b/docs/guides-publish-config.md
deleted file mode 100644
index 158e01fd03..0000000000
--- a/docs/guides-publish-config.md
+++ /dev/null
@@ -1 +0,0 @@
-# Guide: Publish a config
diff --git a/docs/guides-ci-setup.md b/docs/guides/ci-setup.md
similarity index 85%
rename from docs/guides-ci-setup.md
rename to docs/guides/ci-setup.md
index d05ee569c2..d4c217d373 100644
--- a/docs/guides-ci-setup.md
+++ b/docs/guides/ci-setup.md
@@ -4,7 +4,7 @@ Enforce commit conventions with confidence by linting on your CI servers with `c
This guide assumes you have already configured `commitlint` for local usage.
-Follow the [Getting Started](./?id=getting-started) for basic installation and configuration instructions.
+Follow the [Getting Started](/guides/getting-started) for basic installation and configuration instructions.
## GitHub Actions
@@ -147,7 +147,7 @@ lint:commit:
## Jenkins X
-```
+```yml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
@@ -155,15 +155,15 @@ metadata:
spec:
pipelineSpec:
tasks:
- - name: conventional-commits
- taskSpec:
- steps:
- - name: lint-commit-messages
- image: commitlint/commitlint
- script: |
- #!/usr/bin/env sh
- . .jx/variables.sh
- commitlint --extends '@commitlint/config-conventional' --from $PR_BASE_SHA --to $PR_HEAD_SHA
+ - name: conventional-commits
+ taskSpec:
+ steps:
+ - name: lint-commit-messages
+ image: commitlint/commitlint
+ script: |
+ #!/usr/bin/env sh
+ . .jx/variables.sh
+ commitlint --extends '@commitlint/config-conventional' --from $PR_BASE_SHA --to $PR_HEAD_SHA
serviceAccountName: tekton-bot
timeout: 15m
```
@@ -181,4 +181,6 @@ workflows:
- npx commitlint --from=HEAD~1
```
-?> Help yourself adopting a commit convention by using an interactive commit prompt. Learn how to use `@commitlint/prompt-cli` in the [Use prompt guide](guides-use-prompt.md)
+> [!TIP]
+> Help yourself adopting a commit convention by using an interactive commit prompt.
+> Learn how to use `@commitlint/prompt-cli` in the [Use prompt guide](/> guides/use-prompt)
diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md
new file mode 100644
index 0000000000..494e1f268c
--- /dev/null
+++ b/docs/guides/getting-started.md
@@ -0,0 +1,31 @@
+# Getting started
+
+## Install
+
+Install `@commitlint/cli` and a `@commitlint/config-*` / `commitlint-config-*` of your choice as devDependency and configure `commitlint` to use it.
+
+::: code-group
+
+```sh [npm]
+npm install --save-dev @commitlint/{cli,config-conventional}
+```
+
+```sh [yarn]
+yarn add --dev @commitlint/{cli,config-conventional}
+```
+
+```sh [npm (Windows)]
+npm install --save-dev @commitlint/config-conventional @commitlint/cli
+```
+
+:::
+
+## Configuration
+
+Configure commitlint to use conventional config
+
+```sh
+echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
+```
+
+Refer to [configuration documentation](/reference/configuration) for more information.
diff --git a/docs/guides-local-setup.md b/docs/guides/local-setup.md
similarity index 65%
rename from docs/guides-local-setup.md
rename to docs/guides/local-setup.md
index cc706f359c..1a55cb4877 100644
--- a/docs/guides-local-setup.md
+++ b/docs/guides/local-setup.md
@@ -4,64 +4,7 @@ Get high commit message quality and short feedback cycles by linting commit mess
This guide demonstrates how to achieve this via git hooks.
-## Install commitlint
-
-Install `commitlint` and a `commitlint-config-*` of your choice as devDependency and
-configure `commitlint` to use it.
-
----
-
-
-NPM
-
-```sh
-# Install and configure if needed
-npm install --save-dev @commitlint/{cli,config-conventional}
-# For Windows:
-npm install --save-dev @commitlint/config-conventional @commitlint/cli
-```
-
-
-
----
-
-
-YARN
-
-```sh
-# Install and configure if needed
-yarn add --dev @commitlint/{cli,config-conventional}
-```
-
-
-
-## Configuration
-
-```sh
-# Configure commitlint to use conventional config
-echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
-```
-
-Configuration can be defined in the following files:
-
-- `.commitlintrc`
-- `.commitlintrc.json`
-- `.commitlintrc.yaml`
-- `.commitlintrc.yml`
-- `.commitlintrc.js`
-- `.commitlintrc.cjs`
-- `.commitlintrc.mjs`
-- `.commitlintrc.ts`
-- `.commitlintrc.cts`
-- `commitlint.config.js`
-- `commitlint.config.cjs`
-- `commitlint.config.mjs`
-- `commitlint.config.ts`
-- `commitlint.config.cts`
-
-Alternatively you can add `commitlint` field in `package.json`
-
-Refer to [configuration documentation](reference-configuration.md) for more information.
+Follow the [Getting Started](/guides/getting-started) for basic installation and configuration instructions.
## Add hook
@@ -73,13 +16,14 @@ To lint commits before they are created you can use [Husky](https://typicode.git
You can find complete setup instructions on the [official documentation](https://typicode.github.io/husky/get-started.html).
+> [!NOTE]
> The following instructions are meant to `husky@v9` if you are using a different version
> consult the official documentation of your version.
---
-
-NPM
+:::tabs
+== npm
```sh
npm install --save-dev husky
@@ -97,12 +41,7 @@ npm pkg set scripts.commitlint="commitlint --edit"
echo "npm run commitlint \${1}" > .husky/commit-msg
```
-
-
----
-
-
-YARN
+== yarn
```sh
yarn add --dev husky
@@ -120,9 +59,10 @@ npm pkg set scripts.commitlint="commitlint --edit"
echo "yarn commitlint \${1}" > .husky/commit-msg
```
-Please note that currently @commitlint/cli doesn't support yarn v2 Plug'n'Play (using yarn v2 with `nodeLinker: node-modules` in your .yarnrc.yml file may work sometimes)
+> [!WARNING]
+> Please note that currently @commitlint/cli doesn't support yarn v2 Plug'n'Play (using yarn > v2 with `nodeLinker: node-modules` in your .yarnrc.yml file may work sometimes)
-
+:::
---
@@ -130,6 +70,7 @@ Please note that currently @commitlint/cli doesn't support yarn v2 Plug'n'Play (
Info about git hooks can be found on [Git documentation](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).
+> [!WARNING]
> It's necessary that you use **commit-msg** as the name for hook file.
## Test
@@ -171,4 +112,4 @@ No staged files match any of provided globs.
# husky > commit-msg
```
-?> Local linting is fine for fast feedback but can easily be tinkered with. To ensure all commits are linted you'll want to check commits on an automated CI Server too. Learn how to in the [CI Setup guide](guides-ci-setup.md).
+?> Local linting is fine for fast feedback but can easily be tinkered with. To ensure all commits are linted you'll want to check commits on an automated CI Server too. Learn how to in the [CI Setup guide](/guides/ci-setup).
diff --git a/docs/guides-use-prompt.md b/docs/guides/use-prompt.md
similarity index 72%
rename from docs/guides-use-prompt.md
rename to docs/guides/use-prompt.md
index f32a947a30..cd1bdda4d5 100644
--- a/docs/guides-use-prompt.md
+++ b/docs/guides/use-prompt.md
@@ -4,23 +4,31 @@
## Install
-```bash
-# Create a git repository if needed
-git init
+1. Create a git repository if needed
-# Create a package.json if needed
-npm init
+ ```sh
+ git init
+ ```
-# Install and configure if needed
-npm install --save-dev @commitlint/{cli,config-conventional,prompt-cli}
-echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
-```
+2. Create a package.json if needed
+
+ ```sh
+ npm init
+ ```
+
+3. Install and configure if needed
+
+ ```sh
+ npm install --save-dev @commitlint/{cli,config-conventional,prompt-cli}
+
+ echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
+ ```
## Provide a shortcut
To make prompt-cli easy to use, add a npm run-script to your `package.json`
-```json
+```json:line-numbers {3}
{
"scripts": {
"commit": "commit"
diff --git a/docs/index.html b/docs/index.html
deleted file mode 100644
index 295a13e89d..0000000000
--- a/docs/index.html
+++ /dev/null
@@ -1,140 +0,0 @@
-
-
-
-
- commitlint - Lint commit messages
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000000..cf71d243e9
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,43 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+ name: commitlint
+ text: Lint commit messages
+ tagline: helps your team adhere to a commit convention
+ image:
+ src: ./assets/commitlint.svg
+ alt: commitlint on CLI
+ actions:
+ - theme: brand
+ text: Guides
+ link: /guides/getting-started
+
+ - theme: alt
+ text: Reference
+ link: /reference/configuration
+
+ - theme: alt
+ text: Concepts
+ link: /concepts/commit-conventions
+
+features:
+ - title: Sharable configs
+ details: By supporting npm-installed configurations it makes sharing of commit conventions easy.
+ icon: 🌏
+ link: /concepts/shareable-config
+ linkText: Learn more
+
+ - title: Easy setup
+ details: Get high commit message quality and short feedback cycles by linting commit messages right when they are authored.
+ icon: 🚀
+ link: /guides/getting-started
+ linkText: Getting started
+
+ - title: Easy to integrate with your CI
+ details: To get the most out of commitlint you'll want to automate it in your project lifecycle.
+ icon: ⚙️
+ link: /guides/ci-setup
+ linkText: Learn more
+---
diff --git a/docs/assets/commitlint.json b/docs/public/assets/commitlint.json
similarity index 100%
rename from docs/assets/commitlint.json
rename to docs/public/assets/commitlint.json
diff --git a/docs/assets/commitlint.svg b/docs/public/assets/commitlint.svg
similarity index 100%
rename from docs/assets/commitlint.svg
rename to docs/public/assets/commitlint.svg
diff --git a/docs/assets/cz-commitlint.png b/docs/public/assets/cz-commitlint.png
similarity index 100%
rename from docs/assets/cz-commitlint.png
rename to docs/public/assets/cz-commitlint.png
diff --git a/docs/assets/icon.png b/docs/public/assets/icon.png
similarity index 100%
rename from docs/assets/icon.png
rename to docs/public/assets/icon.png
diff --git a/docs/assets/icon.svg b/docs/public/assets/icon.svg
similarity index 100%
rename from docs/assets/icon.svg
rename to docs/public/assets/icon.svg
diff --git a/docs/reference-api.md b/docs/reference-api.md
deleted file mode 100644
index 84c20cbefa..0000000000
--- a/docs/reference-api.md
+++ /dev/null
@@ -1,466 +0,0 @@
-# API
-
-## @commitlint/format
-
-> Format commitlint reports
-
-### Install
-
-```
-npm install --save @commitlint/format
-```
-
-### Usage
-
-- **Signature**
-
-```ts
-type Problem = {
- /*
- * Level of the problem hint | warning | error
- */
- level: 0 | 1 | 2;
- /*
- * Name of the problem to annotate the message with
- */
- name: string;
- /*
- * Message to print
- */
- message: string;
-}
-
-type Report = {
- results: ReportResult[];
-}
-
-type ReportResult = {
- errors: Problem[];
- warnings: Problem[];
-}
-
-type formatOptions = {
- /**
- * Color the output
- **/
- color: boolean = true;
-
- /**
- * Signs to use as decoration for messages with severy 0, 1, 2
- **/
- signs: readonly [string; string; string] = [' ', '⚠', '✖'];
-
- /**
- * Colors to use for messages with severy 0, 1, 2
- **/
- colors: readonly [string; string; string] = ['white', 'yellow', 'red'];
-
- /**
- * Print summary and inputs for reports without problems
- **/
- verbose: boolean = false;
-
- /**
- * URL to print as help for reports with problems
- **/
- helpUrl: string;
-}
-
-format(report?: Report = {}, options?: formatOptions = {}) => string[];
-```
-
-- **Example**
-
-```js
-const format = require('@commitlint/format').default;
-
-format(); // => [ '\u001b[1m\u001b[32m✔\u001b[39m found 0 problems, 0 warnings\u001b[22m' ]
-
-format(
- {
- results: [
- {
- warnings: [
- {
- level: 0,
- name: 'some-hint',
- message: 'This will not show up as it has level 0',
- },
- {
- level: 1,
- name: 'some-warning',
- message: 'This will show up yellow as it has level 1',
- },
- ],
- errors: [
- {
- level: 2,
- name: 'some-error',
- message: 'This will show up red as it has level 2',
- },
- ],
- },
- ],
- },
- {
- color: false,
- }
-);
-/* => [
- '✖ This will show up red as it has level 2 [some-error]',
- ' This will not show up as it has level 0 [some-hint]',
- '⚠ This will show up yellow as it has level 1 [some-warning]',
- '✖ found 1 problems, 2 warnings'
-] */
-```
-
-## @commitlint/load
-
-> Load shared commitlint configuration
-
-### Install
-
-```
-npm install --save @commitlint/load
-```
-
-### Usage
-
-- **Signature**
-
-```ts
-/**
- * How to handle violation of rule
- * 0 - ignore
- * 1 - warn
- * 2 - throw
- */
-type RuleLevel = 0 | 1 | 2;
-
-/*
- * Application of rule
- * always - positive
- * never - negative
- */
-type RuleCondition = 'always' | 'never';
-
-/*
- * Additional, optional options to pass to rule
- */
-type RuleOption = any;
-
-/**
- * Basic complete rule definition
- */
-type PrimitiveRule = [RuleLevel, RuleCondition, RuleOption?];
-
-/*
- * Async rules are resolved during config lookup.
- * They can be used to set up linting rules based on e.g. the project fs
- */
-type AsyncRule = Promise;
-
-/*
- * Function rules are executed during config lookup.
- * They can be used to set up linting rules based on e.g. the project fs
- */
-type FunctionRule = () => PrimitiveRule;
-
-/*
- * Async function rules are executed and awaited during config lookup.
- * They can be used to set up linting rules based on e.g. the project fs
- */
-type AsyncFunctionRule () => Promise;
-
-/*
- * Polymorphic rule struct
- */
-type Rule = PrimitiveRule | FunctionRule | AsyncFunctionRule;
-
-/*
- * Parser preset for conventional commits
- */
-type ParserPreset = {
- name: string;
- path: string;
- opts: any;
-};
-
-type Seed = {
- /*
- * ids resolveable from cwd or configuration file.
- * Imported and merged into configuration
- * with increasing precedence, with top level config taking the highest.
- */
- extends?: string[];
- /*
- * id resolveable from cwd or configuration file.
- * Imported and expanded to {ParserPreset}.
- * Top level parserPresets override presets in extended configuration.
- */
- parserPreset?: string;
- /**
- * Initial map of rules to check against
- */
- rules?: {[ruleName: string]: Rule};
- /**
- * URL to print as help for reports with problems
- */
- helpUrl?: string;
-};
-
-type Config = {
- /*
- * Relatives path to all extendend configurations.
- */
- extends: string[];
- /*
- * Expanded parser preset, if any
- */
- parserPreset?: ParserPreset;
- /*
- * Merged map of rules to check against
- */
- rules: {[ruleName: string]: Rule};
- /**
- * URL to print as help for reports with problems
- */
- helpUrl?: string;
-};
-
-type LoadOptions = {
- /*
- * Path to the config file to load.
- */
- file?: string;
- /*
- * The cwd to use when loading config from file parameter.
- */
- cwd: string;
-};
-
-load(seed: Seed = {}, options?: LoadOptions = {cwd: process.cwd()}) => Promise;
-```
-
-- **Example**
-
-```js
-const load = require('@commitlint/load').default;
-
-load({
- rules: {
- 'body-leading-blank': [2, 'always'],
- },
-}).then((config) => console.log(config));
-// => { extends: [], rules: { 'body-leading-blank': [ 2, 'always' ] } }
-
-load({extends: ['./package']}).then((config) => console.log(config));
-// => { extends: ['./package', './package-b'], rules: {} }
-
-load({parserPreset: './parser-preset.js'}).then((config) =>
- console.log(config)
-);
-// => { extends: [], rules: {}, parserPreset: {name: './parser-preset.js', path: './parser-preset.js', opts: {}}}
-
-load({}, {file: '.commitlintrc.yml', cwd: process.cwd()}).then((config) =>
- console.log(config)
-);
-// => { extends: [], rules: { 'body-leading-blank': [ 1, 'always' ] }, formatter: '@commitlint/format', plugins: {} }
-```
-
-### @commitlint/read
-
-> Read commit messages from a specified range or disk
-
-### Install
-
-```
-npm install --save @commitlint/read
-```
-
-### Usage
-
-- **Signature**
-
-```ts
-type Range = {
- /* Lower end of the commit range to read */
- from: string;
- /* Upper end of the commit range to read */
- to: string;
- /* Whether (boolean) to read from ./.git/COMMIT_EDITMSG or where to read from (string) */
- edit?: boolean | string;
-};
-
-read(range: Range) => Promise
-```
-
-- **Example**
-
-```js
-// git commit -m "I did something"
-const read = require('@commitlint/read').default;
-
-read({edit: true}).then((messages) => console.log(messages));
-// => ['I did something\n\n']
-
-read({edit: './git/GITGUI_EDITMESSAGE'}).then((messages) =>
- console.log(messages)
-);
-// => ['I did something via git gui\n\n']
-
-read({from: 'HEAD~2'}).then((messages) => console.log(messages));
-// => ['I did something\n\n', 'Initial commit\n\n']
-
-read({from: 'HEAD~2', to: 'HEAD~1'}).then((messages) => console.log(messages));
-// => ['Initial commit\n\n']
-```
-
-### lint
-
-> Lint a string against commitlint rules
-
-### Install
-
-```
-npm install --save @commitlint/lint
-```
-
-### Usage
-
-- **Signature**
-
-```ts
-type RuleLevel = 0 | 1 | 2;
-type RuleCondition = 'always' | 'never';
-type RuleOption = any;
-type PrimitiveRule = [RuleLevel, RuleCondition, RuleOption?];
-type AsyncRule = Promise;
-type FunctionRule = () => PrimitiveRule;
-type AsyncFunctionRule () => Promise;
-type Rule = PrimitiveRule | FunctionRule | AsyncFunctionRule;
-
-type Problem = {
- level: number;
- valid: boolean;
- name: string;
- message: string;
-}
-
-type Report = {
- valid: boolean;
- errors: Problem[];
- warnings: Problem[];
-}
-
-type Options = {
- parserOpts?: any;
-};
-
-lint(message: string, rules: {[ruleName: string]: Rule}, opts?: Options) => Promise;
-```
-
-- **Basic Example**
-
-```js
-const lint = require('@commitlint/lint').default;
-
-lint('foo: bar').then((report) => console.log(report));
-// => { valid: true, errors: [], warnings: [] }
-
-lint('foo: bar', {'type-enum': [1, 'always', ['foo']]}).then((report) =>
- console.log(report)
-);
-// => { valid: true, errors: [], warnings: [] }
-
-lint('foo: bar', {'type-enum': [1, 'always', ['bar']]}).then((report) =>
- console.log(report)
-);
-/* =>
- { valid: true,
- errors: [],
- warnings:
- [ { level: 1,
- valid: false,
- name: 'type-enum',
- message: 'type must be one of [bar]' } ] }
- */
-
-const opts = {
- parserOpts: {
- headerPattern: /^(\w*)-(\w*)/,
- headerCorrespondence: ['type', 'scope'],
- },
-};
-
-lint('foo-bar', {'type-enum': [2, 'always', ['foo']]}, opts).then((report) =>
- console.log(report)
-);
-// => { valid: true, errors: [], warnings: [] }
-```
-
-- **Load configuration**
-
-```js
-const load = require('@commitlint/load').default;
-const lint = require('@commitlint/lint').default;
-
-const CONFIG = {
- extends: ['@commitlint/config-conventional'],
-};
-
-load(CONFIG)
- .then((opts) =>
- lint(
- 'foo: bar',
- opts.rules,
- opts.parserPreset ? {parserOpts: opts.parserPreset.parserOpts} : {}
- )
- )
- .then((report) => console.log(report));
-/* =>
- { valid: false,
- errors:
- [ { level: 2,
- valid: false,
- name: 'type-enum',
- message: 'type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test]' } ],
- warnings: [] }
- */
-```
-
-- **Read git history**
-
-```js
-const lint = require('@commitlint/lint').default;
-const read = require('@commitlint/read').default;
-
-const RULES = {
- 'type-enum': [2, 'always', ['foo']],
-};
-
-const check = (commit) => lint(commit, RULES);
-
-read({to: 'HEAD', from: 'HEAD~2'}).then((commits) =>
- Promise.all(commits.map(check))
-);
-```
-
-- **Simplified last-commit checker**
-
-```js
-const load = require('@commitlint/load').default;
-const read = require('@commitlint/read').default;
-const lint = require('@commitlint/lint').default;
-
-Promise.all([load(), read({from: 'HEAD~1'})])
- .then((tasks) => {
- const [{rules, parserPreset}, [commit]] = tasks;
- return lint(
- commit,
- rules,
- parserPreset ? {parserOpts: parserPreset.parserOpts} : {}
- );
- })
- .then((report) => console.log(JSON.stringify(result.valid)));
-```
diff --git a/docs/reference-examples.md b/docs/reference-examples.md
deleted file mode 100644
index 42709982c0..0000000000
--- a/docs/reference-examples.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Examples
-
-These examples show common usages of how commitlint can be configured.
-
-## Validate for issue/ticket numbers
-
-In your `package.json` add:
-
-```
- commitlint: {
- 'rules': {
- 'references-empty': [2, 'never'],
- },
- parserPreset: {
- parserOpts: {
- issuePrefixes: ['PROJ-']
- }
- },
- }
-```
diff --git a/docs/reference-cli.md b/docs/reference/cli.md
similarity index 99%
rename from docs/reference-cli.md
rename to docs/reference/cli.md
index 387b8048db..aa9bf4d2de 100644
--- a/docs/reference-cli.md
+++ b/docs/reference/cli.md
@@ -1,6 +1,6 @@
# CLI
-```bash
+```sh
❯ npx commitlint --help
@commitlint/cli@11.0.0 - Lint your commit messages
diff --git a/docs/reference-community-projects.md b/docs/reference/community-projects.md
similarity index 100%
rename from docs/reference-community-projects.md
rename to docs/reference/community-projects.md
diff --git a/docs/reference-configuration.md b/docs/reference/configuration.md
similarity index 62%
rename from docs/reference-configuration.md
rename to docs/reference/configuration.md
index 0e1d3f9a71..c77d695cb2 100644
--- a/docs/reference-configuration.md
+++ b/docs/reference/configuration.md
@@ -1,21 +1,42 @@
# Configuration
-`@commitlint/cli` picks up configuration from `./commitlint.config.js`.
+## Config via file
+
+`@commitlint/cli` picks up configuration from the following files:
+
+- `.commitlintrc`
+- `.commitlintrc.json`
+- `.commitlintrc.yaml`
+- `.commitlintrc.yml`
+- `.commitlintrc.js`
+- `.commitlintrc.cjs`
+- `.commitlintrc.mjs`
+- `.commitlintrc.ts`
+- `.commitlintrc.cts`
+- `commitlint.config.js`
+- `commitlint.config.cjs`
+- `commitlint.config.mjs`
+- `commitlint.config.ts`
+- `commitlint.config.cts`
The file is expected
-- to contain valid JavaScript
+- to contain valid JavaScript / Typescript
- export a configuration object
- adhere to the schema outlined below
+Configuration files are resolved using [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig/tree/v8.2.0).
+
+## Config via `package.json`
+
+You can add `commitlint` field in `package.json` with an object that follows below structure.
+
## Config option CLI
Add the path to the configuration file. Example: `commitlint --config commitlint.config.js`
## Configuration object example
-### JavaScript
-
```js
const Configuration = {
/*
@@ -74,64 +95,40 @@ const Configuration = {
},
};
-module.exports = Configuration;
+export default Configuration;
```
-### TypeScript
+> [!NOTE]
+> CJS format is supported as well:
+>
+> ```js
+> module.exports = Configuration;
+> ```
+
+### Typescript configuration
+
+Configuration can also be a typescript file.
+
+Relevant types and enums can be imported from `@commitlint/types`.
+
+Below you can see main changes from a standard js file:
```ts
-import type {UserConfig} from '@commitlint/types';
-import {RuleConfigSeverity} from '@commitlint/types';
+import type {UserConfig} from '@commitlint/types'; // [!code focus]
+import {RuleConfigSeverity} from '@commitlint/types'; // [!code focus]
const Configuration: UserConfig = {
- /*
- * Resolve and load @commitlint/config-conventional from node_modules.
- * Referenced packages must be installed
- */
+ // [!code focus]
extends: ['@commitlint/config-conventional'],
- /*
- * Resolve and load conventional-changelog-atom from node_modules.
- * Referenced packages must be installed
- */
parserPreset: 'conventional-changelog-atom',
- /*
- * Resolve and load @commitlint/format from node_modules.
- * Referenced package must be installed
- */
formatter: '@commitlint/format',
- /*
- * Any rules defined here will override rules from @commitlint/config-conventional
- */
rules: {
- 'type-enum': [RuleConfigSeverity.Error, 'always', ['foo']],
- },
- /*
- * Functions that return true if commitlint should ignore the given message.
- */
- ignores: [(commit) => commit === ''],
- /*
- * Whether commitlint uses the default ignore rules.
- */
- defaultIgnores: true,
- /*
- * Custom URL to show upon failure
- */
- helpUrl:
- 'https://github.com/conventional-changelog/commitlint/#what-is-commitlint',
- /*
- * Custom prompt configs
- */
- prompt: {
- messages: {},
- questions: {
- type: {
- description: 'please input type:',
- },
- },
+ 'type-enum': [RuleConfigSeverity.Error, 'always', ['foo']], // [!code focus]
},
+ // ...
};
-module.exports = Configuration;
+export default Configuration;
```
## Shareable configuration
@@ -142,48 +139,55 @@ that can be resolved by the node resolve algorithm.
This means installed npm packages and local files can be used.
-- npm
+:::tabs
+== npm
-```
+```sh
npm install --save-dev commitlint-config-lerna @commitlint/config-conventional
```
-```js
-// commitlint.config.js
-module.exports = {
- extends: [
- 'lerna' // prefixed with commitlint-config-*,
- '@commitlint/config-conventional' // scoped packages are not prefixed
- ]
+::: code-group
+
+```js [commitlint.config.js]
+export default {
+ extends: [
+ 'lerna' // prefixed with commitlint-config-*,
+ '@commitlint/config-conventional' // scoped packages are not prefixed
+ ]
}
```
-- local
+== local
-```js
-// commitlint.config.js
-module.exports = {
+::: code-group
+
+```js [commitlint.config.js]
+export default {
extends: ['./commitlint.base.js', './commitlint.types.js'],
};
```
-```js
-// commitlint.types.js, will be picked up by commitlint.config.js
-module.exports = {
+```js [commitlint.types.js]
+// will be picked up by commitlint.config.js
+export default {
rules: {
'type-enum': [2, 'always', ['foo']],
},
};
```
-```js
-// commitlint.base.js, will be picked up by commitlint.config.js
-module.exports = {
+```js [commitlint.base.js]
+// will be picked up by commitlint.config.js
+export default {
extends: ['@commitlint/config-conventional'], // extends can be nested
parserPreset: 'conventional-changelog-atom',
};
```
+:::
+
+More information can be found in the [Concepts – sharable config section](/concepts/shareable-config).
+
## Parser presets
The parser preset used to parse commit messages can be configured.
@@ -191,31 +195,33 @@ Use ids resolvable by the node resolve algorithm.
This means installed npm packages and local files can be used.
-- npm
+:::tabs
+== npm
-```
+```sh
npm install --save-dev conventional-changelog-atom
```
-```js
-// commitlint.config.js
-module.exports = {
+::: code-group
+
+```js [commitlint.config.js]
+export default {
parserPreset: 'conventional-changelog-atom',
};
```
-- local
+== local
-```js
-// commitlint.config.js
-module.exports = {
+::: code-group
+
+```js [commitlint.config.js]
+export default {
parserPreset: './parser-preset',
};
```
-```js
-// parser-preset.js
-module.exports = {
+```js [parser-preset.js]
+export default {
parserOpts: {
headerPattern: /^(\w*)\((\w*)\)-(\w*)\s(.*)$/,
headerCorrespondence: ['type', 'scope', 'ticket', 'subject'],
@@ -223,23 +229,25 @@ module.exports = {
};
```
+:::
+
## Formatter
Commitlint can output the issues encountered in different formats, if necessary.
Use ids resolvable by the node resolve algorithm.
```js
-module.exports = {
+export default {
formatter: '@commitlint/format',
};
```
## Rules
-Refer to [Rules](reference-rules.md) for a complete list of available rules.
+Refer to [Rules](/reference/rules.md) for a complete list of available rules.
## Prompt
Config command-line submit interaction, works with `@commitlint/cz-commitlint`.
-Refer to [Prompt Config](reference-prompt.md) for details.
+Refer to [Prompt Config](/reference/prompt.md) for details.
diff --git a/docs/reference/examples.md b/docs/reference/examples.md
new file mode 100644
index 0000000000..3832adbb1f
--- /dev/null
+++ b/docs/reference/examples.md
@@ -0,0 +1,22 @@
+# Examples
+
+These examples show common usages of how commitlint can be configured.
+
+## Validate for issue/ticket numbers
+
+::: code-group
+
+```jsonc [package.json]
+ // ...
+ commitlint: {
+ "rules": {
+ "references-empty": [2, "never"]
+ },
+ "parserPreset": {
+ "parserOpts": {
+ "issuePrefixes": ["PROJ-"]
+ }
+ }
+ }
+ // ...
+```
diff --git a/docs/reference-plugins.md b/docs/reference/plugins.md
similarity index 95%
rename from docs/reference-plugins.md
rename to docs/reference/plugins.md
index 078f124684..2233107143 100644
--- a/docs/reference-plugins.md
+++ b/docs/reference/plugins.md
@@ -3,12 +3,12 @@
Our plugin implementation is based off of [eslint's plugin implementation](https://github.com/eslint/eslint/blob/5018378131fd5190bbccca902c0cf4276ee1581a/lib/config/plugins.js);
Each plugin is an npm module with a name in the format of `commitlint-plugin-`, such as `commitlint-plugin-jquery`. You can also use scoped packages in the format of `@/commitlint-plugin-` such as `@jquery/commitlint-plugin-jquery`.
-### Rules in Plugins
+## Rules in Plugins
Plugins can expose additional rules for use in commitlint. To do so, the plugin must export a `rules` object containing a key-value mapping of rule ID to rule. The rule ID does not have to follow any naming convention (so it can just be `dollar-sign`, for instance).
```js
-module.exports = {
+export default {
rules: {
'dollar-sign': function (parsed, when, value) {
// rule implementation ...
@@ -19,7 +19,7 @@ module.exports = {
To use the rule in commitlint, you would use the unprefixed plugin name, followed by a slash, followed by the rule name. So if this plugin were named `commitlint-plugin-myplugin`, then in your configuration you'd refer to the rule by the name `myplugin/dollar-sign`. Example: `"rules": {"myplugin/dollar-sign": 2}`.
-### Peer Dependency
+## Peer Dependency
To make clear that the plugin requires commitlint to work correctly you have to declare commitlint as a `peerDependency` in your `package.json`.
The plugin support was introduced in commitlint version `7.6.0`. Ensure the `peerDependency` points to @commitlint `7.6.0` or later.
@@ -49,9 +49,10 @@ In case you want to develop your plugins locally without the need to publish to
### Usage Example
-```js
-// commitlint.config.js
-module.exports = {
+::: code-group
+
+```js [commitlint.config.js]
+export default {
rules: {
'hello-world-rule': [2, 'always'],
},
@@ -71,7 +72,7 @@ module.exports = {
};
```
-### Usage Example
+:::
```bash
> echo "feat: random subject" | commitlint # fails
diff --git a/docs/reference-prompt.md b/docs/reference/prompt.md
similarity index 94%
rename from docs/reference-prompt.md
rename to docs/reference/prompt.md
index 34ae6ea799..48a2ec9540 100644
--- a/docs/reference-prompt.md
+++ b/docs/reference/prompt.md
@@ -9,7 +9,7 @@ There are three fields: `settings`, `messages` and `questions`
Set optional options.
- `enableMultipleScopes`: `(boolean)` Enable multiple scopes, select scope with a radio list, disabled by default.
-- `scopeEnumSeparator`: `(string)` Commitlint supports [multiple scopes](./concepts-commit-conventions.md?id=multiple-scopes), you can specify the delimiter. It is applied when `enableMultipleScopes` set true.
+- `scopeEnumSeparator`: `(string)` Commitlint supports [multiple scopes](/concepts/commit-conventions#multiple-scopes), you can specify the delimiter. It is applied when `enableMultipleScopes` set true.
## `messages`
@@ -39,12 +39,10 @@ Specify the interactive steps, Steps can only be configured in
- `issues`
- `issuesBody`
-