feat: 启用评论系统 (#35)

启用 giscus 评论系统

docusaurus.config.js

@@ -94,6 +94,16 @@ const config = {
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
+      // giscus 评论
+      giscus: {
+        repo: 'BetterECNU/SharedCourses',
+        repoId: 'R_kgDOMR1oyA',
+        category: 'Announcements',
+        categoryId: 'DIC_kwDOMR1oyM4CvymL',
+        theme: 'light_high_contrast',
+        darkTheme: 'dark_tritanopia'
+      },
+
       // Replace with your project's social card
       image: 'img/docusaurus-social-card.jpg',
       navbar: {
@@ -174,6 +184,8 @@ const config = {
     mermaid: true,
   },
   themes:['@docusaurus/theme-mermaid'],
+  // 以下部分为启用giscus评论
+  clientModules: [require.resolve('./src/clientModules/routeModules.ts')]
 };
 
 export default config;

package-lock.json

@@ -12,8 +12,10 @@
         "@docusaurus/preset-classic": "3.8.1",
         "@docusaurus/theme-mermaid": "^3.8.1",
         "@easyops-cn/docusaurus-search-local": "^0.52.1",
+        "@giscus/react": "^3.1.0",
         "@mdx-js/react": "^3.0.0",
         "clsx": "^2.0.0",
+        "mitt": "^3.0.1",
         "prism-react-renderer": "^2.3.0",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
@@ -4395,6 +4397,18 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@giscus/react": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/@giscus/react/-/react-3.1.0.tgz",
+      "integrity": "sha512-0TCO2TvL43+oOdyVVGHDItwxD1UMKP2ZYpT6gXmhFOqfAJtZxTzJ9hkn34iAF/b6YzyJ4Um89QIt9z/ajmAEeg==",
+      "dependencies": {
+        "giscus": "^1.6.0"
+      },
+      "peerDependencies": {
+        "react": "^16 || ^17 || ^18 || ^19",
+        "react-dom": "^16 || ^17 || ^18 || ^19"
+      }
+    },
     "node_modules/@hapi/hoek": {
       "version": "9.3.0",
       "resolved": "https://registry.npmjs.org/@hapi/hoek/-/hoek-9.3.0.tgz",
@@ -4522,6 +4536,21 @@
       "integrity": "sha512-Vo+PSpZG2/fmgmiNzYK9qWRh8h/CHrwD0mo1h1DzL4yzHNSfWYujGTYsWGreD000gcgmZ7K4Ys6Tx9TxtsKdDw==",
       "license": "MIT"
     },
+    "node_modules/@lit-labs/ssr-dom-shim": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/@lit-labs/ssr-dom-shim/-/ssr-dom-shim-1.4.0.tgz",
+      "integrity": "sha512-ficsEARKnmmW5njugNYKipTm4SFnbik7CXtoencDZzmzo/dQ+2Q0bgkzJuoJP20Aj0F+izzJjOqsnkd6F/o1bw==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@lit/reactive-element": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@lit/reactive-element/-/reactive-element-2.1.1.tgz",
+      "integrity": "sha512-N+dm5PAYdQ8e6UlywyyrgI2t++wFGXfHx+dSJ1oBrg6FAxUj40jId++EaRm80MKX5JnlH1sBsyZ5h0bcZKemCg==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@lit-labs/ssr-dom-shim": "^1.4.0"
+      }
+    },
     "node_modules/@mdx-js/mdx": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/@mdx-js/mdx/-/mdx-3.1.1.tgz",
@@ -5640,8 +5669,7 @@
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/@types/trusted-types/-/trusted-types-2.0.7.tgz",
       "integrity": "sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==",
-      "license": "MIT",
+      "license": "MIT"
-      "optional": true
     },
     "node_modules/@types/unist": {
       "version": "3.0.3",
@@ -9684,6 +9712,15 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/giscus": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/giscus/-/giscus-1.6.0.tgz",
+      "integrity": "sha512-Zrsi8r4t1LVW950keaWcsURuZUQwUaMKjvJgTCY125vkW6OiEBkatE7ScJDbpqKHdZwb///7FVC21SE3iFK3PQ==",
+      "license": "MIT",
+      "dependencies": {
+        "lit": "^3.2.1"
+      }
+    },
     "node_modules/github-slugger": {
       "version": "1.5.0",
       "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-1.5.0.tgz",
@@ -11283,6 +11320,37 @@
       "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==",
       "license": "MIT"
     },
+    "node_modules/lit": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/lit/-/lit-3.3.1.tgz",
+      "integrity": "sha512-Ksr/8L3PTapbdXJCk+EJVB78jDodUMaP54gD24W186zGRARvwrsPfS60wae/SSCTCNZVPd1chXqio1qHQmu4NA==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@lit/reactive-element": "^2.1.0",
+        "lit-element": "^4.2.0",
+        "lit-html": "^3.3.0"
+      }
+    },
+    "node_modules/lit-element": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/lit-element/-/lit-element-4.2.1.tgz",
+      "integrity": "sha512-WGAWRGzirAgyphK2urmYOV72tlvnxw7YfyLDgQ+OZnM9vQQBQnumQ7jUJe6unEzwGU3ahFOjuz1iz1jjrpCPuw==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@lit-labs/ssr-dom-shim": "^1.4.0",
+        "@lit/reactive-element": "^2.1.0",
+        "lit-html": "^3.3.0"
+      }
+    },
+    "node_modules/lit-html": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/lit-html/-/lit-html-3.3.1.tgz",
+      "integrity": "sha512-S9hbyDu/vs1qNrithiNyeyv64c9yqiW9l+DBgI18fL+MTvOtWoFR0FWiyq1TxaYef5wNlpEmzlXoBlZEO+WjoA==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@types/trusted-types": "^2.0.2"
+      }
+    },
     "node_modules/loader-runner": {
       "version": "4.3.0",
       "resolved": "https://registry.npmjs.org/loader-runner/-/loader-runner-4.3.0.tgz",
@@ -13976,6 +14044,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/mitt": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz",
+      "integrity": "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==",
+      "license": "MIT"
+    },
     "node_modules/mlly": {
       "version": "1.8.0",
       "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.0.tgz",

package.json

@@ -18,8 +18,10 @@
     "@docusaurus/preset-classic": "3.8.1",
     "@docusaurus/theme-mermaid": "^3.8.1",
     "@easyops-cn/docusaurus-search-local": "^0.52.1",
+    "@giscus/react": "^3.1.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
+    "mitt": "^3.0.1",
     "prism-react-renderer": "^2.3.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

src/clientModules/routeModules.ts

@@ -0,0 +1,17 @@
+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
+}

src/components/comment/index.tsx

@@ -0,0 +1,58 @@
+import React, { forwardRef, useEffect, useState } 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 = forwardRef<HTMLDivElement>((_props, ref) => {
+  const { giscus } = useThemeConfig() as CustomThemeConfig;
+  const { colorMode } = useColorMode();
+  const { theme = 'light', darkTheme = 'dark_dimmed' } = giscus;
+  const giscusTheme = colorMode === 'dark' ? darkTheme : theme;
+  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;
+  }
+
+  return (
+    <BrowserOnly fallback={<div>Loading Comments...</div>}>
+      {() => (
+        <div ref={ref} id="comment" style={{ paddingTop: 50 }}>
+          <Giscus
+            id="comments"
+            mapping="title"
+            strict="1"
+            reactionsEnabled="1"
+            emitMetadata="0"
+            inputPosition="bottom"
+            lang="zh-CN"
+            loading="lazy"
+            {...giscus}
+            theme={giscusTheme}
+          />
+        </div>
+      )}
+    </BrowserOnly>
+  );
+});
+
+export default Comment;

src/theme/BlogPostPage/Metadata/index.tsx

@@ -0,0 +1,37 @@
+import React, {type ReactNode} from 'react';
+import {PageMetadata} from '@docusaurus/theme-common';
+import {useBlogPost} from '@docusaurus/plugin-content-blog/client';
+
+export default function BlogPostPageMetadata(): ReactNode {
+  const {assets, metadata} = useBlogPost();
+  const {title, description, date, tags, authors, frontMatter} = metadata;
+
+  const {keywords} = frontMatter;
+  const image = assets.image ?? frontMatter.image;
+  return (
+    <PageMetadata
+      title={frontMatter.title_meta ?? title}
+      description={description}
+      keywords={keywords}
+      image={image}>
+      <meta property="og:type" content="article" />
+      <meta property="article:published_time" content={date} />
+      {/* TODO double check those article meta array syntaxes, see https://ogp.me/#array */}
+      {authors.some((author) => author.url) && (
+        <meta
+          property="article:author"
+          content={authors
+            .map((author) => author.url)
+            .filter(Boolean)
+            .join(',')}
+        />
+      )}
+      {tags.length > 0 && (
+        <meta
+          property="article:tag"
+          content={tags.map((tag) => tag.label).join(',')}
+        />
+      )}
+    </PageMetadata>
+  );
+}

src/theme/BlogPostPage/StructuredData/index.tsx

@@ -0,0 +1,14 @@
+import React, {type ReactNode} from 'react';
+import Head from '@docusaurus/Head';
+import {useBlogPostStructuredData} from '@docusaurus/plugin-content-blog/client';
+
+export default function BlogPostStructuredData(): ReactNode {
+  const structuredData = useBlogPostStructuredData();
+  return (
+    <Head>
+      <script type="application/ld+json">
+        {JSON.stringify(structuredData)}
+      </script>
+    </Head>
+  );
+}

src/theme/BlogPostPage/index.tsx

@@ -0,0 +1,75 @@
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {HtmlClassNameProvider, ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  BlogPostProvider,
+  useBlogPost,
+} from '@docusaurus/plugin-content-blog/client';
+import BlogLayout from '@theme/BlogLayout';
+import BlogPostItem from '@theme/BlogPostItem';
+import BlogPostPaginator from '@theme/BlogPostPaginator';
+import BlogPostPageMetadata from '@theme/BlogPostPage/Metadata';
+import BlogPostPageStructuredData from '@theme/BlogPostPage/StructuredData';
+import TOC from '@theme/TOC';
+import ContentVisibility from '@theme/ContentVisibility';
+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;
+}): ReactNode {
+  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
+      }>
+      <ContentVisibility metadata={metadata} />
+
+      <BlogPostItem>{children}</BlogPostItem>
+
+      {(nextItem || prevItem) && (
+        <BlogPostPaginator nextItem={nextItem} prevItem={prevItem} />
+      )}
+      {!hideComment && <Comment />}
+    </BlogLayout>
+  );
+}
+
+export default function BlogPostPage(props: Props): ReactNode {
+  const BlogPostContent = props.content;
+  return (
+    <BlogPostProvider content={props.content} isBlogPostPage>
+      <HtmlClassNameProvider
+        className={clsx(
+          ThemeClassNames.wrapper.blogPages,
+          ThemeClassNames.page.blogPostPage,
+        )}>
+        <BlogPostPageMetadata />
+        <BlogPostPageStructuredData />
+        <BlogPostPageContent sidebar={props.sidebar}>
+          <BlogPostContent />
+        </BlogPostPageContent>
+      </HtmlClassNameProvider>
+    </BlogPostProvider>
+  );
+}

src/theme/DocItem/Layout/index.tsx

@@ -0,0 +1,68 @@
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {useWindowSize} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+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 ContentVisibility from '@theme/ContentVisibility';
+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): ReactNode {
+  const docTOC = useDocTOC();
+  const { frontMatter } = useDoc();
+  const { hide_comment: hideComment } = frontMatter;
+  const {metadata} = useDoc();
+  return (
+    <div className="row">
+      <div className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
+        <ContentVisibility metadata={metadata} />
+        <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>
+  );
+}

src/theme/DocItem/Layout/styles.module.css

@@ -0,0 +1,10 @@
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}