在 VitePress 中集成 Giscus 评论系统

Giscus 是一个基于 GitHub Discussions 的评论系统。本文将详细介绍如何使用 vitepress-plugin-comment-with-giscus 插件在 VitePress 中集成 Giscus，包括针对私有仓库的特殊解决方案和 Giscus GitHub App 的安装过程。

Giscus 官方网站

在开始之前，请访问 Giscus 的官方网站：https://giscus.app

这个网站提供了 Giscus 的详细说明、配置选项，也是获取必要配置信息的地方。

针对私有仓库的解决方案

如果您的 VitePress 项目仓库是私有的，您可以创建一个单独的公开仓库来专门用于 Giscus 评论系统。这种方法有以下优点：

保护主要项目代码：您的 VitePress 项目代码仍然可以保持私有。
评论管理分离：将评论与主要项目分开管理可能更加方便。
保持 Giscus 的所有功能：由于使用公开仓库，您可以充分利用 Giscus 的所有特性。

步骤

创建新的公共仓库：
- 在 GitHub 上创建一个新的公共仓库，专门用于存储评论。
- 可以给它起一个相关的名字，比如 "my-site-comments"。
在新仓库中启用 Discussions：
- 进入仓库设置。
- 在 "Features" 部分启用 "Discussions"。
安装 Giscus GitHub App：这一步骤非常重要，下面是详细的操作指南：
a. 访问 Giscus GitHub App 安装页面：https://github.com/apps/giscus
这是安装 Giscus GitHub App 的直接链接，点击它将直接带您到安装页面。
b. 在安装页面上，点击绿色的 "Install" 按钮。
c. 选择安装位置：
- 如果您有多个组织账户，GitHub 会询问您想在哪里安装 Giscus。
- 选择您的个人账户或包含新创建的公共仓库的组织。
d. 配置仓库访问：
- 在下一页，您可以选择将 Giscus 安装到所有仓库，或者只选择特定的仓库。
- 为了安全起见，建议选择 "Only select repositories"。
- 然后从列表中选择您新创建的用于评论的公共仓库。
e. 确认安装：
- 仔细检查您的选择是否正确。
- 点击 "Install" 按钮确认安装。
f. 授权访问：
- GitHub 可能会要求您再次输入密码以确认此操作。
g. 完成安装：
- 安装完成后，您会被重定向到 Giscus 的配置页面或者您的 GitHub 设置页面。
安装完成后，Giscus 就获得了访问您指定仓库 Discussions 的权限。这使得 Giscus 可以创建、读取和管理 Discussions，这是评论系统正常工作所必需的。
配置 Giscus：
- 访问 Giscus 配置页面。
- 使用新创建的公共仓库信息进行配置。
- 选择其他所需的设置（如语言、主题等）。

在 VitePress 中集成 Giscus

使用 vitepress-plugin-comment-with-giscus 插件可以简化集成过程。

安装插件

安装 vitepress-plugin-comment-with-giscus 插件：

bash

# 使用 npm
npm i vitepress-plugin-comment-with-giscus

# 或者使用 yarn
yarn add vitepress-plugin-comment-with-giscus

配置插件

在 .vitepress/theme 目录下的 index.js 文件中添加以下配置：

import DefaultTheme from 'vitepress/theme';
import giscusTalk from 'vitepress-plugin-comment-with-giscus';
import { useData, useRoute } from 'vitepress';
import { toRefs } from "vue";

export default {
...DefaultTheme,
enhanceApp(ctx) {
DefaultTheme.enhanceApp(ctx);
},
setup() {
const { frontmatter } = toRefs(useData());
const route = useRoute();

        giscusTalk({
            repo: 'your-username/your-repo-name',
            repoId: 'your-repo-id',
            category: 'Announcements', // 或其他分类
            categoryId: 'your-category-id',
            mapping: 'pathname',
            inputPosition: 'top',
            lang: 'zh-CN',
            lightTheme: 'light',
            darkTheme: 'transparent_dark',
        }, {
            frontmatter,
            route
        }, true);
    }
};

获取 Giscus 配置

要获取必要的配置信息，请按照以下步骤操作：

访问 Giscus 配置页面

填写您的仓库信息（使用公共评论仓库的信息）并选择偏好设置在生成的脚本中找到相应的配置值

自定义选项

homePageShowComment: 设置是否在首页显示评论区（默认为 false） locales: 配置多语言支持在 frontmatter 中使用 comment: false 可以在特定页面禁用评论

在 VitePress 中集成 Giscus 评论系统 ​

Giscus 官方网站 ​

针对私有仓库的解决方案 ​

步骤 ​

在 VitePress 中集成 Giscus ​

安装插件 ​

配置插件 ​

获取 Giscus 配置 ​

访问 Giscus 配置页面 ​

自定义选项 ​