F.R.W.D

🌱 How I add comments to freewill.dev

6 min read

In this seed I share how I gave my garden a voice — by adding comments with Giscus.

Intro (Motivation & Why)

A garden feels more alive when visitors can walk through it and leave their own traces. Writing is already a way for me to learn and share, but I also want freewill.dev to be a place where ideas spark conversations — not just a quiet monologue.

Quartz makes it easy to add comments, and since it supports Giscus out of the box, that was an easy choice. Giscus is open source, privacy-friendly, and built on GitHub Discussions — which fits perfectly with my values of freedom and self-reliance.

Guide Overview

  1. Configure GitHub repo + Giscus app
  2. Configure Quartz to add Giscus for comments
  3. Customize Comments component - Behavior + Style
  4. Test locally
  5. Deploy changes

Prerequisites

  • ✅ A working Quartz site (from Seed 1)
  • ✅ Git + deployment setup working
  • ✅ A public GitHub repo

Steps

Step 1 — Configure GitHub repo + Giscus app

1.1 - Configure GitHub repo

Checklist - Per Gitcus Site

  1. The repository is public, otherwise visitors will not be able to view the discussion.
  2. The giscus app is installed, otherwise visitors will not be able to comment and react.
  3. The Discussions feature is turned on by enabling it for your repository.

Figure 1 — Giscus - Repo requirements

✅ Repository is public

I create a new repo for Giscus and I make it public repo

Figure 2 — GitHub - Repo config

✅ giscus app is installed

I go to https://github.com/apps/giscus to install Giscus to my repo.

Figure 3 — GitHub - Install Giscus app

GitHub will ask you where to install it:

  • Your personal account → if your repo is under your username
  • An organization → if your repo lives under a GitHub org Basically you choose location where you have GitHub repo for hosting discussions / giscus comments

Note

You can install Giscus for ALL repositories under your username/organization, or only for selected repositories. In my case, I want to install it for my selected repository only.

TIP

Under GitHub settings, you can see list of installed GitHub apps

Figure 4 — GitHub Settings - GitHub Apps

Figure 5 — GitHub Settings - Installed GitHub Apps

✅ Discussions feature is turned on

Just follow instructions here to enable “Discussions” feature

Go to repo > Settings , scroll down to see “Discussions” under Features. Check the checkbox to turn it on.

Note

We don’t have to “Set up discussions” - Giscus will create it as needed !.

Figure 6 — GitHub Features - Enable Discussions

Verify GitHub repo settings

Go to https://giscus.app/#repository, type in my repo to validate

→ yay, I see Success! This repository meets all of the above criteria.

1.2 - Configure Giscus app

Page ↔️ Discussions Mapping

I keep the default “Page ↔️ Discussions Mapping” option = “Discussion title contains page pathname”.

Giscus looks for a Discussion whose title includes the page’s URL path.

If no matching discussion exists, it can automatically create one.

This option is Good for static sites (like Quartz), because every page has a unique, stable path.

Discussion Category

As mentioned in Giscus app page, it’s recommended to use “Announcements” as “Discussion Category”.

So let’s just do it !!!

Other Giscus settings

I keep the rest of settings with default options.

Collect Giscus config info

In Giscus app page, scroll down to “Enable giscus” section to collect information that is needed to configure Quartz

  • data-repo
  • data-repo-id
  • data-category
  • data-category-id

We’d need this info later to configure Quartz !

Step 2 — Configure Quartz to add Giscus for comments

Once we have GitHub repo + Giscus app configured, let’s update Quartz to include Giscus for Comments.

Per instructions in Quartz page, I add Comments component to afterBody in quartz.layout.ts and boom I have Comments in freewill.dev now 😊 🎉🎉🎉

Figure 7 — Quartz with working Comments feature

TIP

by default, all pages will display comments, to disable it for a specific page, set comments to false. Quartz can conditionally display the comment box based on a field comments in the frontmatter.

So I disable comments for pages like index, FRWD Garden

---
title: Comments disabled here!
comments: false
---

However, this “default comments on” is NOT what I like, because I don’t want comments to be displayed on “tags” page. So I’ll customize that behavior of Comments component in next step.

Step 3 — Customize Comments component - Behavior + Style

3.1 - Change to “default comments off”

Figure 8 — Quartz with working Comments feature

So I’ll change this “default on” behavior of Comments component to “defaults comments off” unless frontmatter comments: true

quartz/components/Comments.tsx
// check if comments should be displayed according to frontmatter
    const enableComment: boolean =
	  fileData.frontmatter?.comments === true ||
	  fileData.frontmatter?.comments === "true"
	  
    if (!enableComment) {
      return <></>
    }

3.2 - Change Giscus theme

Changing Giscus theme in Quartz is quite straightforward.

Quartz comes with default light + dark themes for Giscus. You can find those .css files in quartz/static/giscus folder. I’ll use those files as base for my custom themes. And I put the custom .css files in same quartz/static/giscus folder.

Figure 9 — Custom Giscus themes in Quartz

Once I have those custom themes created, I need to update Comments component configuration in quartz.layout.ts to use the new theme

quartz.layout.ts
afterBody: [
    Component.QuartzCustomDivider(),
    Component.Comments({
      provider: 'giscus',
      options: {
        // from data-repo
        repo: '...',
        // from data-repo-id
        repoId: '...',
        // from data-category
        category: 'Announcements',
        // from data-category-id
        categoryId: '...',
        // from data-lang
        lang: 'en',
        lightTheme: 'frwd-light-v2',
        darkTheme: 'frwd-dark-v2'
      }
    }),
  ],

Step 4 — Test locally

WARN

Hold on, why my custom theme is not working ???. Comments component UI looks quite messed up after updating.

What’s actually happening

Giscus renders in an iframe served from https://giscus.app. That iframe fetches my custom theme CSS from my domain → this is a cross‑origin request, and my Caddy web server does NOT have CORS configured for this case yet.

After applying Recipe - Enable CORS in Caddy (Example = Giscus Themes), custom theme ALMOST works 😅. WHY …?

It turns out, by default themeUrl of Comments component is https://${cfg.baseUrl}/static/giscus and I set my baseUrl in quartz.config.ts to freewill.dev so Giscus tried to load up my custom theme .css files from https://freewill.dev/static/giscus/*.css which don’t exist.

So, after deploying my updated site to my host, Giscus Comments look great with custom theme locally now 👍

Step 5 — Deploy changes

I still do manual deploy 😅 as I described in How I publish freewill.dev with Quartz + Obsidian

Wrap-Up

Now that comments are live, my garden feels less like a quiet collection of notes and more like a space where conversations can grow. Each seed I publish can spark new ideas, questions, or perspectives — and that’s the real value of sharing in public.

🌱 Freedom isn’t just about publishing — it’s about creating space for others to speak 💬 too.

─── ✧ ✦ ✧ ───

Graph View

Backlinks