feat(auto-catalog): rebuild

vuepress-theme-hope · Nov 29, 2023 · e0911ea · e0911ea
1 parent 1756782
commit e0911ea
Show file tree

Hide file tree

Showing 22 changed files with 582 additions and 594 deletions.
diff --git a/docs/auto-catalog/src/config.md b/docs/auto-catalog/src/config.md
@@ -41,34 +41,6 @@ Page paths excluding from auto generation.
 
 Page Frontmatter generator.
 
-### titleGetter
-
-- Type: `(page: Page) => string`
-- Default: `(page: Page) => page.title`
-
-Page title getter
-
-### iconGetter
-
-- Type: `(page: Page) => string`
-- Required: No
-
-Page icon getter
-
-### orderGetter
-
-- Type: `(page: Page) => string`
-- Required: No
-
-Page order getter
-
-### shouldIndex
-
-- Type: `(page: Page) => boolean`
-- Default: `() => true`
-
-Whether page should be indexed getter
-
 ### component
 
 - Type: `string`
@@ -128,18 +100,28 @@ Locales config for catalog component.
 
 ## Client options
 
-### defineAutoCatalogIconComponent
+### defineAutoCatalogGetter
 
 ```ts
-export type AutoCatalogIconComponent = Component<{
-  icon: string;
-}>;
-export declare const defineAutoCatalogIconComponent: (
-  options: AutoCatalogIconComponent,
+export interface AutoCatalogInfo {
+  /** Catalog title */
+  title: string;
+  /** Catalog order */
+  order?: number;
+  /** Catalog content */
+  content?: Component;
+}
+
+export type AutoCatalogInfoGetter = (
+  meta: Record<string, unknown>,
+) => AutoCatalogInfo | null;
+
+export declare const defineAutoCatalogGetter: (
+  options: AutoCatalogInfoGetter,
 ) => void;
 ```
 
-Customize icon component for auto catalog.
+Customize how to extract catalog info from meta.
 
 ## AutoCatalog Component Props
 

diff --git a/docs/auto-catalog/src/guide.md b/docs/auto-catalog/src/guide.md
@@ -7,31 +7,116 @@ With `vuepress-plugin-auto-catalog`, you can easily get automatically generated
 
 <!-- more -->
 
-## Controlling Catalog
-
-You can set `shouldIndex`, `titleGetter` and `orderGetter` in plugin options to control catalog generation. They all accept functions which receives `Page` object as first argument.
-
-- `shouldIndex` returns a boolean value, if the function returns `false`, the page will be ignored, otherwise, the page will be indexed.
-- `titleGetter` returns a string value, the string value will be used as the page title, by default the plugin will use `page.title`.
-- `orderGetter` returns a number value if possible, order sequence is as follows:
-
-  ```: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
-  ```
+## Extracting Info
+
+First, you should set catalog info in routeMeta:
+
+::: code-tabs#language
+
+@tab TS
+
+```ts
+// .vuepress/config.ts
+import { defineUserConfig } from "vuepress";
+
+export default defineUserConfig({
+  extendsPage: (page) => {
+    // set catalog info in routeMeta
+    page.routeMeta = {
+      // catalog title
+      title: page.title,
+      // ... other information
+    };
+  },
+});
+```
+
+@tab JS
+
+```js
+// .vuepress/config.js
+import { autoCatalogPlugin } from "vuepress-plugin-auto-catalog";
+
+export default {
+  extendsPage: (page) => {
+    // set catalog info in routeMeta
+    page.routeMeta = {
+      // catalog title
+      title: page.title,
+      // ... other information
+    };
+  },
+};
+```
+
+:::
+
+You can then import `defineAutoCatalogGetter` from `vuepress-plugin-auto-catalog/client` and use it in client config file to extract catalog info from meta.
+
+::: code-tabs#language
+
+@tab TS
+
+```ts
+// .vuepress/client.ts
+import { defineClientConfig } from "@vuepress/client";
+import { defineAutoCatalogGetter } from "vuepress-plugin-auto-catalog/client";
+
+export default defineClientConfig({
+  setup: () => {
+    defineAutoCatalogGetter((meta) =>
+      meta.title ? { title: meta.title } : null,
+    );
+  },
+});
+```
+
+@tab JS
+
+```js
+// .vuepress/client.js
+import { defineAutoCatalogGetter } from "vuepress-plugin-auto-catalog/client";
+
+export default {
+  setup: () => {
+    defineAutoCatalogGetter((meta) =>
+      meta.title ? { title: meta.title } : null,
+    );
+  },
+};
+```
+
+:::
+
+Catalog info should contains:
+
+- `title`: catalog title
+- `order`: catalog order (optional)
+- `content`: catalog content component (optional)
+
+::: info 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
+```
+
+:::
 
 ## Excluding pages
 
@@ -137,42 +222,3 @@ By default, `<AutoCatalog />` generates catalog for current folder. If you want
 You can use `<AutoCatalog />` in your theme layout, or in your markdown files directly.
 
 If you do not like the built-in component and 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.
-
-## Displaying Icons for Catalog
-
-You can import `defineAutoCatalogIconComponent` from `vuepress-plugin-auto-catalog/client` and use it in client config file to define a component for catalog icon.
-
-The component should accept a `icon` prop which is the icon value.
-
-::: code-tabs#language
-
-@tab TS
-
-```ts
-// .vuepress/client.ts
-import { defineClientConfig } from "@vuepress/client";
-import { defineAutoCatalogIconComponent } from "vuepress-plugin-auto-catalog/client";
-import MyIconComponent from "./components/MyIconComponent.vue";
-
-export default defineClientConfig({
-  setup: () => {
-    defineAutoCatalogIconComponent(MyIconComponent);
-  },
-});
-```
-
-@tab JS
-
-```js
-// .vuepress/client.js
-import { defineAutoCatalogIconComponent } from "vuepress-plugin-auto-catalog/client";
-import MyIconComponent from "./components/MyIconComponent.vue";
-
-export default {
-  setup: () => {
-    defineAutoCatalogIconComponent(MyIconComponent);
-  },
-};
-```
-
-:::
diff --git a/docs/auto-catalog/src/migration.md b/docs/auto-catalog/src/migration.md
@@ -9,14 +9,6 @@ You can pass the second argument `true` to enable legacy mode when calling `auto
 
 ## Changes in Pre-released Versions
 
-- `getTitle` is renamed to `titleGetter`
-
-- `getIcon` is renamed to `iconGetter`
-
-- `getOrder` is renamed to `orderGetter`
-
-- `getIndex` is renamed to `indexGetter`
-
-- `iconComponent` is removed in favor of [defineAutoCatalogIconComponent](./config.md#defineautocatalogiconcomponent)
+- `getTitle`, `titleGetter`, `getIcon`, `iconGetter`, `getOrder`, `orderGetter`, `getIndex`, `indexGetter`, `iconComponent`. `defineAutoCatalogIconComponent` are replaced by [`defineAutoCatalogGetter`](./config.md#defineautocataloggetter).
 
 - We support `indexType` as component prop for a couple of versions and remove it has we no longer need it.
diff --git a/docs/auto-catalog/src/zh/config.md b/docs/auto-catalog/src/zh/config.md
@@ -41,34 +41,6 @@ icon: gears
 
 控制页面 Frontmatter。
 
-### titleGetter
-
-- 类型: `(page: Page) => string`
-- 默认值: `(page: Page) => page.title`
-
-页面标题获取器
-
-### iconGetter
-
-- 类型: `(page: Page) => string`
-- 必填: 否
-
-页面图标获取器
-
-### orderGetter
-
-- 类型: `(page: Page) => string`
-- 必填: 否
-
-页面顺序获取器
-
-### shouldIndex
-
-- 类型: `(page: Page) => boolean`
-- 默认值: `() => true`
-
-页面是否应该被索引
-
 ### component
 
 - 类型: `string`
@@ -130,18 +102,28 @@ icon: gears
 
 ## 客户端选项
 
-### defineAutoCatalogIconComponent
+### defineAutoCatalogGetter
 
 ```ts
-export type AutoCatalogIconComponent = Component<{
-  icon: string;
-}>;
-export declare const defineAutoCatalogIconComponent: (
-  options: AutoCatalogIconComponent,
+export interface AutoCatalogInfo {
+  /** 目录标题 */
+  title: string;
+  /** 目录顺序 */
+  order?: number;
+  /** 目录内容 */
+  content?: Component;
+}
+
+export type AutoCatalogInfoGetter = (
+  meta: Record<string, unknown>,
+) => AutoCatalogInfo | null;
+
+export declare const defineAutoCatalogGetter: (
+  options: AutoCatalogInfoGetter,
 ) => void;
 ```
 
-自定义目录图标组件。
+自定义如何从 meta 中提取目录信息。
 
 ## AutoCatalog 组件属性