跳到主要内容

Docusaurus 添加评论功能

获取 Giscus 配置参数

首先根据 Giscus 官网 的步骤配置安装并获取配置后的参数。

选择 giscus 连接到的仓库。请确保:

  1. 此仓库是公开的,否则访客将无法查看 discussion。
  2. giscus app 已安装否则访客将无法评论和回应。
  3. Discussions 功能已在你的仓库中启用。

Docusaurus 中安装 Giscus

yarn add @giscus/react

然后我们封装一个评论组件方便使用

src/components/comment/index.tsx
import React from 'react';
import BrowserOnly from '@docusaurus/BrowserOnly';
import Giscus, { GiscusProps } from '@giscus/react';
import {
useThemeConfig,
useColorMode,
ThemeConfig
} from '@docusaurus/theme-common';

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

export const Comment = () => {
const { giscus } = useThemeConfig() as CustomThemeConfig;
const { colorMode } = useColorMode();
const { theme = 'light', darkTheme = 'dark_dimmed' } = giscus;
const giscusTheme = colorMode === 'dark' ? darkTheme : theme;

return (
<BrowserOnly fallback={<div>Loading Comments...</div>}>
{() => (
<div style={{ paddingTop: 50 }}>
<Giscus
id="comments"
mapping="title"
strict="1"
term="Welcome to @giscus/react component!"
reactionsEnabled="1"
emitMetadata="0"
inputPosition="bottom"
lang="zh-CN"
loading="lazy"
{...giscus}
theme={giscusTheme}
/>
</div>
)}
</BrowserOnly>
);
};

export default Comment;

Swizzling Docusaurus 内部组件

Docusaurus 页面分为文档和博客,自己根据需求 Swizzling 对应的页面组件。

Swizzling 文档页面对应组件

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

因为我的项目是基于 typescript 的,如果你的项目是 javascript 的话,则不需要加后面的 --typescript

Swizzling 后会生成 src/theme/DocItem/Layout 目录,我们需要对 src/theme/DocItem/Layout/index.tsx 进行修改

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>
);
}

Swizzling 博客页面对应组件

yarn run swizzle @docusaurus/theme-classic BlogPostPage -- --eject --typescript

同样修改文件

src/theme/BlogPostPage/index.tsx
import React, { type ReactNode } from 'react';
import clsx from 'clsx';
import {
HtmlClassNameProvider,
ThemeClassNames
} from '@docusaurus/theme-common';

import {
BlogPostProvider,
useBlogPost
// @ts-ignore
} from '@docusaurus/theme-common/internal';
import BlogLayout from '@theme/BlogLayout';
import BlogPostItem from '@theme/BlogPostItem';
import BlogPostPaginator from '@theme/BlogPostPaginator';
import BlogPostPageMetadata from '@theme/BlogPostPage/Metadata';
import TOC from '@theme/TOC';
import type { Props } from '@theme/BlogPostPage';
import type { BlogSidebar } from '@docusaurus/plugin-content-blog';
import Comment from '../../components/comment';

function BlogPostPageContent({
sidebar,
children
}: {
sidebar: BlogSidebar;
children: ReactNode;
}): JSX.Element {
const { metadata, toc } = useBlogPost();
const { nextItem, prevItem, frontMatter } = metadata;
const {
hide_table_of_contents: hideTableOfContents,
toc_min_heading_level: tocMinHeadingLevel,
toc_max_heading_level: tocMaxHeadingLevel,
hide_comment: hideComment
} = frontMatter;
return (
<BlogLayout
sidebar={sidebar}
toc={
!hideTableOfContents && toc.length > 0 ? (
<TOC
toc={toc}
minHeadingLevel={tocMinHeadingLevel}
maxHeadingLevel={tocMaxHeadingLevel}
/>
) : undefined
}
>
<BlogPostItem>{children}</BlogPostItem>
{(nextItem || prevItem) && (
<BlogPostPaginator nextItem={nextItem} prevItem={prevItem} />
)}
{!hideComment && <Comment />}
</BlogLayout>
);
}

export default function BlogPostPage(props: Props): JSX.Element {
const BlogPostContent = props.content;
return (
<BlogPostProvider content={props.content} isBlogPostPage>
<HtmlClassNameProvider
className={clsx(
ThemeClassNames.wrapper.blogPages,
ThemeClassNames.page.blogPostPage
)}
>
<BlogPostPageMetadata />
<BlogPostPageContent sidebar={props.sidebar}>
<BlogPostContent />
</BlogPostPageContent>
</HtmlClassNameProvider>
</BlogPostProvider>
);
}
警告

Swizzling 后需要重新运行 Docusaurus ,不然是无法看到效果的

提示

对于不需要评论的文章,在前言中加入 hide_comment: true

配置 Giscus

docusaurus.config.js
module.exports = {
themeConfig: {
giscus: {
repo: 'xxx',
repoId: 'xxx',
category: 'Announcements',
categoryId: 'xxx'
}
}
};

黑夜模式

根据自己喜好修改配置

docusaurus.config.js
giscus: {
theme: 'light_high_contrast',
darkTheme: 'dark_tritanopia'
},
信息

默认的主题分别是:light, dark_dimmed

大功告成

完成以上步骤后你就可以在每篇博客和每篇文档的底部看到评论功能了

Loading Comments...