From 6c2279e157fec2b312beef21c22a88014c7ecf7f Mon Sep 17 00:00:00 2001
From: Kuizuo <hi@kuizuo.cn>
Date: Sun, 28 Jan 2024 23:05:48 +0800
Subject: [PATCH] docs: update docusaurus guides

---
 data/social.ts                     |   4 +-
 docs/skill/docusaurus/comment.md   |   6 +-
 docs/skill/docusaurus/component.md |   8 +-
 docs/skill/docusaurus/config.md    |  49 ++++++-----
 docs/skill/docusaurus/guides.mdx   |   2 +-
 docs/skill/docusaurus/plugin.md    | 127 +++++++++++++++--------------
 6 files changed, 104 insertions(+), 92 deletions(-)

diff --git a/data/social.ts b/data/social.ts
index f01b7cfb..280e5fb4 100644
--- a/data/social.ts
+++ b/data/social.ts
@@ -2,7 +2,6 @@ export type Social = {
   github?: string
   twitter?: string
   juejin?: string
-  csdn?: string
   qq?: string
   wx?: string
   cloudmusic?: string
@@ -22,7 +21,6 @@ const social: Social = {
   github: 'https://github.com/kuizuo',
   twitter: 'https://twitter.com/kuizuo',
   juejin: 'https://juejin.cn/user/1565318510545901',
-  csdn: 'https://blog.csdn.net/kuizuo12',
   qq: 'https://img.kuizuo.cn/qq.png',
   wx: 'https://img.kuizuo.cn/wechat.png',
   // zhihu: 'https://www.zhihu.com/people/kuizuo',
@@ -31,7 +29,7 @@ const social: Social = {
   discord: 'https://discord.gg/M8cVcjDxkz',
 }
 
-const socialSet: Record<keyof Social, SocialValue> = {
+const socialSet: Record<keyof Social | 'rss', SocialValue> = {
   github: {
     href: social.github,
     title: 'GitHub',
diff --git a/docs/skill/docusaurus/comment.md b/docs/skill/docusaurus/comment.md
index 1c6b85b7..173ba3d9 100644
--- a/docs/skill/docusaurus/comment.md
+++ b/docs/skill/docusaurus/comment.md
@@ -31,7 +31,7 @@ Waline：需要搭建后端服务与数据库服务，提供评论与浏览量
 <script
   src="https://giscus.app/client.js"
   data-repo="kuizuo/blog"
-  data-repo-id="MDEwOlJlcG9zaXRvcnkzOTc2MjU2MTI="
+  data-repo-id="MDEwOlJlcG9zaXRvcnkzOTc2Mxxxxx"
   data-category="General"
   data-category-id="DIC_kwDOF7NJDM4CPK95"
   data-mapping="title"
@@ -51,7 +51,7 @@ Waline：需要搭建后端服务与数据库服务，提供评论与浏览量
 ```javascript title='docusaurus.config.ts' icon='logos:docusaurus'
 giscus: {
   repo: 'kuizuo/blog',
-  repoId: 'MDEwOlJlcG9zaXRvcnkzOTc2MjU2MTI=',
+  repoId: 'MDEwOlJlcG9zaXRvcnkzOTc2Mxxxxx',
   category: 'General',
   categoryId: 'DIC_kwDOF7NJDM4CPK95',
   theme: 'light',
@@ -59,7 +59,7 @@ giscus: {
 }
 ```
 
-:::info 如果不替换的话，评论的信息都将会在我的 Discussions 下😂
+:::info 切记一定要将上述数据替换成你的，如果不替换的话，评论的信息都将会在我的 Discussions 下。
 
 :::
 
diff --git a/docs/skill/docusaurus/component.md b/docs/skill/docusaurus/component.md
index 19ea2fc9..f04ce2f6 100644
--- a/docs/skill/docusaurus/component.md
+++ b/docs/skill/docusaurus/component.md
@@ -34,11 +34,9 @@ website
 要输出所有 `@docusaurus/theme-classic` 组件的总览，可以运行：
 
 ```bash
-yarn run swizzle @docusaurus/theme-classic -- --list
+npm run swizzle @docusaurus/theme-classic -- --list
 ```
 
-不过我更倾向于直接在 `node_modules/@docusaurus/theme-classic/src/theme` 查看所有组件。
-
 这里以归档页举例，官方的归档页面组件是 `theme/BlogArchivePage`
 
 有两种方式可以完成自定义组件：[弹出组件](https://docusaurus.io/zh-CN/docs/swizzling#ejecting)或者[包装组件](https://docusaurus.io/zh-CN/docs/swizzling#wrapping)
@@ -46,12 +44,12 @@ yarn run swizzle @docusaurus/theme-classic -- --list
 例如弹出组件，可以执行以下[命令](https://docusaurus.io/zh-CN/docs/cli#docusaurus-swizzle)：
 
 ```bash
-yarn run swizzle @docusaurus/theme-classic BlogArchivePage -- --eject --typescript
+npm run swizzle @docusaurus/theme-classic BlogArchivePage -- --eject --typescript
 ```
 
 这样会创建 `src/theme/BlogArchivePage/index.tsx`，也就是归档页面的代码，而要做的就是修改代码，实现自己所需的样式与功能。
 
-不过这样获取到的只是 index.tsx 文件，有可能还存在子组件。所有我一般的做法是在 `node_modules/@docusaurus/theme-classic/src/theme` 中找到组件所在文件夹，然后将整个文件夹复制到 `src/theme` 下。这样能得到就是最原始的 ts 文件，同时所能修改的地方也就越多，更方便的个性化。
+不过这样获取到的只是 index.tsx 文件，有可能还存在子组件。所以我一般的做法是在 `node_modules/@docusaurus/theme-classic/src/theme` 中找到组件所在文件夹，然后将整个文件夹复制到 `src/theme` 下。这样能得到就是最原始的 ts 文件，同时所能修改的地方也就越多，更方便的个性化。
 
 :::warning
 
diff --git a/docs/skill/docusaurus/config.md b/docs/skill/docusaurus/config.md
index e65d9f76..2a07f0b9 100644
--- a/docs/skill/docusaurus/config.md
+++ b/docs/skill/docusaurus/config.md
@@ -47,38 +47,47 @@ export default config
 
 ### 基本信息
 
-站点名和作者名只需要搜索 **愧怍** 便能找到关键位置
+站点名和作者名只需要搜索 **愧怍** 或 **kuizuo** 便能找到关键位置，将其更改为你的便可。
 
-### 关于我
+### 关于我 页面
 
 具体可在 `src/pages/about.mdx` 中查看与修改。
 
-其中技术栈的图标使用 [Shields.io](https://shields.io/) 生成，github 的状态信息使用[GitHub Profile Summary Cards](https://github-profile-summary-cards.vercel.app/demo.html)生成
+这里你可能需要展示你的技术栈，这里我推荐使用 [skillicons](https://skillicons.dev/) 来生成技术栈的图标，就如下面这样
 
-所要做的就是将 username 替换成你的 github 名即可。
+[![My Skills](https://skillicons.dev/icons?i=ts,nodejs,vue,nuxt,react,nextjs,tailwind,nestjs,prisma,postgres,redis,supabase,rust,wasm,vscode)](https://skillicons.dev)
 
-### 社交链接
+而 github 的状态信息使用[GitHub Profile Summary Cards](https://github-profile-summary-cards.vercel.app/demo.html) 或 [github-stats](https://github.com/jstrieb/github-stats) ，这里我选用 github-stats 因为带有动画，但需要图片需要自行构建。
 
-只需要在 `docusaurus.config.ts` 中修改 socials 属性，替换成你的即可。
+![](https://raw.githubusercontent.com/kuizuo/github-stats/master/generated/overview.svg#gh-light-mode-only)
 
-```typescript title='docusaurus.config.ts' icon='logos:docusaurus'
-socials: {
-  github: 'https://github.com/kuizuo',
-  twitter: 'https://twitter.com/kuizuo',
-  juejin: 'https://juejin.cn/user/1565318510545901',
-  csdn: 'https://blog.csdn.net/kuizuo12',
-  qq: 'https://wpa.qq.com/msgrd?v=3&amp;uin=911993023&amp;site=qq',
-  cloudmusic: 'https://music.163.com/#/user/home?id=1333010742',
-}
-```
+![](https://raw.githubusercontent.com/kuizuo/github-stats/master/generated/languages.svg#gh-light-mode-only)
 
-如果你还有其他社交链接，可以在这里添加对应的链接，然后在 `src/components/Hero.index.tsx` 中的 SocialLinks 组件中来配置新增或者删除社交链接图标。
+### 友链、导航、项目 页面
 
-### 友链、导航、项目
+这三个页面是通过 [plugin-content-pages](https://docusaurus.io/zh-CN/docs/api/plugins/@docusaurus/plugin-content-pages) 实现自定义页面的，如果想了解页面的实现可以看[自定义页面](/docs/docusaurus-style#自定义页面)
 
-这里你需要关注数据部分，如果想了解页面的实现可以看[自定义页面](/docs/docusaurus-style#自定义页面)
+这里你主要关注数据部分，数据都存放至根文件夹 `/data` 下，并使用 ts 用作类型提示。这些数据最终会在这些页面中渲染，你只需要根据符合的类型定义所要展示的数据，访问对应页面就能查看到效果。
 
-数据部分存放在根目录 `/data` 下，并使用 ts 用作类型提示。这些数据最终会在这些页面中渲染，你只需要根据符合的类型定义所要展示的数据，访问对应页面就能查看到效果。
+### 社交链接
+
+只需要在 `data/social.ts` 中修改 social 对象即可。
+
+内置了以下主流的可供选择的几个社交账号。
+
+```typescript title='social.ts' icon='logos:typescript-icon'
+export type Social = {
+  github?: string
+  twitter?: string
+  juejin?: string
+  qq?: string
+  wx?: string
+  cloudmusic?: string
+  zhihu?: string
+  email?: string
+  discord?: string
+}
+```
 
 ## 其他配置
 
diff --git a/docs/skill/docusaurus/guides.mdx b/docs/skill/docusaurus/guides.mdx
index e4aee89b..aa470e6c 100644
--- a/docs/skill/docusaurus/guides.mdx
+++ b/docs/skill/docusaurus/guides.mdx
@@ -8,7 +8,7 @@ keywords: ['guides', 'docusaurus', 'docusaurus-guides']
 
 这里是本人对 [Docusaurus](https://docusaurus.io/) 的魔改指南，帮助使用者更好使用 Docusaurus。
 
-同时 [Docusaurus 2.0](https://docusaurus.io/zh-CN/blog/2022/08/01/announcing-docusaurus-2.0) 也正式发布了，顺带升级依赖与重构项目使其易懂易用。
+同时 [Docusaurus 3.0](https://docusaurus.io/zh-CN/blog/releases/3.0) 也正式发布了，顺带升级依赖与重构项目使其易懂易用。
 
 也欢迎你使用本主题，如果你有任何问题，欢迎在 [GitHub Discussions](https://github.com/kuizuo/blog/discussions) 提出。
 
diff --git a/docs/skill/docusaurus/plugin.md b/docs/skill/docusaurus/plugin.md
index 8b213128..96ccc08d 100644
--- a/docs/skill/docusaurus/plugin.md
+++ b/docs/skill/docusaurus/plugin.md
@@ -5,72 +5,63 @@ title: 插件
 authors: kuizuo
 ---
 
-在 `docusaurus.config.ts` 下的 plugins，可以看到所有插件以及插件配置。
+在 `docusaurus.config.ts` 下的 plugins，可以看到所有插件以及插件配置。如下所示
 
 ```typescript title='docusaurus.config.ts' icon='logos:docusaurus'
 plugins: [
-  'docusaurus-plugin-image-zoom',
-  'docusaurus-plugin-sass',
-  path.resolve(__dirname, './src/plugin/plugin-baidu-tongji'),
-  path.resolve(__dirname, './src/plugin/plugin-baidu-push'),
-  [
-    path.resolve(__dirname, './src/plugin/plugin-content-blog'),
-    {
-      path: 'blog',
-      routeBasePath: '/',
-      editUrl: ({ locale, blogDirPath, blogPath, permalink }) =>
-        `https://github.com/kuizuo/blog/edit/main/${blogDirPath}/${blogPath}`,
-      editLocalizedFiles: false,
-      blogSidebarCount: 10,
-      postsPerPage: 10,
-      showReadingTime: true,
-      readingTime: ({ content, frontMatter, defaultReadingTime }) =>
-        defaultReadingTime({ content, options: { wordsPerMinute: 300 } }),
-      feedOptions: {
-        type: 'all',
-        title: '愧怍',
-        copyright: `Copyright © ${new Date().getFullYear()} 愧怍 Built with Docusaurus.<p><a href="http://beian.miit.gov.cn/" class="footer_lin">${beian}</a></p>`,
+    'docusaurus-plugin-image-zoom',
+    'docusaurus-plugin-sass',
+    '@docusaurus/plugin-ideal-image',
+    ['docusaurus-plugin-baidu-tongji', { token: 'xxxxxxxxxxxxxxx' }],
+    [
+      '@docusaurus/plugin-pwa',
+      {
+        debug: process.env.NODE_ENV === 'development',
+        offlineModeActivationStrategies: ['appInstalled', 'standalone', 'queryString'],
+        pwaHead: [
+          { tagName: 'link', rel: 'icon', href: '/img/logo.png' },
+          { tagName: 'link', rel: 'manifest', href: '/manifest.json' },
+          { tagName: 'meta', name: 'theme-color', content: '#12affa' },
+        ],
       },
-    },
+    ],
+    [
+      './src/plugin/plugin-content-blog', // 为了实现全局 blog 数据，必须改写 plugin-content-blog 插件
+      {
+        path: 'blog',
+        editUrl: ({ locale, blogDirPath, blogPath, permalink }) =>
+          `https://github.com/kuizuo/blog/edit/main/${blogDirPath}/${blogPath}`,
+        editLocalizedFiles: false,
+        blogDescription: '代码人生：编织技术与生活的博客之旅',
+        blogSidebarCount: 10,
+        blogSidebarTitle: 'Blogs',
+        postsPerPage: 10,
+        showReadingTime: true,
+        readingTime: ({ content, frontMatter, defaultReadingTime }) =>
+          defaultReadingTime({ content, options: { wordsPerMinute: 300 } }),
+        feedOptions: {
+          type: 'all',
+          title: '愧怍',
+          copyright: `Copyright © ${new Date().getFullYear()} 愧怍 Built with Docusaurus.<p><a href="http://beian.miit.gov.cn/" class="footer_lin">${beian}</a></p>`,
+        },
+      },
+    ],
   ],
-  // ...
-]
 ```
 
-这里我会列举我所用到的插件（包括自定义），更多插件可看[社区精选 | Docusaurus](https://docusaurus.io/zh-CN/community/resources#community-plugins)
-
-## plugin-baidu-tongji
-
-[百度统计](https://tongji.baidu.com/web/welcome/login)
-
-这样你就能看到你的站点访客主要都在看哪些页面，以及行为记录，如下图所示。![image-20221204153015256](https://img.kuizuo.cn/image-20221204153015256.png)
-
-## plugin-baidu-push
+## [plugin-image-zoom](https://github.com/flexanalytics/plugin-image-zoom)
 
-[百度收录](https://ziyuan.baidu.com/dailysubmit/index)
+适用于 Docusaurus 的图像缩放插件。
 
-主动推送代码，用于网站收录，这部分代码无需变动。
+## plugin-sass
 
-```javascript title="src/plugins/plugin-baidu-push/index.js"
-;(function () {
-  var bp = document.createElement('script')
-  var curProtocol = window.location.protocol.split(':')[0]
-  if (curProtocol === 'https') {
-    bp.src = 'https://zz.bdstatic.com/linksubmit/push.js'
-  } else {
-    bp.src = 'http://push.zhanzhang.baidu.com/push.js'
-  }
-  bp.defer = true
-  var s = document.getElementsByTagName('script')[0]
-  s.parentNode.insertBefore(bp, s)
-})()
-```
+支持 sass 预处理器
 
-## plugin-matomo(弃用)
+## plugin-baidu-tongji
 
-[Matomo Analytics](https://matomo.org/) 站点统计，分析用户行为，停留时间。
+使站点支持 [百度统计](https://tongji.baidu.com/web/welcome/login) ，这样你就能看到你的站点访客主要都在看哪些页面，以及行为记录，如下图所示。![image-20221204153015256](https://img.kuizuo.cn/image-20221204153015256.png)
 
-与百度统计类似，不过这个需要自行部署 matomo 服务，不需要的可直接删除。
+同时还在 [Footer](https://github.com/kuizuo/blog/blob/main/src/theme/Footer/index.tsx#L3) 中添加了 [@vercel/analytics](https://github.com/vercel/analytics) 前提是需要本项目部署于 Vercel 上。
 
 ## [plugin-pwa](https://docusaurus.io/zh-CN/docs/api/plugins/@docusaurus/plugin-pwa)
 
@@ -78,18 +69,34 @@ plugins: [
 
 ![image-20221204153401244](https://img.kuizuo.cn/image-20221204153401244.png)
 
-## [plugin-image-zoom](https://github.com/flexanalytics/plugin-image-zoom)
+## plugin-content-blog
 
-适用于 Docusaurus 的图像缩放插件。
+由于官方的 [plugin-content-blog](https://docusaurus.io/zh-CN/docs/api/plugins/@docusaurus/plugin-content-blog) 插件没有将有关博客的数据设置为全局，所以只能在博客列表页面 `BlogListPage` 组件中获取到，而由于本博客的某些组件需要使用到部分数据，因此这里对 `plugin-content-blog` 进行魔改，将 blog 信息添加至全局数据中，可在任意页面中都访问到所有博文的信息。
 
-## plugin-sass
+```typescript title='src/plugin/plugin-content-blog.ts'
+async function blogPluginEnhanced(context, options) {
+  const blogPluginInstance = await blogPlugin(context, options)
 
-支持 sass 预处理器
+  return {
+    ...blogPluginInstance,
+    async contentLoaded({ content, allContent, actions }) {
+      // Create default plugin pages
+      await blogPluginInstance.contentLoaded({ content, allContent, actions })
 
-## plugin-content-blog
+      // Create your additional pages
+      const { blogPosts, blogTags } = content
+      const { setGlobalData } = actions
 
-由于官方的 [plugin-content-blog](https://docusaurus.io/zh-CN/docs/api/plugins/@docusaurus/plugin-content-blog) 插件没有将博客的所有**标签**数据传递给博客列表组件，也就是导致博客列表页面 `BlogListPage` 获取不到全局标签信息，所以这里对 `plugin-content-blog` 进行魔改，将 blog 信息添加至全局数据中，可在任意页面中都访问到所有博文的信息。
+      setGlobalData({
+        posts: blogPosts.slice(0, 10), // Only store 10 posts
+        postNum: blogPosts.length,
+        tagNum: Object.keys(blogTags).length,
+      })
+    },
+  }
+}
+```
 
-:::warning 这些数据可能会占据一定的空间，查看详情 [点我](https://github.com/facebook/docusaurus/pull/7163#issuecomment-1096780257)。
+:::warning 这些数据可能会占据一定的空间，[点我](https://github.com/facebook/docusaurus/pull/7163#issuecomment-1096780257)查看详情 。
 
 :::