docs: use vitepress

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

@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));
 });

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);
+		},
+	},
+});

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;