📃 docs: 文档更新

Author: 白云苍狗

demo/[tags].paths.ts

@@ -3,6 +3,8 @@ import config from './.vitepress/config';
 
 export default {
 	async paths() {
-		return dynamicPages(config, 'tags');
+		const paths = await dynamicPages(config, 'tags');
+		console.log(paths);
+		return paths;
 	},
 };

docs/.vitepress/assets/log.json

@@ -2,6 +2,56 @@
 	{
 		"large_version": "v0.0.x",
 		"children": [
+			{
+				"version": "0.0.17",
+				"date": "2024-09-27",
+				"logs": [
+					{
+						"type": "feat",
+						"text": "分页生成静态文件"
+					},
+					{
+						"type": "style",
+						"text": "样式优化"
+					},
+					{
+						"type": "perf",
+						"text": "将 fjGallery  插件初始化放到相册详情组件内"
+					}
+				]
+			},
+			{
+				"version": "0.0.16",
+				"date": "2024-09-11",
+				"logs": [
+					{
+						"type": "style",
+						"text": "样式优化"
+					},
+					{
+						"type": "refactor",
+						"text": "原文地址取值调整"
+					}
+				]
+			},
+			{
+				"version": "0.0.15",
+				"date": "2024-09-05",
+				"logs": [
+					{
+						"type": "fix",
+						"text": "分页时 route.path 无变动"
+					},
+					{
+						"type": "fix",
+						"text": "页面无法提取出目录时报错"
+					},
+					{
+						"type": "fix",
+						"text": "子路径下图标头像兼容"
+					}
+				]
+			},
 			{
 				"version": "0.0.14",
 				"date": "2024-08-29",

docs/guide/config.md

@@ -513,17 +513,69 @@ export default defineConfig({
 ```ts [config.ts]
 export default defineConfig({
 	themeConfig: {
-		indexGenerator: { // [!code ++]
+		indexGenerator: {
 			perPage: 8, // [!code ++]
-			// ...  // [!code ++]
-		} // [!code ++]
+		}
 	}
 });
 ```
 
 <<< @/../packages/vitepress-theme-async/types/theme.d.ts#IndexGeneratorConfig
 :::
 
+默认情况下，生成的分页是伪分页，通过 URL 参数前端实现的分页，并不会按照分页生成对应 .html 文件。
+
+如果需要按分页生成静态文件需要开启 `static` 配置，然后将 `index.md` 改名为 `[index].md`，并添加 `[index].paths.ts` 文件，调用主题 `dynamicPages` 方法动态添加分页路由。
+
+::: code-group
+
+```ts [config.ts]
+export default defineConfig({
+	themeConfig: {
+		indexGenerator: {
+			static: true, // [!code ++]
+		}
+	}
+});
+```
+
+```txt [博客目录]
+.
+├─ .vitepress
+├─ posts
+│  └─ ...
+├─ index.md // [!code --]
+├─ [index].md // [!code ++]
+├─ [index].paths.ts // [!code ++]
+├─ ...
+```
+
+```ts [[index].paths.ts]
+import { dynamicPages } from 'vitepress-theme-async/plugin/page';
+import config from './.vitepress/config';
+
+export default {
+	async paths() {
+		return dynamicPages(config, 'index');
+	},
+};
+
+```
+
+```txt [对比]
+# 静态模式访问路径
+https://xxx				// 首页
+https://xxx/page/2		// 第二页
+https://xxx/page/3		// 第三页
+
+# 普通模式访问路径
+https://xxx				// 首页
+https://xxx?page=2		// 第二页
+https://xxx?page=3		// 第三页
+```
+
+:::
+
 #### 归档分页
 
 归档分配置后，同时也会对`分类页`和`标签页`生效。
@@ -535,17 +587,61 @@ export default defineConfig({
 ```ts [config.ts]
 export default defineConfig({
 	themeConfig: {
-		archiveGenerator: { // [!code ++]
+		archiveGenerator: {
 			style: 'less', // [!code ++]
-			// ...  // [!code ++]
-		} // [!code ++]
+		}
 	}
 });
 ```
 
 <<< @/../packages/vitepress-theme-async/types/theme.d.ts#ArchiveGeneratorConfig
 :::
 
+归档分类页与首页一样，默认情况下，生成的分页是伪分页，通过 URL 参数前端实现的分页，并不会按照分页生成对应 .html 文件。
+
+如果需要按分页生成静态文件需要开启 static 配置，然后将 `archives|categories|tags.md` 改名为 `[archives|categories|tags].md`，并添加 `[archives|categories|tags].paths.ts` 文件，调用主题 dynamicPages 方法动态添加分页路由。
+
+::: code-group
+
+```ts [config.ts]
+export default defineConfig({
+	themeConfig: {
+		archiveGenerator: {
+			static: true, // [!code ++]
+		}
+	}
+});
+```
+
+```txt [博客目录]
+.
+├─ .vitepress
+├─ posts
+│  └─ ...
+├─ archives.md // [!code --]
+├─ [archives].md // [!code ++]
+├─ [archives].paths.ts // [!code ++]
+├─ categories.md // [!code --]
+├─ [categories].md // [!code ++]
+├─ [categories].paths.ts // [!code ++]
+├─ tags.md // [!code --]
+├─ [tags].md // [!code ++]
+├─ [tags].paths.ts // [!code ++]
+├─ ...
+```
+
+:::
+
+如果开启了分页生成静态文件，文件的路由会根据 `page` 配置生成路由，以 `tags` 为例
+
+| 配置路径    | 第一页路径       | 其他页路径        | 子级第一页      | 子级其他页路径         |
+| :---------- | :--------------- | :---------------- | :-------------- | :--------------------- |
+| /           | /index.html      | /page/2.html      | /子级.html      | /子级/page/2.html      |
+| /index      | /index.html      | /page/2.html      | /子级.html      | /子级/page/2.html      |
+| /tags       | /tags.html       | /tags/page/2.html | /tags/子级.html | /tags/子级/page/2.html |
+| /tags/      | /tags/index.html | /tags/page/2.html | /tags/子级.html | /tags/子级/page/2.html |
+| /tags/index | /tags/index.html | /tags/page/2.html | /tags/子级.html | /tags/子级/page/2.html |
+
 ### 分类卡片
 
 首页中显示的分类卡片。

docs/guide/page.md

@@ -67,12 +67,12 @@ date: 2019-11-20 10:16:09
 ```ts [config.ts]
 export default defineConfig({
 	themeConfig: {
-	page: {// [!code ++]
+	page: {
 			archives: '/archives',// [!code ++]
 			categories: '/categories',// [!code ++]
 			tags: '/tags',// [!code ++]
-		}// [!code ++]
-	},// [!code ++]
+		}
+	},
 });
 ```
 
@@ -251,7 +251,6 @@ single_column: true
 
 `TrmGallery` 相册详情组件，可以通过 `srcs` 传入图片列表。`TrmGallery` 为主题内置 [全局组件](https://vitepress-theme-async.imalun.com/guide/config#%E5%85%A8%E5%B1%80%E7%BB%84%E4%BB%B6)，默认未开启。
 
-
 ```md
 ---
 title: 壁纸