docs: use vitepress

.github/CONTRIBUTING.md

@@ -78,6 +78,18 @@ yarn test
 
 (Partly outdated)
 
+## Documentation update
+
+Documentation uses `vitepress`.
+To run and edit teh documentation locally run:
+
+```sh
+yarn install
+yarn build-dev
+```
+
+For more information refer to [vitepress documentation](https://vitepress.dev).
+
 ## Publishing a release
 
 ```sh

.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

@@ -9,6 +9,22 @@ import rules from './index.js';
 
 const __dirname = path.resolve(fileURLToPath(import.meta.url), '..');
 
+function _glob(pattern: string) {
+	const files = globSync(pattern, {
+		ignore: ['**/index.ts', '**/*.test.ts'],
+		cwd: __dirname,
+	});
+	return files.map(relative).map(toExport);
+}
+
+function relative(filePath: string) {
+	return path.relative(__dirname, filePath);
+}
+
+function toExport(fileName: string) {
+	return path.basename(fileName, path.extname(fileName));
+}
+
 test('exports all rules', () => {
 	const expected = _glob('*.ts').sort();
 	const actual = Object.keys(rules).sort();
@@ -22,29 +38,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));
 });
-
-function _glob(pattern: string) {
-	const files = globSync(pattern, {
-		ignore: ['**/index.ts', '**/*.test.ts'],
-		cwd: __dirname,
-	});
-	return files.map(relative).map(toExport);
-}
-
-function relative(filePath: string) {
-	return path.relative(__dirname, filePath);
-}
-
-function toExport(fileName: string) {
-	return path.basename(fileName, path.extname(fileName));
-}

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/format', link: '/format'},
+					{text: '@commitlint/lint', link: '/lint'},
+					{text: '@commitlint/load', link: '/load'},
+					{text: '@commitlint/read', link: '/read'},
+				],
+			},
+			{
+				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;