在 `docusaurus.config.ts` 下的 plugins，可以看到所有插件以及插件配置。如下所示

```typescript title='docusaurus.config.ts' icon='logos:docusaurus'
plugins: [
 '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.<a href="http://beian.miit.gov.cn/" class="footer_lin">${beian}</a>`,
 },
 },
 ],
 ],
```

## [plugin-image-zoom](https://github.com/flexanalytics/plugin-image-zoom)

适用于 Docusaurus 的图像缩放插件。

## plugin-sass

支持 sass 预处理器

## plugin-baidu-tongji

使站点支持 [百度统计](https://tongji.baidu.com/web/welcome/login) ，这样你就能看到你的站点访客主要都在看哪些页面，以及行为记录，如下图所示。![image-20221204153015256](https://img.kuizuo.cn/image-20221204153015256.png)

同时还在 [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)

创建支持离线模式和应用安装的 PWA 文档站点，就像下图这样。

![image-20221204153401244](https://img.kuizuo.cn/image-20221204153401244.png)

## plugin-content-blog

由于官方的 [plugin-content-blog](https://docusaurus.io/zh-CN/docs/api/plugins/@docusaurus/plugin-content-blog) 插件没有将有关博客的数据设置为全局，所以只能在博客列表页面 `BlogListPage` 组件中获取到，而由于本博客的某些组件需要使用到部分数据，因此这里对 `plugin-content-blog` 进行魔改，将 blog 信息添加至全局数据中，可在任意页面中都访问到所有博文的信息。

```typescript title='src/plugin/plugin-content-blog.ts'
async function blogPluginEnhanced(context, options) {
 const blogPluginInstance = await blogPlugin(context, options)

 return {
 ...blogPluginInstance,
 async contentLoaded({ content, allContent, actions }) {
 // Create default plugin pages
 await blogPluginInstance.contentLoaded({ content, allContent, actions })

 // Create your additional pages
 const { blogPosts, blogTags } = content
 const { setGlobalData } = actions

 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)查看详情 。

:::

插件

## docusaurus.config.ts

`docusaurus.config.ts` 位于你的网站的根目录，包含了你的站点的配置信息。

在这里可以修改 logo，站点名(title)，作者名，顶部的公告(announcementBar)，导航栏(navbar)，底部导航(footer)等等。

```typescript title='docusaurus.config.ts' icon='logos:docusaurus'
const config: Config = {
  title: '愧怍的小站',
  url: 'https://kuizuo.cn',
  baseUrl: '/',
  favicon: 'img/favicon.ico',
  organizationName: 'kuizuo',
  projectName: 'blog',
  themeConfig: {
    image: 'img/logo.png',
    metadata: [
      {
        name: 'keywords',
        content: '愧怍, kuizuo, blog, javascript, typescript, node, react, vue, web, 前端, 后端',
      },
    ],
    // ...
}

export default config
```

同时绝大部分的配置信息都可以放在这里，例如搜索(algolia)，评论(giscus)，社交链接(socials)等等。这些配置都可以通过docusaurus内置的hook(useThemeConfig、useDocusaurusContext)来获取。

完整的配置信息说明 [docusaurus.config.ts | Docusaurus](https://docusaurus.io/zh-CN/docs/api/docusaurus-config)

## sidebars.js

用于配置文档的侧边栏，例如本博客中的[技术笔记](/docs/skill/)，[工具推荐](/docs/tools/)。侧边栏对应的每一项都是一个 markdown 文件，同时这些文件都存放在 docs 目录下，方便管理。

[侧边栏 | Docusaurus](https://docusaurus.io/zh-CN/docs/sidebar)

## 相关信息

### 基本信息

站点名和作者名只需要搜索 **愧怍** 或 **kuizuo** 便能找到关键位置，将其更改为你的便可。

### 关于我 页面

具体可在 `src/pages/about.mdx` 中查看与修改。

这里你可能需要展示你的技术栈，这里我推荐使用 [skillicons](https://skillicons.dev/) 来生成技术栈的图标，就如下面这样

[![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 因为带有动画，但需要图片需要自行构建。

![](https://raw.githubusercontent.com/kuizuo/github-stats/master/generated/overview.svg#gh-light-mode-only)

![](https://raw.githubusercontent.com/kuizuo/github-stats/master/generated/languages.svg#gh-light-mode-only)

### 友链、导航、项目 页面

这三个页面是通过 [plugin-content-pages](https://docusaurus.io/zh-CN/docs/api/plugins/@docusaurus/plugin-content-pages) 实现自定义页面的，如果想了解页面的实现可以看[自定义页面](/docs/docusaurus-style#自定义页面)

这里你主要关注数据部分，数据都存放至根文件夹 `/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
}
```

## 其他配置

可能还需要配置下 giscus 评论，搜索，站点统计等等，这些会放在[插件](/docs/docusaurus-plugin)中细讲。


配置文件

我之前使用 [Vercel](https://vercel.com) 一把梭，无需任何配置。这样我就只需要专注输出内容即可。这是我当时使用 Vercel 部署的文章 [Vercel 部署个人博客](/blog/vercel-deploy-blog)

但如今，`vercel.app` 被 DNS 污染，即被墙了，导致国内无法访问，虽然使用有自己的域名解析到 Vercel 上也可能访问，但被墙了，也就意味着国内 DNS 的解析速度必然有所下降，导致站点访问速度有所下降。

加上我想有更好的访客体验，于是我决定采用国内国外不同的解析方式来加快访问。

首先在线路类型中，分别针对境内和境外做了不同的记录值，境内使用国内的 CDN 服务，而境外就使用 Vercel。

![image-20221204161431863](https://img.kuizuo.cn/image-20221204161431863.png)

这样我国内访问就是访问国内的 CDN，访问国外访问就是 Vercel 的 CDN，这样针对不同的地区的网络都能有一个不错的访问速度，可以到 [Ping.cn:网站测速-ping 检测](https://www.ping.cn/) 中测试测试你的站点访问速度如何。

以下是我的网站测速结果，也可通过访问 [kuizuo.cn 在全国各地区网络速度测试情况-Ping.cn](https://www.ping.cn/http/kuizuo.cn) 在线查看

![image-20221204161146327](https://img.kuizuo.cn/image-20221204161146327.png)

果然，花钱了就是不一样。

## 持续集成

由于 Vercel 能够自动拉取仓库代码，并自行构建部署，因此通常什么配置都不需要。

由于代码提交到代码仓库(github)，则需要借用 CI 服务来帮助我们完成这些任务，这里我使用了 [Github Action](https://github.com/marketplace) 来帮助我构建，构建记录可以在 [Actions · kuizuo/blog](https://github.com/kuizuo/blog/actions) 中查看。以下是我的配置文件

```yaml title='.github/workflows/ci.yml' icon='logos:github-actions'
name: CI

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        os: [ubuntu-latest] # macos-latest, windows-latest
        node: [18]

    steps:
      - uses: actions/checkout@v4

      - name: Set node version to ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - run: corepack enable

      - name: Setup
        run: npm i -g @antfu/ni

      - name: Install
        run: nci

      - name: Build
        run: nr build

      - name: SSH Deploy
        uses: easingthemes/ssh-deploy@v4.1.10
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
          ARGS: '-avzr --delete'
          SOURCE: 'build'
          REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
          REMOTE_USER: 'root'
          TARGET: '/opt/1panel/apps/openresty/openresty/www/sites/kuizuo.cn/index'
```

等待 CI 将最终构建的产物通过 rsync 放到自己的服务器上，便完成了整套部署的流程。

当一切都配置好了之后，我只需要将代码推送到远程仓库上，Github Action 与 Vercel 分别完成它们所该做的任务。等待片刻，再次访问站点，刚刚提交的代码就成功生效了。

## 没有域名和服务器该怎么部署？

当然了上述只是我的配置方案，有许多伙伴可能没有自己的域名或者自己的服务器，就想着白嫖，那么这里目前我只能推荐 [Netlify](https://www.netlify.com/)，然后通过 netlify 的二级域名如 kuizuo-blog.netlify.app 来进行访问。

我个人还是非常建议去弄一个属于自己的域名，通过 Vercel 的自定义域名就可以访问。并且由于自己的域名解析的不是大陆的服务器（Vercel 的服务器就不是国内大陆的），因此无需备案这一更繁琐的步骤。


部署

## [样式和布局](https://docusaurus.io/zh-CN/docs/styling-layout#styling-your-site-with-infima)

Docusaurus 网站是一个 React 单页应用。 你可以像一般的 React 应用一样给网站提供样式，像 [tailwindcss](https://tailwindcss.com/) 与组件库都是支持的。不过引入这些会带来一定的代码体积，因此在这套主题中我所使用的都是全局样式与 css 模块。

## 修改主题色

可以在 [这里](https://docusaurus.io/zh-CN/docs/styling-layout#styling-your-site-with-infima) 设置主色调与背景色来查看浅色与深色模式下的效果，例如我的主题色是 #12AFFA

`@docusaurus/preset-classic` 用 [Infima](https://infima.dev/) 作为底层样式框架。 Infima 提供了灵活的布局，以及常见的 UI 组件样式，适用于以内容为中心的网站（博客、文档、首页）。想要了解更多详情，请查看 [Infima 网站](https://infima.dev/)。

## 主页

因为设置了[仅博客模式](https://docusaurus.io/zh-CN/docs/blog#blog-only-mode)，没有专门编写的首页，而是将博文列表设置为首页。需要将 `src/pages/index.tsx` 文件给删除（或者改个名），否则会导致首页路径冲突。当然你也可以专门搞一个主页，就像 docusaurus 那样，然后跳转至博文列表页。

所以博客页面，也就是首页。但仅仅只有博客是远远不够的，所以便添加了 Hero 组件，也就是首次访问博客的样子。

主页右侧 SVG 背景文件地址: `src/components/Hero/img/hero_main.svg`, 插画来源于 [unDraw](https://undraw.co/illustrations)，在这个网站可以找到这类插画风格的背景。或者你可以找专门设计插画的人为你设计。

## 自定义页面

[归档](/blog/archive)、[友链](/friends)、[导航](/resources)、[项目](/project)以及[关于我](/about)页面都在 `src/pages` 目录下定义，根据文件名映射对应路由。页面的创建可以查看 [创建页面 | Docusaurus](https://docusaurus.io/zh-CN/docs/creating-pages)

样式与页面

> [搜索 | Docusaurus](https://docusaurus.io/zh-CN/docs/search)

## [algolia](https://www.algolia.com/)

有两种方案来配置 algolia。

1. 让 Docsearch（准确来说是 [Algolia Crawler](https://crawler.algolia.com/)） 每周一次爬取你的网站（也可自行爬取），**前提是项目开源，否则收费**，好处是无需额外配置，申请比较繁琐（本博客目前采用的方式）

2. 自己运行 DocSearch 爬虫，可以随时爬取，但需要自行去注册账号和搭建爬虫环境，或者使用 Github Actions 来帮我们爬取。

### 方案1

关于申请 Algolia DocSearch 在文档中有详细介绍，主要是要申请麻烦，需要等待邮箱，并且还需要回复内容给对方进行确认。所以免费托管的 DocSearch 条件是，比较苛刻的，但申请完几乎是一劳永逸，也是我非常推荐的。如果申请成功后就可以在 [Crawler Admin Console](https://crawler.algolia.com/admin/crawlers) 中查看

![image-20220627232545640](https://img.kuizuo.cn/image-20220627232545640.png)

然后将得到 algolia 的 appId，apiKey，indexName 填写到 `docusaurus.config.ts` 中即可。

```javascript title='docusaurus.config.ts'
algolia: {
 appId: 'GV6YN1ODMO',
 apiKey: '50303937b0e4630bec4a20a14e3b7872',
 indexName: 'kuizuo',
}
```

爬取完毕后还会定时发送到你邮箱

![image-20230219144035031](https://img.kuizuo.cn/image-20230219144035031.png)

### 方案2

[Run your own | DocSearch (algolia.com)](https://docsearch.algolia.com/docs/run-your-own)

因为方案1是真的难申请，极大概率会失败，无奈只能采用方案2。

首先去申请 [Algolia](https://www.algolia.com/) 账号，然后在左侧 indices 创建索引，在 API Keys 中获取 Application ID 和 API Key（注意，有两个 API KEY）

![image-20210821230135749](https://img.kuizuo.cn/image-20210821230135749.png)

![image-20210821230232837](https://img.kuizuo.cn/image-20210821230232837.png)

填入到 `docusaurus.config.ts` 中的 API KEY 是 **Search-Only API Key**

```js
themeConfig: {
 algolia: {
 apiKey: "xxxxxxxxxxx",
 appId: "xxxxxxxxxxx",
 indexName: "kuizuo",
 },
}
```

系统我选用的是 Linux，在 Docker 的环境下运行爬虫代码。不过要先 [安装 jq](https://github.com/stedolan/jq/wiki/Installation#zero-install) 我这里选择的是 0install 进行安装（安装可能稍慢），具体可以查看文档，然后在控制台查看安装结果

```
[root@kzserver kuizuo.cn]# jq --version
jq-1.6
```

接着在任意目录中创建 `.env` 文件，填入对应的 APPID 和 API KEY（这里是`Admin API Key`，当时我还一直以为是 Search API Key 坑了我半天 😭）

```js
APPLICATION_ID = YOUR_APP_ID
API_KEY = YOUR_API_KEY
```

然后创建 `docsearch.json` 文件到项目目录下，其内容可以参考如下（将高亮部分替换成你的网站）

```json title='docsearch.json' {2-4}
{
 "index_name": "xxxx",
 "start_urls": ["https://example.com"],
 "sitemap_urls": ["https://example.com"],
 "selectors": {
 "lvl0": {
 "selector": "(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]",
 "type": "xpath",
 "global": true,
 "default_value": "Documentation"
 },
 "lvl1": "header h1, article h1",
 "lvl2": "article h2",
 "lvl3": "article h3",
 "lvl4": "article h4",
 "lvl5": "article h5, article td:first-child",
 "lvl6": "article h6",
 "text": "article p, article li, article td:last-child"
 },
 "custom_settings": {
 "attributesForFaceting": ["type", "lang", "language", "version", "docusaurus_tag"],
 "attributesToRetrieve": ["hierarchy", "content", "anchor", "url", "url_without_anchor", "type"],
 "attributesToHighlight": ["hierarchy", "content"],
 "attributesToSnippet": ["content:10"],
 "camelCaseAttributes": ["hierarchy", "content"],
 "searchableAttributes": [
 "unordered(hierarchy.lvl0)",
 "unordered(hierarchy.lvl1)",
 "unordered(hierarchy.lvl2)",
 "unordered(hierarchy.lvl3)",
 "unordered(hierarchy.lvl4)",
 "unordered(hierarchy.lvl5)",
 "unordered(hierarchy.lvl6)",
 "content"
 ],
 "distinct": true,
 "attributeForDistinct": "url",
 "customRanking": ["desc(weight.pageRank)", "desc(weight.level)", "asc(weight.position)"],
 "ranking": ["words", "filters", "typo", "attribute", "proximity", "exact", "custom"],
 "highlightPreTag": "",
 "highlightPostTag": "",
 "minWordSizefor1Typo": 3,
 "minWordSizefor2Typos": 7,
 "allowTyposOnNumericTokens": false,
 "minProximity": 1,
 "ignorePlurals": true,
 "advancedSyntax": true,
 "attributeCriteriaComputedByMinProximity": true,
 "removeWordsIfNoResults": "allOptional",
 "separatorsToIndex": "_",
 "synonyms": [
 ["js", "javascript"],
 ["ts", "typescript"]
 ]
 }
}
```

运行 docker 命令

```bash
docker run -it --env-file=.env -e "CONFIG=$(cat docsearch.json | jq -r tostring)" algolia/docsearch-scraper
```

接着等待容器运行，爬取你的网站即可。最终打开 algolia 控制台提示如下页面则表示成功

![image-20210821225934002](https://img.kuizuo.cn/image-20210821225934002.png)

因为要确保项目成功部署后才触发，如果采用 vercel 部署可以按照如下触发条件。

```yaml title='.github/workflows/docsearch.yml'
name: docsearch

on: deployment

jobs:
 algolia:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v2

 - name: Get the content of docsearch.json as config
 id: algolia_config
 run: echo "::set-output name=config::$(cat docsearch.json | jq -r tostring)"

 - name: Run algolia/docsearch-scraper image
 env:
 ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
 ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
 CONFIG: ${{ steps.algolia_config.outputs.config }}
 run: |
 docker run \
 --env APPLICATION_ID=${ALGOLIA_APP_ID} \
 --env API_KEY=${ALGOLIA_API_KEY} \
 --env "CONFIG=${CONFIG}" \
 algolia/docsearch-scraper
```

添加 [secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) 到你的 Github 仓库中，提交代码便可触发爬虫规则。

## [orama](https://docs.oramasearch.com/open-source/plugins/plugin-docusaurus)

配置 algolia 的过程有稍许的复杂，这里你可以在 docusaurus 中集成 [orama](https://docs.oramasearch.com/open-source/plugins/plugin-docusaurus)，这是一个在浏览器、服务器和边缘运行全文、矢量和混合搜索查询服务。最终实现的效果如图所示

![](https://img.kuizuo.cn/2024/0118082834-202401180828818.png)

## 本地搜索

如果你嫌 algolia 申请比较麻烦，docusaurus 也提供本地搜索，不过搜索上肯定会比全文搜索来的差一些。

本地搜索插件：[docusaurus-search-local](https://github.com/cmfcmf/docusaurus-search-local)