docs: use vitepress

.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/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,87 @@
+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: 'API', link: '/api'},
+					{text: 'Plugins', link: '/plugins'},
+					{text: 'Prompt', link: '/prompt'},
+					{text: 'Examples', link: '/examples'},
+					{text: 'Community projects', link: '/community-projects'},
+				],
+			},
+			{
+				text: 'Concepts',
+				base: '/concepts',
+				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;

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)

docs/concepts-commit-conventions.md → 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?

docs/concepts-shareable-config.md → docs/concepts/shareable-config.md

@@ -3,16 +3,33 @@
 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.
+```ts [commitlint.config.ts]
+import type {UserConfig} from '@commitlint/types';
+
+const config: UserConfig = {
+  extends: ['example'], // => commitlint-config-example
+};
+
+export default config;
+```
+
+:::
+
+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,15 +41,33 @@ 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]
+/**
+ * @type {import('@commitlint/types').UserConfig}
+ */
+export default {
   extends: ['./example'], // => ./example.js
 };
 ```
 
+```ts [commitlint.config.ts]
+import type {UserConfig} from '@commitlint/types';
+
+const config: UserConfig = {
+  extends: ['./example'], // => ./example.js
+};
+
+export default config;
+```
+
+:::
+
 ## Scoped packages
 
 When using scoped packages you have two options.