3 篇博文 含有标签「docusaurus」

最佳实践：Typora+docusaurus完美解决(云笔记+知识库+博客)需求​

目录​

[toc]

版权​

前言​

写在前面​

背景​

==我为什么要写这篇文章呢？==

因为我自己是一个it从业者，那么日常笔记数据对自己来说就特别重要，俗话说，好记性不如烂笔头，那么如何安全地维护好自己的工作经验沉淀数据、日常学习记录数据、生活数据等等，就显得特别重要。（我相信，每个人都有属于自己的重要数据）

自己之前用过各种云笔记，例如word/有道云/notion/wolai/语雀……等等，到最后发现都各种问题，一言难尽，因为来回切换笔记数据真的很麻烦，也很浪费时间。

后买你无意间发现了typora（md软件领域的扛把子），发现用typora来记录和阅读自己的笔记数据真的是一种享受。

后来又发现了docusaurus，发现它真的是静态站点构建工具里的no1，特备适合自己构建知识库，同时，它也提供了博客功能。且有好看的主题及强大的社区。

因此，typora与docusaurus的相遇注定成为很多人理想的内容管理工具。

接下来的这篇文章就是我的关于"云笔记+知识库+博客"的最佳实践，欢迎交流。😉

常见云笔记分类​

大致上可以将笔记软件分为几大类：

1）传统的笔记软件：这类一般以 Word、WPS、OneNote为代表。缺点：一般不支持 Markdown 文件格式，需要花费更多的时间在对内容的排版上。

2）云笔记软件：这类笔记软件的特点，是数据都存储在云端，在本地没有备份。一般都是支持Markdown格式，并且有些也支持双链笔记【就是在一个笔记里可以直接引用其它的笔记，然后点击后直接跳转】。这类一般以：语雀、网易云笔记、wolai、notion、飞书 为代表。 缺点：笔记有一个特点就是数据都是存储在远程服务器（数据被牢牢绑定）；并且如果是免费版本只提供很少的空间；

3）本地笔记软件：这类软件的特点和云笔记的特点就是，数据都存储在本地。常见的代表作有：Typora、Obsidian、思源。

写博客的好处​

在学习到一些新技术的时候，会用笔记的方式把操作的流程记录下来，一方面是为了能够更快的掌握这块技能，同时也方便后续对看过的知识进行回归，进一步对内容进行巩固。同时写成博客后，也可以分享到互联网上进行传播，帮助到更多的人。

你的笔记需求​

• 笔记数据安全且完全可控；（禁止与第三方厂商绑定）
• 笔记数据由markdown维护；
• pc端编辑，多端可查看内容；
• 数据完全本地化；
• ……

软件介绍​

==typora介绍：==

写Markdown费事？Typora让你像写word一样行云流水，所见即所得。

Typora 是一款适配 Windows / macOS / Linux 平台的 Markdown 编辑器，编辑实时预览标记格式，所见即所得，轻巧而强大。

typora就是专为 markdown 语法打造的一款软件。

• Typora删除了预览窗口，以及所有其他不必要的干扰。取而代之的是实时预览。
• Markdown的语法因不同的解析器或编辑器而异，Typora使用的是GitHub Flavored Markdown。

Typora 最舒服的是所见即所得的排版，以及实时渲染带来的沉浸式写作体验，非常舒服。

用官方的话描述：

Typora 提供同时读写的无缝体验，删除了预览窗口、模式切换器、markdown 源代码的语法符号以及所有其他不必要的干扰。相反，提供了真正的实时预览功能，可帮助您专注于内容本身。

==docusaurus介绍：==

Docusaurus是一款基于React的开源文档站点生成器，它可以帮助开发者快速构建出现代化、易于维护的文档网站。Docusaurus是由Facebook开发的，最初是为React Native文档而创建的。现在，Docusaurus已经成为开发者在创建和维护文档站点时的首选工具之一。

Docusaurus是一个基于React和Node.js构建的开源工具，旨在帮助开发人员快速构建易于管理和维护的文档站点。

Docusaurus的优势之一是它的==易用性==。它提供了一套现成的模板和主题，让开发者可以快速开始构建文档站点。另外，Docusaurus还提供了一个实时预览功能，让开发者可以在本地进行修改和调试，从而加快开发效率。

Docusaurus支持Markdown和==MDX格式==的文档，这意味着开发者可以使用简单的文本编辑器来编写和更新文档。此外，Docusaurus还提供了一些插件和工具，例如搜索和版本控制，使得文档站点的维护更加简单和高效。

除此之外，Docusaurus还具有高度的可定制性。它使用React组件来构建页面，这意味着开发者可以轻松地自定义页面的外观和功能。此外，Docusaurus还支持多语言站点，可以满足不同语言用户的需求。

==vscode介绍：==

VS Code 的全称是 Visual Studio Code，是一款开源的、免费的、跨平台的、高性能的、轻量级的代码编辑器。它在性能、语言支持、开源社区方面，都做得很不错。

==Picgo介绍==：

PicGo: 一个用于快速上传图片并获取图片 URL 链接的工具。

使用markdown一直有一个痛点，那就是图片的问题，不想word那样可以直接保存图片，markdown不行，如果插入图片，图片在本地会单独存放，以链接的形式插入在markdown中，如果本地图片丢失或者位置变了，那就不显示了。

所以这里就需要一个图床，也就是把图片传上去，弄个链接，然后插入markdown中，那么图床不少，怎么传呢？

使用这个工具，只要复制下图片，然后按个快捷键就可以直接将图片上传到你事先设定好的图床上，然后返回给你个链接，可以直接用。

支持全平台，开源且免费，支持丰富的插件系统，推荐使用。使用 PicGo 上传图片的流程是这样的：先复制图片，然后通过一个快捷键上传图片到对应的图床（并直接返回一个该图片的直链到你的系统剪切板），此时你只需到你的 Markdown 内容中粘贴就完事了，整个过程不超过 5 秒钟。

==Everyting介绍：==

==坚果云：==

坚果云是一家中国的云存储服务提供商，为个人和企业用户提供数据存储、同步和共享服务。以下是关于坚果云的一些简介：

1. 数据存储：坚果云提供安全可靠的云存储空间，用户可以将个人或企业数据存储在云端，避免了数据丢失的风险。

2. 文件同步和共享：坚果云支持多设备文件同步，用户可以在不同的设备上访问和更新自己的文件，并确保文件的最新版本在各个设备间同步。此外，用户还可以通过链接将文件分享给他人，方便协作和共享。

3. 数据安全：坚果云提供高级的数据加密和安全性措施，确保用户的数据在传输和存储过程中受到保护。坚果云采用端到端加密技术，即使在数据传输和存储过程中，只有用户才能解密和访问数据。

4. 多平台支持：坚果云提供支持多种操作系统和平台的客户端应用程序，包括Windows、Mac、iOS和Android等，用户可以在不同的设备上方便地使用坚果云服务。

5. 备份和恢复：坚果云还提供备份和恢复功能，用户可以定期备份重要数据，以防数据丢失或设备损坏。

6. 个人和企业版本：坚果云提供个人和企业版本，个人用户可以选择适合自己需求的存储空间，企业用户可以享受更多的存储空间和专业的团队协作功能。

总之，坚果云是一个方便、安全、可靠的云存储服务提供商，适用于个人和企业用户管理和保护他们的数据。

方案​

1.方案设计​

1、本地元数据：

• Typora：主力编辑和阅读md文档；

• Vscode：管理笔记数据；（负责管理笔记视图、查找文件、全文查找等功能）（Everything：配合vscode查找文件；）

• 百度云盘：存放大型软件、音视频、照片、脚本、实验软件等；

• docusaurus仓库：持续更新自己的all知识点到这个文档库。（docusaurus仓库里的核心文档放在坚果云里免费进行云同步，其他本地笔记数据放在百度网盘同步空间里进行同步）

• md图床：（利用ecs的nginx来提供图床，图片数据会本地保存一份后再上传到图床，且利用rsync会每天定时从linux同步数据到本地windowsPC，很nice）

2、分享平台：

docusaurus公开知识库，博客，微信公众号，csdn，知乎；

2.方案优势​

• typora：md领域的扛把子；（编辑和阅读体验真的超丝滑）（可定制typora皮肤）
• docusaurus：静态站点构建工具的扛把子；（支持知识库+博客，且主题唯美）
• 数据完全本地化，与第三方厂商完全解耦；
• ……

3.成本把控​

4.维护原则​

docusaurus维护原则：

• 每一个md的排版都要简洁，清晰；
• 单个md内容不要太大，否则就拆分成多个md；
• 自己的docusaurus知识库只允许存放.md，目录，.sh/.py脚本，其他任何类型的数据禁止存放进去。

环境​

win10

ecs：

CentOS Linux release 7.9.2009 (Core)

ecs名称：docusaurus-wiki

配置规格：2c 2g 40g  ESSD Entry云盘 40GiB (2120 IOPS) 

源码​

链接：https://pan.baidu.com/s/1FG0opRQgJmX9i6jBSbsrVg?pwd=5vjj 提取码：5vjj 2024.8.23-Typora+docusaurus-softwares

前提条件​

• 具备基础的linux命令行能力
• 了解markdown语法：见《markdown语法》文章。
• 购买1台云服务器（自行百度）
• 购买一个域名（自行百度）

0、配置基础环境​

• 安装好git：见《实战：windows安装git-2022.5.4(测试成功)》文章。

  

• 在ecs上配置好nginx图传：见《nginx图床》文章。（会同时安装好rsync服务）

  

• 安装好nodejs：见《nodejs》文章。

  

• 给自己的http配置好https证书：见《使用Certbot签发免费ssl泛域名证书》文章。

  

1、安装typora​

1.安装typora​

• 来到typora官网，下载windows软件包，直接点击下一步完成安装

https://typoraio.cn/#

• 完成安装后，桌面出现如下图标

• 双击打开，输入购买的license

==配置typora：==

现在，我们来简单配置下typora：

2.安装picgo​

typora配置完成后，我们来安装下picgo，用来传输图片到图传上去。

• 来到picgo官网，下载windows软件包，直接点击下一步完成安装

https://molunerfinn.com/PicGo/

• 完成安装后，桌面出现如下图标

• 我们来配置下picgo

双击打开picgo，我们来配置下picgo的sftp插件：

自己本次配置

D:/docusaurus/resource/shell/sftpUploader.json

{
    "sftpUploader": {
        "url": "https://onedayxyy.cn",
        "path": "/images/{fullName}",
        "uploadPath": "/images/{fullName}",
        "host": "ecsip",
        "port": 22,
        "username": "root",
        "password": "123456"
    }
}

设置当前sftp方式为默认方式：

自己云服务器ecs地址：

自己域名：onedayxyy.cn
nginx图床配置路径：/images
图片url地址：http://onedayxyy.cn/images/image-20231123144421591.png

• picgo配置完后，我们来测试下图传是否能正常使用

点击文件-偏好设置-图像：

再点击验证图片上传选项：

能看到成功上传图片并获得新的url字样就代表我们的图传是可用的。

3.安装typora_plugin插件​

（扩展，但推荐安装）

下载链接：

https://github.com/obgnail/typora_plugin/releases/latest

注意：

使用typora_plugin插件时，强烈关闭如下各选项的自动编号功能，只保留图片自动编号即可：（否则该One主题有一些效果不能很好展示）

具体效果如下图：

2、安装docusaurus​

接下来，我们部署下docusaurus：

• 通过如下命令拉取代码，并在本地运行：

cd /d/
git config --global user.name  "hg_it_nuc"
git config --global user.email  "2675263825@qq.com"

git clone https://gitee.com/onlyonexl/one-docusaurus
cd one-docusaurus

#指定镜像源为华为源：
npm config set registry https://mirrors.huaweicloud.com/repository/npm/
pnpm config set registry https://mirrors.huaweicloud.com/repository/npm/

#安装好pnpm
npm install -g pnpm@9.4.0

#安装依赖包并启动
pnpm install
pnpm start

• 默认会在浏览器打开如下页面：

http://localhost:3000/

3、安装坚果云​

• 坚果云下载链接

https://www.jianguoyun.com/static/exe/installer/NutstoreWindowsWPFInstaller.exe

• 安装方法，一直下一步即可。

• 将同名目录修改为如下D:\docusaurus\docs路径

4、最佳姿势​

1.docus仓库存放位置​

2.一条命令完成内容发布​

• 配置vscode终端到ecs的免密

在docusaurus仓库，打开vscode：

##win10和ecs做免密，方便本地win10 脚本执行相关命令：
ssh-keygen
ssh-copy-id -i ~/.ssh/id_rsa.pub root@47.100.215.163 ##输入ecs密码
ssh root@47.100.215.163 date

# $ ls ~/.ssh/id_ed25519.pub 
# /c/Users/Administrator/.ssh/id_ed25519.pub
# $ ssh root@47.100.215.163 date
# Fri Apr 12 07:43:24 CST 2024

• 配置win10 vscode终端环境变量

##（1）配置一键推送PATH环境
cat >> /etc/profile <<EOF
alias xyy2="
sh /d/docusaurus/resource/shell/xyy2.sh
"
EOF
source /etc/profile


##（2）配置rsync PATH环境
#vscode的git bash终端,rsync客户端命令
echo 'PATH=/d/GreenSoftware/cwrsync_6.2.12_x64_free/bin:$PATH' >> /etc/profile
source /etc/profile


## (3)配置备份本地md脚本
echo  'alias backup="sh /d/docusaurus/resource/shell/md_backup.sh"' >> /etc/profile
source /etc/profile

• 验证

一条命令完成docusaurus构建静态数据并推送到ecs nginx目录：

xyy2

• web端验证

https://wiki.onedayxyy.cn/

5、数据备份​

1.docus仓库配置数据​

git备份/本地

2.本地md数据​

（坚果云来同步数据）

手动备份核心md数据：（每周一次）备份脚本：

D:\docusaurus\resource\shell\md_backup.sh

#!/bin/bash
echo "开始备份md核心数据……"

cd /d/BaiduSyncdisk/backup/mdBackup
tar -czvf /d/BaiduSyncdisk/backup/mdBackup/`date +%F_%H-%M-%S`-mdBackup.tar.gz /d/docusaurus/docs


echo -e
echo "md数据大小："
#会被强制覆盖掉当天的代码
du -sh /d/BaiduSyncdisk/backup/mdBackup/

echo -e
echo "已备份的md文件如下："
ls /d/BaiduSyncdisk/backup/mdBackup -tlh

本地vscode里配置环境变量：

echo  'alias backup="sh /d/docusaurus/resource/shell/md_backup.sh"' >> /etc/profile
source /etc/profile

效果：

直接执行backup命令即可实现自动备份：

3.图床数据​

在cmd输入compmgmt.msc

新建任务：MdImages-rsync-linux-to-winodws

利用rsync每天定期增量同步到本地：（可保证数据安全）

ecs上图床大小：

本地图床大小：

关于我​

我的博客主旨：

• 排版美观，语言精炼；
• 文档即手册，步骤明细，拒绝埋坑，提供源码；
• 本人实战文档都是亲测成功的，各位小伙伴在实际操作过程中如有什么疑问，可随时联系本人帮您解决问题，让我们一起进步！

🍀 微信二维码

x2675263825 （舍得）， qq：2675263825。

🍀 微信公众号

《云原生架构师实战》

🍀 个人主页：

https://onedayxyy.cn

🍀 知识库：

https://wiki.onedayxyy.cn/

🍀 博客：

http://blog.onedayxyy.cn/

🍀 csdn

https://blog.csdn.net/weixin_39246554?spm=1010.2135.3001.5421

🍀 知乎

https://www.zhihu.com/people/foryouone

往期推荐​

QQ群

玩转Typora+Docusuaurus+起始页交流群：（欢迎小伙伴一起探讨有趣的IT技术，来完成一些漂亮的项目）

我的开源项目：

https://wiki.onedayxyy.cn/docs/OpenSource

• typora皮肤

https://wiki.onedayxyy.cn/docs/typora

• 起始页

https://onedayxyy.cn/

• 知识库

https://wiki.onedayxyy.cn/

• 博客

https://blog.onedayxyy.cn/

• 家庭相册

https://photo.onedayxyy.cn/

最后​

好了，关于本次就到这里了，感谢大家阅读，最后祝大家生活快乐，每天都过的有意义哦，我们下期见！

实战：给自己docusaurus网站配置giscus评论服务-2024.8.30(测试成功)​

目录​

[toc]

环境​

2024年8月230日，已解决。

win10 Docusaurus version: 3.4.0 Node version: v20.12.1 pnpm 9.4.0 基于愧怍仓库

前言​

推荐两种评论服务

Giscus：基于GitHub Discussions，对程序员相对友好，评论信息提示通过github邮箱发送。

Waline：需要搭建后端服务与数据库服务，提供评论与浏览量服务，可拓展性强。

waline

目前比较流行的博客评论系统还有 waline，它可以提供评论与浏览量服务，由于需要搭配后端服务与数据库服务，所以在配置方面会比 giscus 来的麻烦，但它无需 github Discussions，所以也是绝大多数博客作者的标配。

关于如何配置，参见官方 快速上手 | Waline

简介​

如果你有自己的个人博客网站，为了增加互动，评论功能是必不可少的。可以借助giscus这一工具，快速为您的博客添加评论功能，无需从零开始开发复杂的UI页面、设计数据库及搭建后端服务，轻松提升博客的互动性。

==为什么选择giscus== 在众多评论插件或服务中，giscus凭借其显著的优势脱颖而出，成为个人博客主们的理想之选：

1. 免费且开源：作为一款基于GitHub Discussions的评论系统，giscus对个人用户完全免费，且遵循MIT开源许可协议，确保了使用的透明性和灵活性。

2. 一键集成：giscus提供简洁易用的配置界面和丰富的文档支持，只需几步简单的设置，即可将评论功能无缝嵌入到您的博客中，大大节省了从头开发所需的时间和精力。

3. 移植性强：无论您使用的是静态站点生成器（如Jekyll、Hugo、Hexo等）、CMS系统（如WordPress、Ghost等）还是自建网站，giscus都能轻松适应，确保评论功能在各种平台上的良好运行。

4. 服务稳定可靠：依托于GitHub的强大基础设施，giscus享有高度的稳定性和安全性。用户评论数据存储在您的GitHub仓库中，既便于管理，也免去了自行维护数据库的困扰。

==giscus的工作原理与优势解析==

1. 基于GitHub Discussions giscus的核心是利用GitHub Discussions作为评论的存储和交互平台。每篇博客文章对应一个GitHub Discussion话题，读者的评论即为该话题下的帖子。这种设计有如下优势：

• 社区化讨论氛围：读者可以在同一话题下展开深入讨论，形成围绕博文内容的社区交流环境。
• 用户身份认证：通过GitHub账户登录，简化了用户注册流程，同时增强了评论者的身份可信度。
• 通知与回复管理：作者和评论者能接收到实时通知，方便追踪讨论动态并及时回应。所有回复操作均在GitHub界面完成，操作体验熟悉且流畅。

2. 实时同步与定制化 giscus通过JavaScript SDK实时同步GitHub Discussions中的评论数据到您的博客页面，确保评论内容的即时更新。此外，giscus提供了丰富的定制选项：

• 主题样式：可选择预设的主题颜色或自定义CSS，以匹配您博客的整体视觉风格。
• 评论排序：支持按时间顺序、热度（点赞数）等规则展示评论。
• 评论过滤：可根据需要启用或禁用评论的匿名发布、 reactions（表情反应）等功能。

注意​

之前的评论使用的是 gitalk，但是那个是基于 github issue 的，并且 issue 不能关闭，每次打开仓库的时候都会看到几十个 issue，特别不友好。

所以后面就考虑换成 giscus，由 GitHub Discussions 驱动的评论系统。首先要确保以下几点：

1. 此仓库是公开的，否则访客将无法查看 discussion（并不需要一定是博客的项目，随便一个仓库都可以）。
2. giscus app 已安装否则访客将无法评论和回应。
3. Discussions 功能已在你的仓库中启用。

本博客已经内置好评论组件 src/component/Comment，所以只需要在 docusaurus.config.ts 中设置 giscus 的配置即可。

<script src="https://giscus.app/client.js"
        data-repo="OnlyOnexl/blog-kuizuo"
        data-repo-id="R_kgDOMkmSPw"
        data-category="General"
        data-category-id="DIC_kwDOMkmSP84CiBhH"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

前提​

首先你的拥有一个和我一样的漂亮docusaurus网站哦：

https://wiki.onedayxyy.cn/

该网站的开源仓库如下：

https://gitee.com/onlyonexl/one-docusaurus

0.提前创建一个公开仓库​

https://github.com/OnlyOnexl/OneDocusComment

1.安装giscus​

访问地址：https://github.com/apps/giscus，可以对你的github进行giscus的安装。点击右侧的install按钮进行安装即可，安装完后显示的页面如下：

2.选择仓库​

你可以选择需要开启Discussions功能的仓库。点击上面步骤中Configure按钮，进入配置页面，选择你想要的组织用户：

然后选择仓库，可以选择所有仓库，也可以单独选择：

3.开启Discussions功能​

进入对应的仓库，点击settings，找到Features，勾选

4.配置giscus​

访问地址https://giscus.app/zh-CN，进入配置页面

5.使用giscus​

配置完成后，配置页面底部会生成一段js代码，大致如下所示：

<script src="https://giscus.app/client.js"
        data-repo="[在此输入仓库]"
        data-repo-id="[在此输入仓库 ID]"
        data-category="[在此输入分类名]"
        data-category-id="[在此输入分类 ID]"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

把得到的脚本放入你的页面：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    <div class="giscus"></div>
   <script src="https://giscus.app/client.js"
        data-repo="替换成你的实际值"
        data-repo-id="替换成你的实际值"
        data-category="替换成你的实际值"
        data-category-id="替换成你的实际值"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="noborder_light"
        data-lang="zh-CN"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
</script>
</body>
</html>

页面中显示效果如下：

你可以在你的仓库中进行验证：

借助giscus，您可以在短时间内为个人博客添加一个功能完备、稳定可靠的评论系统，无需投入大量资源进行从头开发。让读者畅所欲言

6.自己本次细节​

• 在github创建一个专门用于自己docusaurus网站评论的公开库：

https://github.com/OnlyOnexl/OneDocusComment

• 配置细节

<script src="https://giscus.app/client.js"
        data-repo="OnlyOnexl/OneDocusComment"
        data-repo-id="R_kgDOMqCExQ"
        data-category="General"
        data-category-id="DIC_kwDOMqCExc4CiCRL"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="top"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
</script>

• 自己docus仓库配置：

由于我在 src/component/Comment 组件中做了配置合并，并且支持主题变化、国际化。因此，你只需要复制 data-repo, data-repo-id, data-category 和 data-category-id 填写到 docusaurus.config.ts 中即可，以下是我的配置文件。

docusaurus.config.tsjavascript

giscus: {
  repo: 'OnlyOnexl/OneDocusComment',
  repoId: 'R_kgDOMqCExQ',
  category: 'General',
  categoryId: 'DIC_kwDOMqCExc4CiCRL',
  theme: 'light',
  darkTheme: 'dark',
}

切记一定要将上述数据替换成你的，如果不替换的话，评论的信息都将会在我的 Discussions 下。

验证：

来到一篇博客最底部：

可以看到有评论界面：

使用自己github登录系统：

进行评论：

来到自己仓库看下：

同时，收到邮箱提醒：

提交本次更改，直接在网站上测试：

xyy2

(完美)

7.给docs也添加评论功能​

docs 文章界面开启评论服务

现在只有 blog 文章下面有评论功能，如果 docs 界面也要开启评论功能的话，但由于 Docusaurus 的 bug 导致切换文档时，在未刷新网页的情况下 Giscus 有时获取的仍然是上一篇文章的评论，为解决这一问题需要做一些小修改，参考以下方法：

安装所需包​

yarn add @giscus/react mitt

本次命令：

pnpm install @giscus/react mitt

封装评论组件​

报错的话不用理，只需确认评论功能是否正常即可

1.配置声明周期函数​

在根目录下创建文件 src/clientModules/routeModules.ts

src/clientModules/routeModules.ts

import mitt from 'mitt';
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

const emitter = mitt();

if (ExecutionEnvironment.canUseDOM) {
  window.emitter = emitter;
}

export function onRouteDidUpdate() {
  if (ExecutionEnvironment.canUseDOM) {
    setTimeout(() => {
      window.emitter.emit('onRouteDidUpdate');
    });
  }
  // https://github.com/facebook/docusaurus/issues/8278
}

2.修改评论组件​

直接复制并将原有的覆盖即可

src/components/comment/index.tsx

import {useColorMode} from '@docusaurus/theme-common';
import BrowserOnly from '@docusaurus/BrowserOnly';
import React, { forwardRef, useEffect, useState } from 'react';
import Giscus, { GiscusProps } from '@giscus/react';
import { useThemeConfig, ThemeConfig } from '@docusaurus/theme-common';

interface CustomThemeConfig extends ThemeConfig {
  giscus: GiscusProps & { darkTheme: string };
}

export const Comment = forwardRef<HTMLDivElement>((_props, ref) => {
  const themeConfig = useThemeConfig() as any;
  const theme = useColorMode().colorMode === 'dark' ? 'dark' : 'light';
  const { giscus } = useThemeConfig() as CustomThemeConfig;
  const [routeDidUpdate, setRouteDidUpdate] = useState(false);

  useEffect(() => {
    function eventHandler(e) {
      setRouteDidUpdate(true);
    }

    window.emitter.on('onRouteDidUpdate', eventHandler);

    return () => {
      window.emitter.off('onRouteDidUpdate', eventHandler);
    };
  }, []);

  if (!routeDidUpdate) {
    return null;
  }

  const options: GiscusProps = {
    ...(themeConfig.giscus as GiscusProps),
    id: 'comments',
    reactionsEnabled: '1',
    emitMetadata: '0',
    inputPosition: 'top',
    theme,
  };
  return (
    <BrowserOnly fallback={<div>Loading Comments...</div>}>
      {() => <Giscus {...options} />}
    </BrowserOnly>
  );
});

export default Comment;

3.安装 swizzling 文档页面对应组件​

yarn run swizzle @docusaurus/theme-classic DocItem/Layout -- --eject --typescript

个人命令：

pnpm swizzle @docusaurus/theme-classic DocItem/Layout --eject --typescript

这里他会报一个警告，选择 yes 就行

为什么会报警告呢？这是官方文档给的部分说明:

完成后就会在根目录下生成如下文件

这里需要进行一点修改，添加如下代码

import React from 'react';
import clsx from 'clsx';
import { useWindowSize } from '@docusaurus/theme-common';
// @ts-ignore
import { useDoc } from '@docusaurus/theme-common/internal';
import DocItemPaginator from '@theme/DocItem/Paginator';
import DocVersionBanner from '@theme/DocVersionBanner';
import DocVersionBadge from '@theme/DocVersionBadge';
import DocItemFooter from '@theme/DocItem/Footer';
import DocItemTOCMobile from '@theme/DocItem/TOC/Mobile';
import DocItemTOCDesktop from '@theme/DocItem/TOC/Desktop';
import DocItemContent from '@theme/DocItem/Content';
import DocBreadcrumbs from '@theme/DocBreadcrumbs';
import type { Props } from '@theme/DocItem/Layout';

import styles from './styles.module.css';
import Comment from '../../../components/Comment';

/**
 * Decide if the toc should be rendered, on mobile or desktop viewports
 */
function useDocTOC() {
  const { frontMatter, toc } = useDoc();
  const windowSize = useWindowSize();

  const hidden = frontMatter.hide_table_of_contents;
  const canRender = !hidden && toc.length > 0;

  const mobile = canRender ? <DocItemTOCMobile /> : undefined;

  const desktop =
    canRender && (windowSize === 'desktop' || windowSize === 'ssr') ? (
      <DocItemTOCDesktop />
    ) : undefined;

  return {
    hidden,
    mobile,
    desktop
  };
}

export default function DocItemLayout({ children }: Props): JSX.Element {
  const docTOC = useDocTOC();
  const { frontMatter } = useDoc();
  const { hide_comment: hideComment } = frontMatter;

  return (
    <div className="row">
      <div className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
        <DocVersionBanner />
        <div className={styles.docItemContainer}>
          <article>
            <DocBreadcrumbs />
            <DocVersionBadge />
            {docTOC.mobile}
            <DocItemContent>{children}</DocItemContent>
            <DocItemFooter />
          </article>
          <DocItemPaginator />
        </div>
        {!hideComment && <Comment />}
      </div>
      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
    </div>
  );
}

• 修改 docusaurus.config.js 文件

module.exports = {
  themeConfig: {
    giscus: {
      repo: 'xxx',
      repoId: 'xxx',
      category: 'Announcements',
      categoryId: 'xxx'
    }
  },
  clientModules: [require.resolve('./src/clientModules/routeModules.ts')]
};

完成以上步骤后即可以到你文档界面查看就可以了（Swizzling 后需要重新运行 Docusaurus ，不然是无法看到效果的）。 对于某些不想开启评论功能的文章，只需在前言中加入：hide_comment: true

验证​

我们这里直接推送，然后验证doc的评论服务：

执行xyy2：

完美。

参考与致谢​

• shaking：《Giscus 评论系统》

• csdn的render-ydb 博主：《5分钟，为你的博客增加评论功能》

• 愧怍：《评论服务》

• Docusaurus 添加评论功能

关于我​

我的博客主旨：

• 排版美观，语言精炼；
• 文档即手册，步骤明细，拒绝埋坑，提供源码；
• 本人实战文档都是亲测成功的，各位小伙伴在实际操作过程中如有什么疑问，可随时联系本人帮您解决问题，让我们一起进步！

🍀 微信二维码

x2675263825 （舍得）， qq：2675263825。

🍀 微信公众号

《云原生架构师实战》

🍀 个人主页：

https://onedayxyy.cn

🍀 知识库：

https://wiki.onedayxyy.cn/

🍀 博客：

http://blog.onedayxyy.cn/

🍀 csdn

https://blog.csdn.net/weixin_39246554?spm=1010.2135.3001.5421

🍀 知乎

https://www.zhihu.com/people/foryouone

往期推荐​

QQ群

玩转Typora+Docusuaurus+起始页交流群：（欢迎小伙伴一起探讨有趣的IT技术，来完成一些漂亮的项目）

我的开源项目：

https://wiki.onedayxyy.cn/docs/OpenSource

• typora皮肤

https://wiki.onedayxyy.cn/docs/typora

• 起始页

https://onedayxyy.cn/

• 知识库

https://wiki.onedayxyy.cn/

• 博客

https://blog.onedayxyy.cn/

• 家庭相册

https://photo.onedayxyy.cn/

最后​

好了，关于本次就到这里了，感谢大家阅读，最后祝大家生活快乐，每天都过的有意义哦，我们下期见！

实战：部署全网最美docusaurus网站-2024.8.18(测试成功)​

目录​

[toc]

版权声明​

强烈推荐：

博主愧怍 ：

https://kuizuo.cn/

https://github.com/kuizuo/blog

QQ群里一位大佬：月桂树在嘉陵江喝咖啡

https://gitee.com/renlangman2/docusaurus352

背景​

原博主愧怍 不是已经有开源库了吗？为啥自己又要出这篇文章呢？

因为因为最近有小伙伴反馈原作者的代码无法部署成功？？？。。。。

自己测试了下，发现的确无法部署成功了……

排查了好久也没发现问题：。。。

作者最新代码是2周前才提交的哇。。。。；

自己老仓库本地是可以做正常运行的，但是新拉的仓库不行；。。。。；

作者的仓库克隆到github，然后用netfliy是可以正常运行的；。。。。；

奇怪了：。。。

自己评估可能出现的原因：。。。

可能是作者魔改后的docus里，有些node依赖包，被官方源丢弃了，导致无法正常下载依赖包。。。。。/相关语法错误；

恰好群里有位大佬改了下代码，让其用yarn来部署项目，结果发现可以了哦。🤣

因此输出了这篇文章。

环境​

win10
Docusaurus version: 3.4.0
Node version: v20.12.1
yarn 1.22.22

源码​

gitee库：

https://gitee.com/onlyonexl/mogai-docus-kuizuo-v2.git

本地：

说明​

前提​

win10提前安装好nodejs环境。

如何安装nodejs，请访问官网（一直下一步安装就好）：

https://nodejs.org/en/download/

1、拉取代码​

git clone https://gitee.com/onlyonexl/mogai-docus-kuizuo-v2.git

2、安装yarn​

进入mogai-docus-kuizuo-v2目录：

安装yarn：

npm install --global yarn
yarn --version

3、下载依赖包​

yarn install

3、运行项目​

yarn start

关于我​

我的博客主旨：

• 排版美观，语言精炼；
• 文档即手册，步骤明细，拒绝埋坑，提供源码；
• 本人实战文档都是亲测成功的，各位小伙伴在实际操作过程中如有什么疑问，可随时联系本人帮您解决问题，让我们一起进步！

🍀 微信二维码

x2675263825 （舍得）， qq：2675263825。

🍀 微信公众号

《云原生架构师实战》

🍀 个人主页：

https://onedayxyy.cn

🍀 知识库：

https://wiki.onedayxyy.cn/

🍀 博客：

http://blog.onedayxyy.cn/

🍀 csdn

https://blog.csdn.net/weixin_39246554?spm=1010.2135.3001.5421

🍀 知乎

https://www.zhihu.com/people/foryouone

往期推荐​

QQ群

玩转Typora+Docusuaurus+起始页交流群：（欢迎小伙伴一起探讨有趣的IT技术，来完成一些漂亮的项目）

我的开源项目：

https://wiki.onedayxyy.cn/docs/OpenSource

• typora皮肤

https://wiki.onedayxyy.cn/docs/typora

• 起始页

https://onedayxyy.cn/

• 知识库

https://wiki.onedayxyy.cn/

• 博客

https://blog.onedayxyy.cn/

• 家庭相册

https://photo.onedayxyy.cn/

最后​

好了，关于本次就到这里了，感谢大家阅读，最后祝大家生活快乐，每天都过的有意义哦，我们下期见！