From c74f61165a87930329ed5a97e36c8311ff2b93d2 Mon Sep 17 00:00:00 2001
From: zkz098 <zkz20081204@126.com>
Date: Tue, 28 Feb 2023 19:34:05 +0800
Subject: [PATCH] =?UTF-8?q?docs(*):=20=E6=9B=B4=E6=96=B0=E9=95=BF=E6=96=87?=
 =?UTF-8?q?=E7=AB=A0=E4=BC=98=E5=8C=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 _config.yml                   |  1 +
 docs/.vuepress/nav/sidebar.js | 10 +++++-----
 docs/guide/theme.md           | 28 +++++++++++++++++-----------
 3 files changed, 23 insertions(+), 16 deletions(-)

diff --git a/_config.yml b/_config.yml
index 83edc53..7579eb0 100644
--- a/_config.yml
+++ b/_config.yml
@@ -29,6 +29,7 @@ experiments:
   disableThemeComment: false # 禁用主题评论系统(一般用于关闭评论或让插件接管评论系统)
   usingRelative: false # _image.yml 使用相对路径
   optimizeLongPosts: false # 优化长文章，这能让长文章的FPS提升70%-150%并解决假死问题，但存在一些副作用
+  # 具体见https://docs.kaitaku.xyz/guide/theme.html#%E9%95%BF%E6%96%87%E7%AB%A0%E4%BC%98%E5%8C%96
 
 # 优化性能区
 performance:
diff --git a/docs/.vuepress/nav/sidebar.js b/docs/.vuepress/nav/sidebar.js
index 7b69bcc..dfec4a2 100644
--- a/docs/.vuepress/nav/sidebar.js
+++ b/docs/.vuepress/nav/sidebar.js
@@ -5,23 +5,23 @@ export default {
             collapsible: true,
             children: [
                 {text: "快速上手",link: "/guide/"},
-                {text: "更多配置",link: "/guide/config"},
-                {text: "主题配置",link: "/guide/theme"},
-                {text: "评论系统",link: "/guide/comment"}
+                {text: "更多配置",link: "/guide/config.html"},
+                {text: "主题配置",link: "/guide/theme.html"},
+                {text: "评论系统",link: "/guide/comment.html"}
             ]
         },
         {
             text: "迁移指南",
             collapsible: true,
             children: [
-                {text: "从shoka迁移",link: "/guide/shoka"}
+                {text: "从shoka迁移",link: "/guide/shoka.html"}
             ]
         },
         {
             text: "最佳实践",
             collapsible: true,
             children: [
-                {text: "性能优化",link: "/guide/performance"}
+                {text: "性能优化",link: "/guide/performance.html"}
             ]
         }
     ]
diff --git a/docs/guide/theme.md b/docs/guide/theme.md
index 834294f..5e84171 100644
--- a/docs/guide/theme.md
+++ b/docs/guide/theme.md
@@ -11,18 +11,24 @@ js: "js" # js存放目录(不建议改动)
 ```
 
 ### 实验性特性
-#### PWA
 :::tip
-PWA功能较为复杂且需要一些时间，早期站点搭建时可以先忽略
+实验性特性均不稳定，随时可能引入破坏性更改，且部分有明显副作用
 :::
-PWA是Progressive Web Apps的缩写，可以为web应用提供类似于原生应用的体验
-配置如下:
+#### 长文章优化
 ```yaml
-pwa:
-  enable: false # 开启PWA功能
-  serviceworker: sw.js #serviceworker脚本位置,使用以/为基准的绝对路径
-  manifest: manifest.json #manifest位置,使用以/为基准的绝对路径
+experiments:
+  optimizeLongPosts: true # 开启长文章优化
 ```
-serviceworker可查看[MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/Service_Worker_API/Using_Service_Workers)以获取帮助 \
-manifest可查看[MDN](https://developer.mozilla.org/zh-CN/docs/Web/Manifest)获取帮助 \
-建议将上述文件放置于assets或source(hexo根目录)下以方便定位
\ No newline at end of file
+当文章过长时(≥5万字)，文章页面的FPS会下降到10FPS左右，部分渲染性能较差的设备还会出现假死现象。 \
+此问题在 shoka 时期就已存在，因此 shokaX 引入了长文章优化，底层原理是使用`content-visibility`暴力缩短渲染范围以大幅提高性能。
+:::tip
+实验室数据显示在2万字时FPS便会出现波动，3万字时就可以感觉到波动了，5万字时页面已经十分卡顿。
+如果页面有大量Katex公式则此问题会更严重
+:::
+
+实验室数据显示此选项可将FPS由10提升到25左右(4x CPU slowdown)并解决卡死问题，但此功能存在`导航栏抖动`和`进度条抖动`问题，可能影响到浏览体验。
+- 导航栏抖动：在滑动时导航栏会反复弹出收回，时间较短(一般不超过1s)
+- 进度条抖动：返回顶部的文字和滑动条的长度与文章实际长度不符，存在±1-5%的误差
+
+上述问题均是由于此方法导致的`window.scrollY`抖动引起的，如果你有好的解决方法欢迎发起PR。
+因此，长文章优化功能仅建议在有文章字数超过3万字或站点主要面向渲染性能较差的设备时启用。
\ No newline at end of file