完善 docs

docs/docs/start-guide/breaking-change.md

@@ -7,7 +7,7 @@ description: "一般情况下都不需要了解。"
 
 在贡献指南中我们提到过会尽量不引入破坏性变更，或任何与原版引擎有不同的地方。
 
-但有些变化难以避免，在这里你可以检查所有变更，评估是否会造成巨大的影响。
+但有些变化难以避免，在这里你可以对变更进行评估是否会对项目造成巨大的影响。
 
 ---
 ### 默认禁用原生 TTF 渲染器

docs/docs/theory-guide/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "原理文档",
+  "position": 5,
+  "collapsed": true,
+  "link": {
+    "type": "doc",
+    "id": "theory-guide-intro"
+  }
+}

docs/docs/theory-guide/dynamic-batcher-theory.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 2
+description: "详细了解动态合图的实现方式。"
+---
+
+# 动态合图
+
+TODO

docs/docs/theory-guide/multi-theory.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 1
+description: "详细了解多纹理渲染的实现方式。"
+---
+
+# 多纹理渲染
+
+TODO

docs/docs/theory-guide/theory-guide-intro.mdx

@@ -0,0 +1,6 @@
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+# 原理文档
+
+TODO

docs/docs/uninstall-guide.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # 卸载指南

docs/docs/update-log.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # 更新日志

docs/docs/user-guide/dynamic-batcher/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "动态合图",
-  "position": 2,
+  "position": 3,
   "collapsed": true,
   "link": {
     "type": "doc",

docs/docs/user-guide/dynamic-batcher/dynamic-batcher-intro.mdx

@@ -1,10 +1,8 @@
----
-hide_title: true
-title: 动态合图
----
 import DocCardList from '@theme/DocCardList';
 import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
+# 动态合图
+
 我们基本重构了动态合图系统，在原有的功能基础上，增加了以下重要特性：
 
 - **完全开放所有接口**，以方便如果你想手动规划或控制动态图集

docs/docs/user-guide/dynamic-batcher/dynamic-batcher-manual.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 2
+description: "随心所欲地控制动态合图的使用。"
 ---
 
 # 手动管理合图

docs/docs/user-guide/dynamic-batcher/dynamic-batcher-settings.md

@@ -1,8 +1,9 @@
 ---
 sidebar_position: 1
+description: "更细致地控制动态合图的使用。"
 ---
 
-# 新增的合图设置
+# 新的合图设置
 
 ## 全局设置
 

docs/docs/user-guide/multi-render/multi-batcher.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 2
+description: "了解如何手动进行多纹理合批。"
+---
+
+# 多纹理合批
+
+着重介绍管理器。

docs/docs/user-guide/multi-render/multi-material.md

@@ -1,6 +1,17 @@
 ---
 sidebar_position: 1
+description: "了解实现多纹理渲染的基础。"
 ---
 
 # 多纹理材质
 
+当我们说 “多纹理材质” 时，指的是持有 `cc.sp.MultiHandler` 实例的材质。
+
+并且使用内置多纹理 Effect 着色器的材质会自动持有一个 `cc.sp.MultiHandler` 实例。
+
+也就是说**使用自行创建的有多个纹理插槽着色器的材质不会被直接识别为多纹理材质。**
+
+:::tip
+
+
+##

docs/docs/user-guide/multi-render/multi-render-intro.mdx

@@ -1,33 +1,43 @@
----
-hide_title: true
-title: 多纹理渲染
----
 import DocCardList from '@theme/DocCardList';
 import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
-我们在引擎中**内置两种多纹理 Effect 着色器资源**（分别是 8 纹理插槽与 16 纹理插槽）。
+# 多纹理渲染
 
-并增加**原生支持多纹理材质**的能力，也就是说你无需编写任何代码即可在支持的渲染组件中直接使用多纹理材质。
+多纹理渲染在 [新 UI 渲染批次合并指南](../../start-guide/batcher-guide#什么是多纹理渲染) 中有所介绍。
 
-:::info 支持的渲染组件
+其原理非常简单，但是为了让它能以最简单的方式在引擎中使用，所以还进行了一些封装。
+
+---
+## 原生支持多纹理材质
+
+:::info 提示
+
+- **支持的渲染组件**
 
     cc.Sprite、cc.Label、cc.RichText、cc.MotionSteak、Spine 组件。
 
-:::
+- **不支持的渲染组件**
 
-:::caution 不支持的渲染组件
+    cc.ParticleSystem、TiledMap 组件：这两个组件当前的引擎实现会强制打断合批，暂时不支持。
 
-cc.ParticleSystem 与 TiledMap 组件，这两个组件引擎的实现会强制打断合批，所以暂不支持。
-
-cc.Label 使用 TTF 字体文件并使用 Char 缓存模式时，引擎内部会使用原生实现的 TTF 渲染器，由于该原生渲染器可以禁用，并且可能导致不同平台渲染效果不一致的问题，所以结合我们的人力较少的原因，暂未去进行适配，服务包会默认禁用，在实际使用上没有差别，但欢迎提交 PR 帮助我们适配该渲染器。
+    DragonBones 组件：因人力有限，并且这个组件与 Spine 组件可以相互代替，所以暂时不支持该组件。
 
 :::
 
-在这个基础上，我们增加了一个**多纹理合批管理器**，一般情况下你并不会接触到它，但是它是我们开发**动态合图的自动多纹理合批**的基础。
+服务包在引擎内置了可以直接使用的多纹理 Effect 着色器资源，并且你可以直接使用多纹理材质而不需要编写任何代码。
 
-:::tip 无需关注
+具体可阅读 [多纹理材质](./multi-material) 文档。
 
-**如果你并不是要（一般情况下也不需要）手动使用多纹理材质或者多纹理合批管理器，请跳过本节文档**，阅读其它内容。
+---
+## 自动切换材质
+
+在大部分时候，我们都不希望你需要手动去设置多纹理材质，比如当组件的纹理加入动态图集后，能自动切换为与动态图集纹理关联的多纹理材质，所以为每个组件都加入了自动切换材质的特性。
+
+这个机制的实现离不开多纹理合批管理器，具体可阅读 [多纹理合批](./multi-batcher) 文档。
+
+:::tip 提示
+
+多纹理渲染属底层设施，如果你并不是要手动使用多纹理材质或者多纹理合批管理器，请跳过本特性文档。
 
 :::
 

docs/docs/user-guide/spine/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Spine",
+  "position": 4,
+  "collapsed": true,
+  "link": {
+    "type": "doc",
+    "id": "spine-intro"
+  }
+}

docs/docs/user-guide/spine/spine-intro.mdx

@@ -0,0 +1,21 @@
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+# Spine
+
+我们基本重构了动态合图系统，在原有的功能基础上，增加了以下重要特性：
+
+- **完全开放所有接口**，以方便如果你想手动规划或控制动态图集
+- **增加默认是否参与动态合图的全局设置，并支持设置单个组件是否参与动态合图**
+- **支持自动加入多纹理合批**
+- **优化图集装箱算法**（使用 Guillotine）
+- **支持复用废弃的空间**
+- **所有图集作为一个整体进行管理**（不再出现纹理被加入到两张图集的情况）
+
+:::tip 提示
+
+你可以阅读官方文档来了解怎么使用 [动态合图](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/dynamic-atlas.html)，由于动态合图的使用本来就是自动的，所以如果没有特殊需求则**不需要阅读后面的内容**。
+
+:::
+
+<DocCardList items={useCurrentSidebarCategory().items}/>

docs/docs/user-guide/spine/spine-skin.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 2
+description: "随心所欲地控制动态合图的使用。"
+---
+
+# 换装
+
+TODO

docs/docs/user-guide/text-render/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "文本渲染",
+  "position": 2,
+  "collapsed": true,
+  "link": {
+    "type": "doc",
+    "id": "text-render-intro"
+  }
+}

docs/docs/user-guide/text-render/text-char-mode.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 1
+description: "详细了解该缓存模式重构后的所有新特性。"
+---
+
+# 新的 Char 缓存模式
+
+TODO

docs/docs/user-guide/text-render/text-high-dpi.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 2
+description: "一行代码开启高清文本渲染。"
+---
+
+# 高 DPI 支持
+
+TODO

docs/docs/user-guide/text-render/text-render-intro.mdx

@@ -0,0 +1,21 @@
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+# 文本渲染
+
+我们基本重构了动态合图系统，在原有的功能基础上，增加了以下重要特性：
+
+- **完全开放所有接口**，以方便如果你想手动规划或控制动态图集
+- **增加默认是否参与动态合图的全局设置，并支持设置单个组件是否参与动态合图**
+- **支持自动加入多纹理合批**
+- **优化图集装箱算法**（使用 Guillotine）
+- **支持复用废弃的空间**
+- **所有图集作为一个整体进行管理**（不再出现纹理被加入到两张图集的情况）
+
+:::tip 提示
+
+你可以阅读官方文档来了解怎么使用 [动态合图](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/dynamic-atlas.html)，由于动态合图的使用本来就是自动的，所以如果没有特殊需求则**不需要阅读后面的内容**。
+
+:::
+
+<DocCardList items={useCurrentSidebarCategory().items}/>

docs/docs/user-guide/text-render/text-richtext.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 3
+description: "就像在其它组件里一样使用自定义材质。"
+---
+
+# RichText 自定义材质
+
+TODO

docs/docs/user-guide/user-guide-intro.mdx

@@ -5,7 +5,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
 在 [入门教程](../start-guide/start-guide-intro) 里，你应该对如何更好地使用安装服务包后的引擎已经有所了解了。
 
-而在这里你能了解到服务包为引擎添加的每个特性、改动与原理：
+通过使用指南你能更详细地了解服务包为引擎添加的每个特性与改动：
 
 <DocCardList items={useCurrentSidebarCategory().items}/>
 

docs/src/theme/DocCard/index.js

@@ -34,6 +34,7 @@ function CardLayout({href, icon, title, description}) {
 }
 
 function CardCategory({ item }) {
+  const doc = useDocById(item.docId ?? undefined);
   const href = findFirstCategoryLink(item); // Unexpected: categories that don't have a link have been filtered upfront
 
   if (!href) {
@@ -45,17 +46,7 @@ function CardCategory({item}) {
       href={href}
       icon=""
       title={item.label}
-      description={translate(
-        {
-          message: '{count} items',
-          id: 'theme.docs.DocCard.categoryDescription',
-          description:
-            'The default description for a category card in the generated index about how many items this category includes',
-        },
-        {
-          count: item.items.length,
-        },
-      )}
+      description={item.description}
     />
   );
 }