feat: add discussion giscus feature

jackyzha0 · May 7, 2024 · 89df64e · 89df64e
1 parent d03fdc2
commit 89df64e
Show file tree

Hide file tree

Showing 7 changed files with 205 additions and 24 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -2,10 +2,12 @@
 title: Configuration
 ---
 
-Quartz is meant to be extremely configurable, even if you don't know any coding. Most of the configuration you should need can be done by just editing `quartz.config.ts` or changing [[layout|the layout]] in `quartz.layout.ts`.
+Quartz is meant to be extremely configurable, even if you don't know any coding. Most of the configuration you should
+need can be done by just editing `quartz.config.ts` or changing [[layout|the layout]] in `quartz.layout.ts`.
 
 > [!tip]
-> If you edit Quartz configuration using a text-editor that has TypeScript language support like VSCode, it will warn you when you you've made an error in your configuration, helping you avoid configuration mistakes!
+> If you edit Quartz configuration using a text-editor that has TypeScript language support like VSCode, it will warn
+> you when you you've made an error in your configuration, helping you avoid configuration mistakes!
 
 The configuration of Quartz can be broken down into two main parts:
 
@@ -18,27 +20,43 @@ const config: QuartzConfig = {
 
 ## General Configuration
 
-This part of the configuration concerns anything that can affect the whole site. The following is a list breaking down all the things you can configure:
+This part of the configuration concerns anything that can affect the whole site. The following is a list breaking down
+all the things you can configure:
 
 - `pageTitle`: title of the site. This is also used when generating the [[RSS Feed]] for your site.
 - `enableSPA`: whether to enable [[SPA Routing]] on your site.
 - `enablePopovers`: whether to enable [[popover previews]] on your site.
 - `analytics`: what to use for analytics on your site. Values can be
   - `null`: don't use analytics;
   - `{ provider: 'google', tagId: '<your-google-tag>' }`: use Google Analytics;
-  - `{ provider: 'plausible' }` (managed) or `{ provider: 'plausible', host: '<your-plausible-host>' }` (self-hosted): use [Plausible](https://plausible.io/);
-  - `{ provider: 'umami', host: '<your-umami-host>', websiteId: '<your-umami-website-id>' }`: use [Umami](https://umami.is/);
-  - `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id' }` (managed) or `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id', host: 'my-goatcounter-domain.com', scriptSrc: 'https://my-url.to/counter.js' }` (self-hosted) use [GoatCounter](https://goatcounter.com);
-  - `{ provider: 'posthog', apiKey: '<your-posthog-project-apiKey>', host: '<your-posthog-host>' }`: use [Posthog](https://posthog.com/);
+  - `{ provider: 'plausible' }` (managed) or `{ provider: 'plausible', host: '<your-plausible-host>' }` (self-hosted):
+    use [Plausible](https://plausible.io/);
+  - `{ provider: 'umami', host: '<your-umami-host>', websiteId: '<your-umami-website-id>' }`:
+    use [Umami](https://umami.is/);
+  - `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id' }` (managed)
+    or `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id', host: 'my-goatcounter-domain.com', scriptSrc: 'https://my-url.to/counter.js' }` (
+    self-hosted) use [GoatCounter](https://goatcounter.com);
+  - `{ provider: 'posthog', apiKey: '<your-posthog-project-apiKey>', host: '<your-posthog-host>' }`:
+    use [Posthog](https://posthog.com/);
   - `{ provider: 'tinylytics', siteId: '<your-site-id>' }`: use [Tinylytics](https://tinylytics.app/);
+- `discussion`: add users discussion/comment feature. Currently support `giscus`. Please check [[discussion|here]]
 - `locale`: used for [[i18n]] and date formatting
-- `baseUrl`: this is used for sitemaps and RSS feeds that require an absolute URL to know where the canonical 'home' of your site lives. This is normally the deployed URL of your site (e.g. `quartz.jzhao.xyz` for this site). Do not include the protocol (i.e. `https://`) or any leading or trailing slashes.
-  - This should also include the subpath if you are [[hosting]] on GitHub pages without a custom domain. For example, if my repository is `jackyzha0/quartz`, GitHub pages would deploy to `https://jackyzha0.github.io/quartz` and the `baseUrl` would be `jackyzha0.github.io/quartz`.
-  - Note that Quartz 4 will avoid using this as much as possible and use relative URLs whenever it can to make sure your site works no matter _where_ you end up actually deploying it.
-- `ignorePatterns`: a list of [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) patterns that Quartz should ignore and not search through when looking for files inside the `content` folder. See [[private pages]] for more details.
-- `defaultDateType`: whether to use created, modified, or published as the default date to display on pages and page listings.
+- `baseUrl`: this is used for sitemaps and RSS feeds that require an absolute URL to know where the canonical 'home' of
+  your site lives. This is normally the deployed URL of your site (e.g. `quartz.jzhao.xyz` for this site). Do not
+  include the protocol (i.e. `https://`) or any leading or trailing slashes.
+  - This should also include the subpath if you are [[hosting]] on GitHub pages without a custom domain. For example,
+    if my repository is `jackyzha0/quartz`, GitHub pages would deploy to `https://jackyzha0.github.io/quartz` and
+    the `baseUrl` would be `jackyzha0.github.io/quartz`.
+  - Note that Quartz 4 will avoid using this as much as possible and use relative URLs whenever it can to make sure
+    your site works no matter _where_ you end up actually deploying it.
+- `ignorePatterns`: a list of [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) patterns that Quartz should
+  ignore and not search through when looking for files inside the `content` folder. See [[private pages]] for more
+  details.
+- `defaultDateType`: whether to use created, modified, or published as the default date to display on pages and page
+  listings.
 - `theme`: configure how the site looks.
-  - `cdnCaching`: If `true` (default), use Google CDN to cache the fonts. This will generally will be faster. Disable (`false`) this if you want Quartz to download the fonts to be self-contained.
+  - `cdnCaching`: If `true` (default), use Google CDN to cache the fonts. This will generally will be faster.
+    Disable (`false`) this if you want Quartz to download the fonts to be self-contained.
   - `typography`: what fonts to use. Any font available on [Google Fonts](https://fonts.google.com/) works here.
     - `header`: Font to use for headers
     - `code`: Font for inline and block quotes.
@@ -62,35 +80,45 @@ You can think of Quartz plugins as a series of transformations over content.
 ```ts title="quartz.config.ts"
 plugins: {
   transformers: [...],
-  filters: [...],
-  emitters: [...],
+    filters
+:
+  [...],
+    emitters
+:
+  [...],
 }
 ```
 
 - [[tags/plugin/transformer|Transformers]] **map** over content (e.g. parsing frontmatter, generating a description)
 - [[tags/plugin/filter|Filters]] **filter** content (e.g. filtering out drafts)
-- [[tags/plugin/emitter|Emitters]] **reduce** over content (e.g. creating an RSS feed or pages that list all files with a specific tag)
+- [[tags/plugin/emitter|Emitters]] **reduce** over content (e.g. creating an RSS feed or pages that list all files with
+  a specific tag)
 
-You can customize the behaviour of Quartz by adding, removing and reordering plugins in the `transformers`, `filters` and `emitters` fields.
+You can customize the behaviour of Quartz by adding, removing and reordering plugins in the `transformers`, `filters`
+and `emitters` fields.
 
 > [!note]
-> Each node is modified by every transformer _in order_. Some transformers are position sensitive, so you may need to pay particular attention to whether they need to come before or after certain other plugins.
+> Each node is modified by every transformer _in order_. Some transformers are position sensitive, so you may need to
+> pay particular attention to whether they need to come before or after certain other plugins.
 
-You should take care to add the plugin to the right entry corresponding to its plugin type. For example, to add the [[ExplicitPublish]] plugin (a [[tags/plugin/filter|Filter]]), you would add the following line:
+You should take care to add the plugin to the right entry corresponding to its plugin type. For example, to add
+the [[ExplicitPublish]] plugin (a [[tags/plugin/filter|Filter]]), you would add the following line:
 
 ```ts title="quartz.config.ts"
 filters: [
   ...
-  Plugin.ExplicitPublish(),
+    Plugin.ExplicitPublish(),
   ...
 ],
 ```
 
 To remove a plugin, you should remove all occurrences of it in the `quartz.config.ts`.
 
-To customize plugins further, some plugins may also have their own configuration settings that you can pass in. If you do not pass in a configuration, the plugin will use its default settings.
+To customize plugins further, some plugins may also have their own configuration settings that you can pass in. If you
+do not pass in a configuration, the plugin will use its default settings.
 
-For example, the [[plugins/Latex|Latex]] plugin allows you to pass in a field specifying the `renderEngine` to choose between Katex and MathJax.
+For example, the [[plugins/Latex|Latex]] plugin allows you to pass in a field specifying the `renderEngine` to choose
+between Katex and MathJax.
 
 ```ts title="quartz.config.ts"
 transformers: [
@@ -99,7 +127,8 @@ transformers: [
 ]
 ```
 
-Some plugins are included by default in the[ `quartz.config.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz.config.ts), but there are more available.
+Some plugins are included by default in
+the[ `quartz.config.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz.config.ts), but there are more available.
 
 You can see a list of all plugins and their configuration options [[tags/plugin|here]].
 

diff --git a/docs/features/discussion.md b/docs/features/discussion.md
@@ -0,0 +1,65 @@
+### Disabled this feature
+
+- `discussion: null` or simply remove this properties
+
+### Enable this feature
+
+Please visit [here](https://giscus.app/) and follow the instructions, include enable giscus app, allow permission for giscus to access your repository.
+
+Get configuration that are generated and fill the quartz configuration .
+
+```typescript title="quartz.config.ts"
+const config: QuartzConfig = {
+  configuration: {
+    ...,
+    discussion: {
+      provider: "giscus",
+      configuration: {
+        dataRepo: "<data-repo>",
+        dataRepoId: "<data-repo-id>",
+        dataCategory: "<data-category>",
+        dataCategoryId: "<data-category-id>",
+      },
+    },
+
+    ...
+  }
+
+```
+
+> [!note]
+> By default, four fields `data-repo/id` and `data-category/id` must be fill by yourself. And there are 10 other fields
+> have default settings. You can overwrite them.
+
+| Name                   | Default value                  |
+| ---------------------- | ------------------------------ |
+| src                    | "https://giscus.app/client.js" |
+| data-strict            | "0"                            |
+| data-mapping           | "pathname"                     |
+| data-reactions-enabled | "1"                            |
+| data-emit-metadata     | "1"                            |
+| data-input-position    | "top"                          |
+| data-theme             | "preferred_color_scheme"       |
+| data-lang              | "en"                           |
+| data-loading           | "lazy"                         |
+| data-origin            | "anonymous"                    |
+
+Finally, add discussion/comment session to your `quartz.layout.ts`
+
+```typescript title="quartz.layout.ts"
+export const defaultContentPageLayout: PageLayout = {
+  beforeBody: [
+    ...
+  ],
+  left: [
+    ...
+  ],
+  right: [
+    ...
+  ],
+  //@ts-ignore
+  footer: Component.Discussion(),
+}
+
+
+```
diff --git a/quartz.config.ts b/quartz.config.ts
@@ -14,6 +14,16 @@ const config: QuartzConfig = {
     analytics: {
       provider: "plausible",
     },
+    discussion: {
+      provider: "giscus",
+      configuration: {
+        dataRepo: "<data-repo>",
+        dataRepoId: "<data-repo-id>",
+        dataCategory: "<data-category>",
+        dataCategoryId: "<data-category-id>",
+      },
+    },
+
     locale: "en-US",
     baseUrl: "quartz.jzhao.xyz",
     ignorePatterns: ["private", "templates", ".obsidian"],

diff --git a/quartz.layout.ts b/quartz.layout.ts
@@ -33,6 +33,8 @@ export const defaultContentPageLayout: PageLayout = {
     Component.DesktopOnly(Component.TableOfContents()),
     Component.Backlinks(),
   ],
+  //@ts-ignore
+  footer: Component.Discussion(),
 }
 
 // components for pages that display lists of pages  (e.g. tags or folders)

diff --git a/quartz/cfg.ts b/quartz/cfg.ts
@@ -35,6 +35,28 @@ export type Analytics =
       siteId: string
     }
 
+export type GiscusConfiguration = {
+  src?: string
+  dataRepo: string
+  dataRepoId: string
+  dataCategory: string
+  dataCategoryId: string
+  dataMapping?: string
+  dataStrict?: string
+  dataReactionsEnabled?: string
+  dataEmitMetadata?: string
+  dataInputPosition?: string
+  dataTheme?: string
+  dataLang?: string
+  dataLoading?: string
+  crossorigin?: string
+}
+
+export type DiscussionSettings = null | {
+  provider: string
+  configuration: GiscusConfiguration
+}
+
 export interface GlobalConfiguration {
   pageTitle: string
   /** Whether to enable single-page-app style rendering. this prevents flashes of unstyled content and improves smoothness of Quartz */
@@ -61,6 +83,8 @@ export interface GlobalConfiguration {
    * Region Codes: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
    */
   locale: ValidLocale
+  /** Discussion settings **/
+  discussion?: DiscussionSettings
 }
 
 export interface QuartzConfig {

diff --git a/quartz/components/Discussion.tsx b/quartz/components/Discussion.tsx
@@ -0,0 +1,50 @@
+import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "./types"
+
+const Discussion: QuartzComponent = ({ cfg }: QuartzComponentProps) => {
+  const discussion = cfg.discussion
+
+  const configuration = discussion?.configuration
+  const src = configuration?.src ? configuration.src : "https://giscus.app/client.js"
+  const dataStrict = configuration?.dataStrict ? configuration.dataStrict : "0"
+  const dataMapping = configuration?.dataMapping ? configuration.dataMapping : "pathname"
+  const dataReactionsEnabled = configuration?.dataReactionsEnabled
+    ? configuration.dataReactionsEnabled
+    : "1"
+  const dataEmitMetadata = configuration?.dataEmitMetadata ? configuration.dataEmitMetadata : "1"
+  const dataInputPosition = configuration?.dataInputPosition
+    ? configuration.dataInputPosition
+    : "top"
+  const dataTheme = configuration?.dataTheme ? configuration.dataTheme : "preferred_color_scheme"
+  const dataLang = configuration?.dataLang ? configuration.dataLang : "en"
+  const dataLoading = configuration?.dataLoading ? configuration.dataLoading : "lazy"
+  const crossOrigin = configuration?.crossorigin ? configuration.crossorigin : "anonymous"
+
+  if (discussion?.provider === "giscus") {
+    return (
+      <>
+        <script
+          src={src}
+          data-repo={discussion.configuration.dataRepo}
+          data-repo-id={discussion.configuration.dataRepoId}
+          data-category={discussion.configuration.dataCategory}
+          data-category-id={discussion.configuration.dataCategoryId}
+          data-mapping={dataMapping}
+          data-strict={dataStrict}
+          data-reactions-enabled={dataReactionsEnabled}
+          data-emit-metadata={dataEmitMetadata}
+          data-input-position={dataInputPosition}
+          data-theme={dataTheme}
+          data-lang={dataLang}
+          data-loading={dataLoading}
+          crossorigin={crossOrigin}
+          async
+        ></script>
+        <div id="disqus_thread"></div>
+      </>
+    )
+  } else {
+    return null
+  }
+}
+
+export default (() => Discussion) satisfies QuartzComponentConstructor
diff --git a/quartz/components/index.ts b/quartz/components/index.ts
@@ -19,7 +19,7 @@ import DesktopOnly from "./DesktopOnly"
 import MobileOnly from "./MobileOnly"
 import RecentNotes from "./RecentNotes"
 import Breadcrumbs from "./Breadcrumbs"
-
+import Discussion from "./Discussion"
 export {
   ArticleTitle,
   Content,
@@ -42,4 +42,5 @@ export {
   RecentNotes,
   NotFound,
   Breadcrumbs,
+  Discussion,
 }