pester · fflaten · May 3, 2023 · May 5, 2023 · May 5, 2023 · Jan 3, 2024
diff --git a/.editorconfig b/.editorconfig
@@ -9,5 +9,5 @@ trim_trailing_whitespace = true
 indent_size = 4
 max_line_length = 80
 
-[*.{json,ps1xml,props,xml,yaml,css}]
+[*.{json,ps1xml,props,xml,yaml,css,js}]
 indent_size = 2
diff --git a/README.md b/README.md
@@ -72,6 +72,9 @@ To upgrade docusaurus to a more recent version:
    - `package.json`
    - `yarn.lock`
 
+> **Warning**
+> Giscus comments are implemented using a unsafe [swizzle](https://docusaurus.io/docs/swizzling#ejecting) of `DocItem/Layout` that could break in minor upgrades of Docusaurus. See [comments here](https://github.com/pester/docs/blob/main/src/theme/DocItem/Layout/index.js) for update instructions.
+
 ## Code of Conduct
 
 In the interest of fostering an open and welcoming environment, we as

diff --git a/giscus.json b/giscus.json
@@ -0,0 +1,11 @@
+{
+  "origins": [
+    "https://pester.dev",
+    "https://pester-docs.netlify.app"
+  ],
+  "originsRegex": [
+    "https://deploy-preview-[0-9]+--pester-docs.netlify.app",
+    "http://localhost:[0-9]+"
+  ],
+  "defaultCommentOrder": "oldest"
+}
diff --git a/package.json b/package.json
@@ -16,6 +16,7 @@
   "dependencies": {
     "@docusaurus/core": "^3.0.0",
     "@docusaurus/preset-classic": "^3.0.0",
+    "@giscus/react": "^2.2.8",
     "@mdx-js/react": "^3.0.0",
     "@tanstack/react-table": "^8.10.0",
     "clsx": "^1.2.1",

diff --git a/src/components/Giscus/Giscus.js b/src/components/Giscus/Giscus.js
@@ -0,0 +1,53 @@
+import Head from '@docusaurus/Head';
+import { useLocation } from '@docusaurus/router';
+import { useColorMode } from '@docusaurus/theme-common';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import Giscus from "@giscus/react";
+import React from 'react';
+import styles from './styles.module.css';
+
+/**
+ * Adds a meta-tag to ensure new dicussion always add the canonical link in the initial post.
+ * Avoids any localhost etc. if first reaction/post was made from a preview build
+ *
+ * See https://github.com/giscus/giscus/blob/main/ADVANCED-USAGE.md#giscusbacklink
+ */
+export function GiscusHead() {
+  const {
+    siteConfig: { url: siteUrl },
+  } = useDocusaurusContext();
+  const { pathname } = useLocation();
+  const canonicalUrl = siteUrl + useBaseUrl(pathname);
+
+  return (
+    <Head>
+      <meta name="giscus:backlink" content={canonicalUrl} />
+    </Head>
+  )
+}
+
+export function GiscusComponent() {
+  const { colorMode } = useColorMode();
+
+  return (
+    <section className={styles.commentsSection}>
+      <Giscus
+        repo="fflaten/docs"
+        repoId="MDEwOlJlcG9zaXRvcnkzMDY2ODYxNTc"
+        category="Comments"
+        categoryId="DIC_kwDOEkeozc4CWO6M"
+        mapping="pathname"
+        strict="1"
+        reactionsEnabled="1"
+        emitMetadata="0"
+        inputPosition="top"
+        theme={colorMode}
+        lang="en"
+        loading="lazy"
+        crossorigin="anonymous"
+        async
+      />
+    </section>
+  );
+}
diff --git a/src/components/Giscus/styles.module.css b/src/components/Giscus/styles.module.css
@@ -0,0 +1,3 @@
+.commentsSection {
+  margin-top: 2rem;
+}
diff --git a/src/theme/DocItem/Layout/index.js b/src/theme/DocItem/Layout/index.js
@@ -0,0 +1,73 @@
+/**
+ * Unsafe swizzle = might break in future minor upgrades.
+ * Run "yarn swizzle @docusaurus/theme-classic DocItem/Layout --eject --danger" and compare the diff.
+ *
+ * Our customizations are marked with comments below
+ */
+
+import React from 'react';
+import clsx from 'clsx';
+import { useWindowSize } from '@docusaurus/theme-common';
+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 Unlisted from '@theme/Unlisted';
+import styles from './styles.module.css';
+/* Customization start */
+import { GiscusHead, GiscusComponent } from '../../../components/Giscus/Giscus';
+/* Customization end */
+
+/**
+ * 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 }) {
+  const docTOC = useDocTOC();
+  const {
+    metadata: { unlisted },
+  } = useDoc();
+  return (
+    <div className="row">
+      <div className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
+        {unlisted && <Unlisted />}
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <DocItemFooter />
+          </article>
+          <DocItemPaginator />
+        </div>
+        {/* Customization start */}
+        <GiscusHead />
+        <GiscusComponent />
+        {/* Customization end */}
+      </div>
+      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+    </div>
+  );
+}
diff --git a/src/theme/DocItem/Layout/styles.module.css b/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;
+  }
+}