docs: use vitepress (#3921)

* docs: use vitepress

* docs: update src docs references

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

.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

.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

@commitlint/cli/README.md

@@ -1,16 +1,11 @@
-> Lint commit messages
+# @commitlint/cli
 
 <p align="center">
-  <img width="750" src="https://conventional-changelog.github.io/commitlint/assets/commitlint.svg">
+  <img width="750" src="https://commitlint.js.org/assets/commitlint.svg">
 </p>
 
-# @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.

@commitlint/cli/src/cli.ts

@@ -306,7 +306,7 @@ async function main(args: MainArgs): Promise<void> {
 					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'),
 				},

@commitlint/config-angular/README.md

@@ -1,23 +1,23 @@
-> 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).
 
 ## Getting started
 
 ```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
 
 ### 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
 

@commitlint/config-conventional/README.md

@@ -1,15 +1,15 @@
-> 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).
 
 ## Getting started
 
 ```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
 

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

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

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

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

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

@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