feat(auto-catalog): add component and level option

docs/auto-catalog/src/config.md

@@ -3,6 +3,26 @@ title: Options
 icon: config
 ---
 
+## component
+
+- Type: `string`
+- Default: `"AutoCatalog"`
+
+Catalog component name.
+
+## level
+
+- Type: `1 | 2 | 3`
+- Default: `3`
+
+Max depth of Catalog items level.
+
+::: note
+
+Only available when you use the built-in catalog component.
+
+:::
+
 ## exclude
 
 - Type: `(RegExp | string)[]`

docs/auto-catalog/src/guide.md

@@ -5,6 +5,12 @@ icon: creative
 
 With `vuepress-plugin-auto-catalog`, you can easily gets automatically generated catalog pages for your theme.
 
+## Catalog Component
+
+The plugin register and use `<AutoCatalog />` component by default, if you want to use your own component, you can set `component` option with your component name.
+
+The default `<AutoCatalog />` will render 3 levels of pages as catalog items, and you can change the level depth by setting `level` option (Only `1` `2` and `3` are supported).
+
 ## Excluding pages
 
 There may be some cases you have a `/foo/bar.md`, but do not want to generate a catalog page at `/foo/`, in this case, you can use `exclude` option to exclude the page.

docs/auto-catalog/src/zh/config.md

@@ -3,6 +3,26 @@ title: 选项
 icon: config
 ---
 
+## component
+
+- 类型: `string`
+- 默认值: `"AutoCatalog"`
+
+目录组件名称。
+
+## level
+
+- 类型: `1 | 2 | 3`
+- 默认值: `3`
+
+目录项级别的最大深度。
+
+::: note
+
+仅在你使用内置目录组件时可用。
+
+:::
+
 ## exclude
 
 - 类型: `(RegExp | string)[]`

docs/auto-catalog/src/zh/guide.md

@@ -5,6 +5,12 @@ icon: creative
 
 使用 `vuepress-plugin-auto-catalog`，你可以轻松地为你的主题自动生成目录页面。
 
+## 目录组件
+
+插件默认注册并使用`<AutoCatalog />`组件，如果你想使用自己的组件，可以设置 `component` 选项为你的组件名称。
+
+默认的 `<AutoCatalog />` 会将 3 层页面呈现为目录项，您可以通过设置 `level` 选项来更改层次深度 (仅支持 `1` `2` 和 `3`)。
+
 ## 排除页面
 
 可能有一些情况你有一个 `/foo/bar.md`，但不想在 `/foo/` 生成目录页面，在这种情况下，你可以使用 `exclude` 选项来排除该页面。

packages/auto-catalog/src/client/config.ts

@@ -1,10 +1,17 @@
 import { defineClientConfig } from "@vuepress/client";
 import { hasGlobalComponent } from "vuepress-shared/client";
-import Catalog from "vuepress-plugin-components/client/components/Catalog.js";
+
+declare const SHOULD_REGISTER_AUTO_CATALOG_COMPONENT: boolean;
 
 export default defineClientConfig({
   enhance: ({ app }) => {
-    if (!hasGlobalComponent("AutoCatalog", app))
-      app.component("AutoCatalog", Catalog);
+    if (
+      SHOULD_REGISTER_AUTO_CATALOG_COMPONENT &&
+      !hasGlobalComponent("AutoCatalog", app)
+    )
+      app.component(
+        "AutoCatalog",
+        () => import("vuepress-plugin-components/client/components/Catalog.js")
+      );
   },
 });

packages/auto-catalog/src/node/autoCatalog.ts

@@ -8,8 +8,10 @@ import type { AutoCatalogOptions } from "./options.js";
 export const generateCatalog = async (
   app: App,
   {
+    component = "AutoCatalog",
     exclude = [],
     frontmatter = (): PageFrontmatter => ({}),
+    level = 3,
   }: AutoCatalogOptions
 ): Promise<void> => {
   const {
@@ -18,6 +20,9 @@ export const generateCatalog = async (
   } = app;
 
   const pathToBeGenerated = new Set<string>();
+  const content = `\
+<${component}${[1, 2].includes(level) ? ` :level="${level}"` : ""} />
+`;
 
   pages.forEach(({ path: pagePath, pathLocale }) => {
     let catalogPath = pagePath;
@@ -46,13 +51,11 @@ export const generateCatalog = async (
       const title = getTitleFromFilename(basename);
 
       return createPage(app, {
-        content: `\
-<AutoCatalog />
-`,
         frontmatter: {
           title,
           ...(frontmatter(catalogPath) || {}),
         },
+        content,
         path: catalogPath,
       });
     })

packages/auto-catalog/src/node/options.ts

@@ -22,4 +22,30 @@ export interface AutoCatalogOptions {
    * @returns 页面 Frontmatter
    */
   frontmatter?: (path: string) => PageFrontmatter;
+
+  /**
+   * The max level of the generated catalog
+   *
+   * @description Available with built-in component, only support 1,2,3
+   *
+   * 生成的目录最大层级
+   *
+   * @description 仅支持内置组件，仅支持 1,2,3
+   *
+   * @default 3
+   */
+  level?: number;
+
+  /**
+   * Component name to use as catalog
+   *
+   * @description By default the plugin will register an `<AutoCatalog />` component and use interface. If you want to use your own component, you can set this option to the name of your component.
+   *
+   * 用作目录的组件名称
+   *
+   * @description 默认情况下，插件将注册一个 `<AutoCatalog />` 组件并使用该组件。如果您想使用自己的组件，可以将此选项设置为您的组件的名称。
+   *
+   * @default 'AutoCatalog'
+   */
+  component?: string;
 }

packages/auto-catalog/src/node/plugin.ts

@@ -13,6 +13,11 @@ export const autoCatalogPlugin =
     return {
       name: "vuepress-plugin-auto-catalog",
 
+      define: (): Record<string, unknown> => ({
+        SHOULD_REGISTER_AUTO_CATALOG_COMPONENT:
+          options.component === "AutoCatalog" || !options.component,
+      }),
+
       onInitialized: async (app): Promise<void> =>
         generateCatalog(app, options),