初始化的一个 docusaurus 项目就已经有预留好的的组件，例如博客布局，标签页归档页等等。但是这些组件的样式可能不满你的审美，或者是想增加在这些主题组件中增加点东西。那么就需要用到 [Swizzle](https://docusaurus.io/zh-CN/docs/swizzling)

## 主题组件

在 docusaurus 中的主题组件存放在 **@docusaurus/theme-classic/theme** 下，如果想要覆盖某个组件的话可以在 src/theme 目录下创建与之对应文件路径结构相同的文件。

像下面这样

```
website
├── node_modules
│   └── @docusaurus/theme-classic
│       └── theme
│           └── Navbar.js
└── src
    └── theme
        └── Navbar.js
```

每当导入 `@theme/Navbar` 时，`website/src/theme/Navbar.js` 都会被优先载入。

关于*分层架构*可看[客户端架构 | Docusaurus](https://docusaurus.io/zh-CN/docs/advanced/client)

## swizzle 组件

要输出所有 `@docusaurus/theme-classic` 组件的总览，可以运行：

```bash
npm run swizzle @docusaurus/theme-classic -- --list
```

这里以归档页举例，官方的归档页面组件是 `theme/BlogArchivePage`

有两种方式可以完成自定义组件：[弹出组件](https://docusaurus.io/zh-CN/docs/swizzling#ejecting)或者[包装组件](https://docusaurus.io/zh-CN/docs/swizzling#wrapping)

例如弹出组件，可以执行以下[命令](https://docusaurus.io/zh-CN/docs/cli#docusaurus-swizzle)：

```bash
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 文件，同时所能修改的地方也就越多，更方便的个性化。

:::warning

**但是**，在使用自定义组件的时候，有些主题组件可能会存在一定**风险**。尤其是在升级 Docusaurus 变得更困难，因为如果接收的属性发生变化，或内部使用的主题 API 发生变化，有可能就会导致页面渲染失败。

就比如我在将 docusaurus 升级到 2.0.0 正式版的时候就出现页面错误，原因是 [plugin-content-blog](https://docusaurus.io/zh-CN/docs/api/plugins/@docusaurus/plugin-content-blog) 在传递给组件的数据发生了变动，导致数据无法解析，自然而然页面就渲染失败。

:::

如果不升级依赖也确实不会有问题，但谁能保证新版本的一些特性不吸引使用者去升级呢？所以在自定义组件的时候，升级依赖后就可能需要维护一定的代码。要做的是重新 swizzle 一份最新的文件，然后去比对变化，最终排查问题。


自定义组件

这里推荐两种评论服务

Giscus：基于GitHub Discussions，对程序员相对友好，评论信息提示通过github邮箱发送。

Waline：需要搭建后端服务与数据库服务，提供评论与浏览量服务，可拓展性强。

## [giscus](https://giscus.app)

之前的评论使用的是 gitalk，但是那个是基于 github issue 的，并且 issue 不能关闭，每次打开仓库的时候都会看到几十个 issue，特别不友好。

所以后面就考虑换成 [giscus](https://giscus.app/zh-CN)，由 [GitHub Discussions](https://docs.github.com/en/discussions) 驱动的评论系统。首先要确保以下几点：

1. **此仓库是[公开的](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/setting-repository-visibility#making-a-repository-public)**，否则访客将无法查看 discussion（并不需要一定是博客的项目，随便一个仓库都可以）。
2. **[giscus](https://github.com/apps/giscus) app 已安装**否则访客将无法评论和回应。
3. **Discussions** 功能已[在你的仓库中启用](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/enabling-or-disabling-github-discussions-for-a-repository)。

本博客已经内置好评论组件 [src/component/Comment](https://github.com/kuizuo/blog/blob/main/src/components/Comment/index.tsx)，所以只需要在 `docusaurus.config.ts` 中设置 giscus 的配置即可。

### 配置 giscus

打开 [giscus](https://giscus.app/) 官网，填写完对应的信息后，可以得到一个已经配置好的`<script>`标签

```html
<script
  src="https://giscus.app/client.js"
  data-repo="kuizuo/blog"
  data-repo-id="MDEwOlJlcG9zaXRvcnkzOTc2Mxxxxx"
  data-category="General"
  data-category-id="DIC_kwDOF7NJDM4CPK95"
  data-mapping="title"
  data-strict="0"
  data-reactions-enabled="1"
  data-emit-metadata="0"
  data-input-position="top"
  data-theme="light"
  data-lang="zh-CN"
  crossorigin="anonymous"
  async
></script>
```

由于我在 `src/component/Comment` 组件中做了配置合并，并且支持主题变化、国际化。因此，你只需要复制 `data-repo`, `data-repo-id`, `data-category` 和 `data-category-id` 填写到 `docusaurus.config.ts` 中即可，以下是我的配置文件。

```javascript title='docusaurus.config.ts' icon='logos:docusaurus'
giscus: {
  repo: 'kuizuo/blog',
  repoId: 'MDEwOlJlcG9zaXRvcnkzOTc2Mxxxxx',
  category: 'General',
  categoryId: 'DIC_kwDOF7NJDM4CPK95',
  theme: 'light',
  darkTheme: 'dark',
}
```

:::info 切记一定要将上述数据替换成你的，如果不替换的话，评论的信息都将会在我的 Discussions 下。

:::

## [waline](https://github.com/walinejs/waline)

目前比较流行的博客评论系统还有 waline，它可以提供评论与浏览量服务，由于需要搭配后端服务与数据库服务，所以在配置方面会比 giscus 来的麻烦，但它无需 github Discussions，所以也是绝大多数博客作者的标配。

关于如何配置，参见官方 [快速上手 | Waline](https://waline.js.org/guide/get-started.html)


评论服务

stylelint 主要针对 css 样式进行格式化(包括css预处理器)，同时对一些属性拼写进行检查。

[Getting started | Stylelint](https://stylelint.io/user-guide/get-started)

配置文件示例：

```json title='.stylelintrc.json' icon='logos:stylelint'
{
  "extends": ["stylelint-config-recommended", "stylelint-config-standard"],
  "rules": {
    "indentation": 4
  }
}
```

## 配合 prettier

[prettier/stylelint-config-prettier](https://github.com/prettier/stylelint-config-prettier)


stylelint

Prettier 是一个固执己见的代码格式化程序。

[Install · Prettier](https://prettier.io/docs/en/install.html)

## 集成在 ESlint 中

ESlint 与 Prettier 可能会冲突，故需做如下设置：

```js
//1. 安装 eslint-config-prettier 插件
npm i -D eslint-config-prettier
//2. 在 eslint 的配置文件中写入以下内容
extends: ['plugin:prettier/recommended'], // 避免与 prettier 冲突
```

## prettier 与 eslint 如何选择

prettier 只需要按照一个 vscode 插件，几乎没有任何门槛，按下 Ctrl + Alt + F 就可以美化你的代码。而 eslint 需要配合代码编辑器与相关规则，通过保存文件或者执行 eslint 命令才能格式化代码。但往往也是因为过少的配置，使 prettier 对代码的约束不如 eslint。

可以看看 Antfu 大佬的博客 [Why I don't use Prettier (antfu.me)](https://antfu.me/posts/why-not-prettier)，阐述了他为何不使用 Prettier。

这两个我都有在使用，在临时编写 demo 代码的时候，肯定优先使用 prettier。

但是在实际项目中，如果不使用 eslint 的话，每次保存代码都需要手动格式化，还是比较繁琐的。


prettier

对于 pnpm 项目，通常会有一个 `.npmrc` 文件，用于配置npm的一些参数，比如使用pnpm的严格模式等，其内容如下。

```properties title='.npmrc' icon='logos:npm-icon'
shamefully-hoist=true
strict-peer-dependencies=false
shell-emulator=true
```

此外，配置仓库镜像源，node版本等等。更多配置可看 [.npmrc](https://pnpm.io/npmrc)。
