feat(plugin-catalog): add catalog plugin (#60)

docs/.vuepress/config.ts

@@ -2,6 +2,7 @@ import { createRequire } from 'node:module'
 import process from 'node:process'
 import { viteBundler } from '@vuepress/bundler-vite'
 import { webpackBundler } from '@vuepress/bundler-webpack'
+import { catalogPlugin } from '@vuepress/plugin-catalog'
 // import { docsearchPlugin } from '@vuepress/plugin-docsearch'
 import { registerComponentsPlugin } from '@vuepress/plugin-register-components'
 import { searchPlugin } from '@vuepress/plugin-search'
@@ -67,6 +68,7 @@ export default defineUserConfig({
 
   // use plugins
   plugins: [
+    catalogPlugin(),
     // docsearchPlugin({
     //   appId: '34YFD9IUQ2',
     //   apiKey: '9a9058b8655746634e01071411c366b8',

docs/.vuepress/configs/navbar/en.ts

@@ -21,6 +21,7 @@ export const navbarEn: NavbarConfig = [
         text: 'Common Features',
         children: [
           '/plugins/back-to-top',
+          '/plugins/catalog',
           '/plugins/container',
           '/plugins/copy-code',
           '/plugins/copyright',

docs/.vuepress/configs/navbar/zh.ts

@@ -21,6 +21,7 @@ export const navbarZh: NavbarConfig = [
         text: '常用功能',
         children: [
           '/zh/plugins/back-to-top',
+          '/zh/plugins/catalog',
           '/zh/plugins/container',
           '/zh/plugins/copy-code',
           '/zh/plugins/copyright',

docs/.vuepress/configs/sidebar/en.ts

@@ -6,6 +6,7 @@ export const sidebarEn: SidebarConfig = {
       text: 'Common Features',
       children: [
         '/plugins/back-to-top',
+        '/plugins/catalog',
         '/plugins/container',
         '/plugins/copy-code',
         '/plugins/copyright',

docs/.vuepress/configs/sidebar/zh.ts

@@ -6,6 +6,7 @@ export const sidebarZh: SidebarConfig = {
       text: '常用功能',
       children: [
         '/zh/plugins/back-to-top',
+        '/zh/plugins/catalog',
         '/zh/plugins/container',
         '/zh/plugins/copy-code',
         '/zh/plugins/copyright',

docs/package.json

@@ -12,6 +12,7 @@
     "@vuepress/bundler-vite": "2.0.0-rc.5",
     "@vuepress/bundler-webpack": "2.0.0-rc.5",
     "@vuepress/plugin-back-to-top": "workspace:*",
+    "@vuepress/plugin-catalog": "workspace:*",
     "@vuepress/plugin-copy-code": "workspace:*",
     "@vuepress/plugin-docsearch": "workspace:*",
     "@vuepress/plugin-external-link-icon": "workspace:*",

docs/plugins/catalog.md

@@ -0,0 +1,256 @@
+# catalog
+
+<NpmBadge package="@vuepress/plugin-catalog" />
+
+The plugin can automatically generate catalog pages and provide catalog components.
+
+## Usage
+
+```bash
+npm i -D @vuepress/plugin-catalog@next
+```
+
+```ts
+import { catalogPlugin } from '@vuepress/plugin-catalog'
+
+export default {
+  plugins: [
+    catalogPlugin({
+      // Your options
+    }),
+  ],
+}
+```
+
+### Extracting Info
+
+First, you should set catalog info in routeMeta:
+
+```js title=".vuepress/config.js"
+import { catalogPlugin } from '@vuepress/plugin-catalog'
+
+export default {
+  extendsPage: (page) => {
+    // set catalog info in routeMeta
+    page.routeMeta = {
+      // catalog title
+      title: page.title,
+      // ... other information
+    }
+  },
+}
+```
+
+You can then import `defineCatalogInfoGetter` from `@vuepress/plugin-catalog/client` and use it in [client config file][client-config] to extract catalog info from meta.
+
+@tab JS
+
+```js title=".vuepress/client.js"
+import { defineCatalogInfoGetter } from '@vuepress/plugin-catalog/client'
+
+export default {
+  setup: () => {
+    defineCatalogInfoGetter((meta) =>
+      meta.title ? { title: meta.title } : null,
+    )
+  },
+}
+```
+
+Catalog info should contains:
+
+- `title`: catalog title
+- `order`: catalog order (optional)
+- `content`: catalog content component (optional)
+
+::: tip Sorting with order
+
+The plugin will sort pages by `order` in the following way:
+
+```:no-line-numbers
+// order positive numbers from small to large
+Project with order 1
+Project with order 2
+...
+Project with order 10
+...
+// Project without order
+Project without order
+Project without order
+...
+// order negative numbers from small to large
+Project with order -10
+// ...
+Project with order -2
+Project with order -1
+```
+
+:::
+
+## Using Catalog Component
+
+The plugin globally register and use `<Catalog />` component by default.
+
+- The `<Catalog />` will render 3 levels of pages as catalog items by default, and you can change the level depth by setting `level` option (max 3 levels).
+- To index to catalog item, add `index` prop.
+- By default, `<Catalog />` generates catalog for current folder. Set `base` props if you want catalog of another folder.
+
+You can use `<Catalog />` in your theme layout, or in your markdown files directly.
+
+If you want to use your own, you can register your component globally and set `component` option with your component name. Auto catalog page will use your component.
+
+## Config
+
+### level <Badge text="Built-in component only" />
+
+- Type: `1 | 2 | 3`
+- Default: `3`
+- Details: Max depth of catalog items.
+
+### index <Badge text="Built-in component only" />
+
+- Type: `boolean`
+- Default: `false`
+- Details: Whether show index for catalog
+
+### frontmatter
+
+- Type: `(path: string) => Record<string, any>`
+- Required: No
+- Details: Frontmatter getter for the generated page.
+- Example:
+
+  ```js title=".vuepress/config.js"
+  import { catalogPlugin } from '@vuepress/plugin-catalog'
+
+  export default {
+    plugins: [
+      catalogPlugin({
+        frontmatter: (path) => ({
+          // frontmatter you want
+          // you may customize title, author. time, etc.
+        }),
+      }),
+    ],
+  }
+  ```
+
+### exclude
+
+- Type: `(RegExp | string)[]`
+- Default: `[]`
+- Details:
+
+  Catalog page path to be excluded during generation.
+
+  - `"/foo/"` means only exclude catalog page generation at `/foo/` folder.
+  - `/^\/foo\//` means exclude catalog page generation at `/foo/` folder and its subfolders.
+
+  ::: tip 404 pages will be automatically excluded.
+
+  :::
+
+### component
+
+- Type: `string`
+- Required: No
+- Details: Component name to use as catalog.
+
+### locales
+
+- Type: `CatalogLocaleConfig`
+
+  ```ts
+  interface CatalogLocaleData {
+    /**
+     * Catalog title
+     */
+    title: string
+
+    /**
+     * Empty hint
+     */
+    empty: string
+  }
+
+  interface CatalogLocaleConfig {
+    [localePath: string]: CatalogLocaleData
+  }
+  ```
+
+- Required: No
+
+- Details: Locales config for catalog component.
+
+::: details Built-in Supported Languages
+
+- **Simplified Chinese** (zh-CN)
+- **Traditional Chinese** (zh-TW)
+- **English (United States)** (en-US)
+- **German** (de-DE)
+- **German (Australia)** (de-AT)
+- **Russian** (ru-RU)
+- **Ukrainian** (uk-UA)
+- **Vietnamese** (vi-VN)
+- **Portuguese (Brazil)** (pt-BR)
+- **Polish** (pl-PL)
+- **French** (fr-FR)
+- **Spanish** (es-ES)
+- **Slovak** (sk-SK)
+- **Japanese** (ja-JP)
+- **Turkish** (tr-TR)
+- **Korean** (ko-KR)
+- **Finnish** (fi-FI)
+- **Indonesian** (id-ID)
+- **Dutch** (nl-NL)
+
+:::
+
+## Client options
+
+### defineCatalogInfoGetter
+
+```ts
+interface CatalogInfo {
+  /** Catalog title */
+  title: string
+  /** Catalog order */
+  order?: number
+  /** Catalog content */
+  content?: Component
+}
+
+type CatalogInfoGetter = (meta: Record<string, unknown>) => CatalogInfo | null
+
+const defineCatalogInfoGetter: (options: CatalogInfoGetter) => void
+```
+
+Customize how to extract catalog info from meta.
+
+## Catalog Component Props
+
+### base
+
+- Type: `string`
+- Default: Folder of current route path
+- Details: Catalog Base
+
+### level
+
+- Type: `1 | 2 | 3`
+- Default: `3`
+- Details: Max level of catalog.
+
+### index
+
+- Type: `boolean`
+- Default: `false`
+- Details: Whether display index number for catalog.
+
+### hideHeading
+
+- Type: `boolean`
+- Default: `false`
+- Details: Whether hide `Category` title.
+
+[client-config]: https://vuejs.press/guide/configuration.html#client-config-file

docs/themes/default/README.md

@@ -1,4 +1,6 @@
-# Usage
+# theme-default
+
+## Usage
 
 <NpmBadge package="@vuepress/theme-default" />