Skip to main content

使用docusaurus2搭建个人博客

· 7 min read
hec9527

每次搬迁博客之前都很纠结到底要不要搬,毕竟博客搬迁费时费力,如果没有解决之前的痛点,得到想要的效果,收益小于付出,还不如维持现状专注以内容产出。但是当我第一看看到 docusaurus2 之后,我决定尝试一下。 docusaurus2 是由 react 构建,mdx 驱动的静态文档搭建工具。

为什么会选择 docusaurus2

之前用过很多博客托管网站,比如 CSDN、博客园、雨雀、docsify、gitbook 等,但没有一款能让人满意,CSDN 环境太差,商业气息浓重,很多人比如我,直接把 CSDN 加入了搜索引擎黑名单,用来写博客,推广起来比较麻烦。之前也用过博客园,但是博客园只支持富文本,并且博客园和 CSDN 一样有非常多质量很低的文章,通常都是复制粘贴别人的文章,甚至格式都不修改的,看到最后突然冒出来一个原文链接。 雨雀用得比较少,docsify 之前我用过,并且在 vercel 上面托管了一个博客,这也是我主要使用的博客,不过这个与其说是一个博客,倒不如说是一个文档,它的网站风格更多像是一个文档,不适合用来托管博客,同时也缺少很多博客的订阅信息。

至于为什么不用鼎鼎大名的 wordpress,是因为最开始的时候我的目标就很明确,静态博客。wordpress 需要后台不能简单的托管在 github pages, 也不能托管在其他的静态资源托管网站。最后在 hexo 和 docusaurus2 之间反复横跳,hexo 的优势就是它有非常丰富的网站主题,套用起来也很方便,可以把博客做得非常花里胡哨,但是我们写博客的目的是做好内容产出,而不是炫技,docusaurus2 使用 react 驱动,我们可以自由的扩展博客的功能,还可以在 mdx 文档中使用 react 组件,同时 docusaurus2 的默认样式也非常不错,不仅支持黑色主题,还适配移动端。

如何安装 docusaurus2

docusaurus2 官方有非常详细的中文文档了,安装使用可以直接查看官方文档,我这里就不做文档搬运这种无聊的事了

docusaurus2 安装

如何配置 algolia 搜索

使用 algolia 搜索,首先需要在项目中安装这个依赖,如果创建项目的时候使用的 classic 模板,那么项目中默认是安装过的

npm install --save @docusaurus/theme-search-algolia

前往 [algolia](Apply for DocSearch) 注册应用,并且生成 Algolia 索引和 API Key,生成 API key 需要添加 addObject, delObject 权限

docusaurus.config.js
themeConfig: {
// ...
algolia: {
appId: 'YOUR_APP_ID', // 没有就用这个 BH4D9OD16A
apiKey: 'YOUR_API_KEY',
indexName: 'YOUR_INDEX_NAME',
contextualSearch: true,
},
// ...
}

如何修改内置组件

之前差点因为 docusaurus2 缺乏定制化的能力而放弃, 然而 docusaurus2 提供了组件变换的工具,如果你对某个主题组件的功能或者样式不满意,可以使用将组件变换出来,修改其中的功能。比如我们想给博客添加评论的功能,自带的主题是不包括这个功能的,所以我们需要修改主题中的组件达到我们的目的。我们先将 BlogPostPage 组件变换出来,这个是用来展示博客内容以及分页等功能的组件,我们可以在这个里面插入评论功能,评论组件我们使用 gitalk。

--typescript参数是可选的,如果添加了--typescript,则变换的组件为ts组件,否则为js

# 使用这种方式弹出组件
npm run swizzle <theme name> [component name] [--typescript]

插入评论组件分为以下几步

  1. 弹出我们想要修改的容器组件
  2. 注册 github 应用
  3. 使用 gitalk 编写评论组件
  4. 在容器组件里面合适的地方插入评论组件
# 弹出内置组件,实现定制化修改
npx docusaurus swizzle @docusaurus/theme-classic NavBar --danger

这里添加 --danger,是因为目前 docusaurus2 还处于 beta 阶段,部分内置组件可能会改变。接下来我们编写一个评论的组件, 首先需要安装 gitalk 依赖,然后去 github 注册应用

npm i gitalk
src/theme/GitTalkCommit/index.tsx
import React, { useEffect } from 'react';
import Gitalk from 'gitalk';
import 'gitalk/dist/gitalk.css';

const GitTalkCommit: React.FC = () => {
useEffect(() => {
new Gitalk({
admin: ['hec9527'],
clientID: '********', // 填写github注册应用的 clientID
clientSecret: '************', // 密码只会显示一次,注册完成后记得保存
repo: 'blog', // 选一个存在的仓库,用户评论会存放在这里
owner: 'hec9527',
id: 'hec9527-123',
distractionFreeMode: true,
}).render('gitalk-container');
}, []);

return <div id='gitalk-container' />;
};

GitTalkCommit.displayName = 'GitTalkCommit';

export default GitTalkCommit;

现在我们在 <BlogPostPage /> 组件中找一个合适的地方插入这个 <GitTalkCommit /> 组件

src/theme/BlogPostPage/index.js
<BlogPostItem frontMatter={frontMatter} assets={assets} metadata={metadata} isBlogPostPage>
<BlogPostContents />
</BlogPostItem>;
{
(nextItem || prevItem) && <BlogPostPaginator nextItem={nextItem} prevItem={prevItem} />;
}
// 在这里,我们把评论组件放在分页按钮后面
<GitTalkCommit />;
danger

注意,目前(2021-12-06)为止,docusaurus2 目前还处于 beta 版本, 内置的组件将来可能会改变,如果弹出并且修改了内置组件,更新 docusaurus 的时候,可能会出现项目无法启动的问题。

这时候基本就需要重新弹出组件,并且编写逻辑