Blog on 0AndWild_log

Adding Comments to Hugo Blog with Giscus

Fri, 17 Oct 2025 12:00:00 +0900

What is Giscus?

Giscus is an open-source comment system that uses GitHub Discussions as its backend.

Key Features

✅ Completely Free (leverages GitHub features)
✅ No Server Required (GitHub handles everything)
✅ Full Markdown Support (code blocks, images, tables, etc.)
✅ Reactions (👍, ❤️, 😄, etc.)
✅ GitHub Notifications (get notified when comments are posted)
✅ Dark Mode (auto-syncs with blog theme)
✅ Data Ownership (stored in your repository)

Differences from Utterances

Feature	Giscus	Utterances
Backend	GitHub Discussions	GitHub Issues
Reactions	✅	❌
Nested Replies	✅ (nested)	⚠️ (flat)
Comment Sorting	✅	⚠️
Best For	Comments	Issue tracking

Conclusion: Giscus is the superior choice over Utterances.

Prerequisites

Requirements

GitHub account
Public GitHub repository (your blog repository)
Hugo + Blowfish theme

Limitations

⚠️ Public repositories only (Private repositories have limited Discussions functionality)
⚠️ GitHub account required (no anonymous comments)

Step 1: Enable GitHub Discussions

1.1 Navigate to Repository Settings

Go to your blog repository on GitHub

Example: https://github.com/0AndWild/0AndWild.github.io

Click the Settings tab

1.2 Enable Discussions

Scroll down to find the Features section
Check the Discussions checkbox ✅
It will save automatically

1.3 Verify

Confirm that the Discussions tab appears at the top of your repository

Code | Issues | Pull requests | Discussions | ← Newly created!

Step 2: Install Giscus App

2.1 Install Giscus GitHub App

Visit https://github.com/apps/giscus
Click the Install button
Choose permission scope:
- All repositories (all repositories)
- Only select repositories (specific repositories - recommended)
Select your blog repository:
```
0AndWild/0AndWild.github.io
```
Click Install

2.2 Verify Permissions

Giscus requests the following permissions:

✅ Read access to discussions (read discussions)
✅ Write access to discussions (write discussions)
✅ Read access to metadata (read metadata)

Step 3: Generate Giscus Configuration

3.1 Visit Giscus Website

Go to https://giscus.app

3.2 Connect Repository

Enter in the Repository section:

0AndWild/0AndWild.github.io

You should see a success message below:

✅ Success! This repository meets all criteria.

If you see an error:

Verify Discussions is enabled
Verify Giscus App is installed
Verify the repository is Public

3.3 Page ↔️ Discussion Mapping

Choose in the Discussion Mapping section:

Recommended: `pathname` (path name)

Mapping: Select pathname

Each blog post’s path becomes the Discussion title.

Example:

Post: /posts/giscus-guide/
Discussion title: posts/giscus-guide

Alternatives:

URL: Uses full URL (problematic if domain changes)
title: Uses post title (problematic if title changes)
og:title: OpenGraph title
specific term: Manually specified

Recommendation: Use pathname

3.4 Select Discussion Category

Choose from the Discussion Category dropdown:

Recommended: `Announcements`

Category: Select Announcements

Characteristics:

Only admins can create new Discussions
Anyone can comment
Ideal for blog posts

Alternative: `General`

Anyone can create Discussions
More open

Recommendation: Announcements (best for blogs)

3.5 Feature Selection

Enable Reactions

✅ Enable reactions

Users can react with 👍, ❤️, 😄, etc.

Emit Metadata

□ Emit metadata (recommended to leave unchecked)

Unnecessary feature, better to keep it off

Comment Input Position

⚪ Above comments
⚪ Below comments (recommended)

Recommendation: Below comments

Encourages users to read existing comments first

Lazy Loading

✅ Lazy loading

Improves page load speed (recommended)

3.6 Theme Selection

Recommended: `preferred_color_scheme`

Theme: preferred_color_scheme

Behavior:

Automatically switches based on user’s system settings
Dark mode ↔️ Light mode automatic

Alternatives:

light: Always light theme
dark: Always dark theme
transparent_dark: Transparent dark
Other GitHub themes

Recommendation: preferred_color_scheme (auto-switching)

3.7 Language Setting

Language: en (English)

Step 4: Copy Generated Code

4.1 Copy Script

Copy the generated code from the Enable giscus section at the bottom of the page:

<script src="https://giscus.app/client.js"
 data-repo="0AndWild/0AndWild.github.io"
 data-repo-id="R_kgDOxxxxxxxx"
 data-category="Announcements"
 data-category-id="DIC_kwDOxxxxxxxx"
 data-mapping="pathname"
 data-strict="0"
 data-reactions-enabled="1"
 data-emit-metadata="0"
 data-input-position="bottom"
 data-theme="preferred_color_scheme"
 data-lang="en"
 data-loading="lazy"
 crossorigin="anonymous"
 async>
</script>

4.2 Important Values

data-repo-id: Repository unique ID (auto-generated)
data-category-id: Category unique ID (auto-generated)

These values are unique to your repository, so you must use the code generated from the Giscus website.

Step 5: Integrate with Blowfish Theme

5.1 Create Directory

From the terminal, navigate to your blog’s root directory:

mkdir -p layouts/partials

5.2 Create comments.html File

touch layouts/partials/comments.html

Or create directly in your IDE/editor:

layouts/
 └── partials/
 └── comments.html ← Create new

5.3 Insert Giscus Code

Add the following content to layouts/partials/comments.html:

<!-- Giscus Comment System -->
<script src="https://giscus.app/client.js"
 data-repo="0AndWild/0AndWild.github.io"
 data-repo-id="R_kgDOxxxxxxxx"
 data-category="Announcements"
 data-category-id="DIC_kwDOxxxxxxxx"
 data-mapping="pathname"
 data-strict="0"
 data-reactions-enabled="1"
 data-emit-metadata="0"
 data-input-position="bottom"
 data-theme="preferred_color_scheme"
 data-lang="en"
 data-loading="lazy"
 crossorigin="anonymous"
 async>
</script>

⚠️ Important: Replace the data-repo-id and data-category-id values with your own values!

5.4 Configure params.toml

Open config/_default/params.toml and add to the [article] section:

[article]
 showComments = true # Add or verify this line
 # ... other settings

If the showComments entry already exists, make sure it’s set to true.

Step 6: Local Testing

6.1 Run Hugo Server

hugo server -D

6.2 Verify in Browser

http://localhost:1313

The Giscus comment widget should appear at the bottom of post pages.

6.3 Write Test Comment

Click Sign in with GitHub button
Authorize GitHub OAuth
Write a test comment
Verify the comment displays

6.4 Check GitHub Discussions

GitHub repository → Discussions tab
Verify a new Discussion was created in the Announcements category
Verify the Discussion title matches the post path

Step 7: Deploy

7.1 Commit to Git

git add layouts/partials/comments.html
git add config/_default/params.toml
git commit -m "Add Giscus comments system"

7.2 Push to GitHub

git push origin main

7.3 Check GitHub Actions

GitHub Actions will automatically build and deploy.

Check deployment status:

GitHub repository → Actions tab

7.4 Verify Deployed Site

https://0andwild.github.io

Verify the comment widget displays correctly on post pages.

Advanced Configuration

Dynamic Dark Mode and Language Setting (Recommended)

A complete solution to make Giscus automatically adapt to Blowfish theme’s dark mode toggle and language switching.

Complete Dynamic Configuration

Full code for layouts/partials/comments.html:

<!-- Giscus Comments with Dynamic Theme and Language -->
{{ $lang := .Site.Language.Lang }}
{{ $translationKey := .File.TranslationBaseName }}
<script>
 (function() {
 // Get current theme (dark/light)
 function getGiscusTheme() {
 const isDark = document.documentElement.classList.contains('dark');
 return isDark ? 'dark_tritanopia' : 'light_tritanopia';
 }

 // Get language from Hugo template
 const currentLang = '{{ $lang }}';

 // Use file directory path for unified comments across languages
 // Example: "posts/subscription_alert" for both index.ko.md and index.en.md
 const discussionId = '{{ .File.Dir | replaceRE "^content/" "" | replaceRE "/$" "" }}';

 // Wait for DOM to be ready
 if (document.readyState === 'loading') {
 document.addEventListener('DOMContentLoaded', initGiscus);
 } else {
 initGiscus();
 }

 function initGiscus() {
 // Create and insert Giscus script with dynamic settings
 const script = document.createElement('script');
 script.src = 'https://giscus.app/client.js';
 script.setAttribute('data-repo', '0AndWild/0AndWild.github.io');
 script.setAttribute('data-repo-id', 'R_kgDOQAqZFA');
 script.setAttribute('data-category', 'General');
 script.setAttribute('data-category-id', 'DIC_kwDOQAqZFM4CwwRg');
 script.setAttribute('data-mapping', 'specific');
 script.setAttribute('data-term', discussionId);
 script.setAttribute('data-strict', '0');
 script.setAttribute('data-reactions-enabled', '1');
 script.setAttribute('data-emit-metadata', '0');
 script.setAttribute('data-input-position', 'bottom');
 script.setAttribute('data-theme', getGiscusTheme());
 script.setAttribute('data-lang', currentLang);
 script.setAttribute('data-loading', 'lazy');
 script.setAttribute('crossorigin', 'anonymous');
 script.async = true;

 // Find giscus container or create one
 const container = document.querySelector('.giscus-container') || document.currentScript?.parentElement;
 if (container) {
 container.appendChild(script);
 }
 }

 // Monitor theme changes and update Giscus
 function updateGiscusTheme() {
 const iframe = document.querySelector('iframe.giscus-frame');
 if (!iframe) return;

 const theme = getGiscusTheme();

 try {
 iframe.contentWindow.postMessage(
 {
 giscus: {
 setConfig: {
 theme: theme
 }
 }
 },
 'https://giscus.app'
 );
 } catch (error) {
 console.log('Giscus theme update delayed, will retry...');
 }
 }

 // Watch for theme changes using MutationObserver
 const observer = new MutationObserver((mutations) => {
 mutations.forEach((mutation) => {
 if (mutation.attributeName === 'class') {
 // Delay update to ensure iframe is ready
 setTimeout(updateGiscusTheme, 100);
 }
 });
 });

 // Start observing after a short delay
 setTimeout(() => {
 observer.observe(document.documentElement, {
 attributes: true,
 attributeFilter: ['class']
 });
 }, 500);

 // Update theme when Giscus iframe loads
 window.addEventListener('message', (event) => {
 if (event.origin !== 'https://giscus.app') return;
 if (event.data.giscus) {
 // Giscus is ready, update theme
 setTimeout(updateGiscusTheme, 200);
 }
 });
 })();
</script>

<style>
 /* Ensure Giscus iframe has proper height and displays all content */
 .giscus-container {
 min-height: 300px;
 }

 .giscus-container iframe.giscus-frame {
 width: 100%;
 border: none;
 min-height: 300px;
 }

 /* Make sure comment actions are visible */
 .giscus {
 overflow: visible !important;
 }
</style>

<div class="giscus-container"></div>

How It Works

1. Dynamic Language Setting

{{ $lang := .Site.Language.Lang }}
const currentLang = '{{ $lang }}';

Gets current page language from Hugo template
Korean page: ko, English page: en
Sets Giscus to the corresponding language

Result:

Korean page → Giscus UI displays in Korean
English page → Giscus UI displays in English
Language switch triggers page reload with automatic update

2. Dynamic Dark Mode Setting

function getGiscusTheme() {
 const isDark = document.documentElement.classList.contains('dark');
 return isDark ? 'dark_tritanopia' : 'light_tritanopia';
}

Blowfish theme adds <html class="dark"> in dark mode
Detects this to determine theme
Uses dark_tritanopia / light_tritanopia themes (colorblind-friendly)

Result:

Page load: Loads Giscus with current theme state
Dark mode toggle click: Real-time Giscus theme change

3. Unified Comments Across Languages

const discussionId = '{{ .File.Dir | replaceRE "^content/" "" | replaceRE "/$" "" }}';

Uses file directory path as Discussion ID
content/posts/subscription_alert/index.ko.md → posts/subscription_alert
content/posts/subscription_alert/index.en.md → posts/subscription_alert
Same ID means Korean/English versions share the same comments

Result:

Comments written on Korean post
Also display on English post
Separate Discussions created per post

4. Real-time Theme Change Detection

const observer = new MutationObserver((mutations) => {
 mutations.forEach((mutation) => {
 if (mutation.attributeName === 'class') {
 setTimeout(updateGiscusTheme, 100);
 }
 });
});

MutationObserver detects HTML class changes
Immediately detects dark mode toggle clicks
Sends theme change command to Giscus iframe via postMessage

Testing Method

# 1. Run local server
hugo server -D

# 2. Verify in browser
http://localhost:1313/posts/subscription_alert/

Test Items:

✅ Page load displays Giscus with current theme (light/dark)
✅ Dark mode toggle click immediately changes Giscus theme
✅ Language switch (ko → en) changes Giscus language
✅ Korean/English pages display same comments

Changing Theme Options

To use different themes, modify the getGiscusTheme() function:

// Basic theme
function getGiscusTheme() {
 const isDark = document.documentElement.classList.contains('dark');
 return isDark ? 'dark' : 'light';
}

// High contrast theme
function getGiscusTheme() {
 const isDark = document.documentElement.classList.contains('dark');
 return isDark ? 'dark_high_contrast' : 'light_high_contrast';
}

// GitHub style theme
function getGiscusTheme() {
 const isDark = document.documentElement.classList.contains('dark');
 return isDark ? 'dark_dimmed' : 'light';
}

Available themes:

light / dark
light_high_contrast / dark_high_contrast
light_tritanopia / dark_tritanopia (colorblind-friendly)
dark_dimmed
transparent_dark
preferred_color_scheme (follows system settings)

Static Theme Configuration (Simple Method)

If dynamic changes aren’t needed, you can configure statically:

<script src="https://giscus.app/client.js"
 data-repo="0AndWild/0AndWild.github.io"
 data-repo-id="R_kgDOxxxxxxxx"
 data-category="General"
 data-category-id="DIC_kwDOxxxxxxxx"
 data-mapping="pathname"
 data-theme="preferred_color_scheme"
 data-lang="en"
 crossorigin="anonymous"
 async>
</script>

Pros: Simple Cons: No real-time theme changes, comments separated by language

Hide Comments on Specific Posts

To hide comments on specific posts only, add to that post’s front matter:

---
title: "Post Without Comments"
showComments: false # Hide comments on this post only
---

Separate Comments by Category

To use different Discussion categories for posts in different categories:

<!-- Conditional category configuration -->
<script>
 const category = {{ if in .Params.categories "Tutorial" }}
 "DIC_kwDOxxxxTutorial"
 {{ else }}
 "DIC_kwDOxxxxGeneral"
 {{ end }};
</script>

<script src="https://giscus.app/client.js"
 ...
 data-category-id="{{ category }}"
 ...>
</script>

Troubleshooting

Cause 1: Discussions Not Enabled

Solution: GitHub repository → Settings → Check Discussions

Cause 2: Giscus App Not Installed

Solution: Install at https://github.com/apps/giscus

Cause 3: Repository ID Error

Solution: Regenerate code at giscus.app

Cause 4: showComments Setting Missing

# config/_default/params.toml
[article]
 showComments = true # Verify

Cause: GitHub OAuth Authorization Needed

1. Click "Sign in with GitHub"
2. Authorize OAuth permissions
3. Redirect to repository
4. Can write comments

Comments Not Saving

Cause: Repository Permission Issue

Check:
1. Is the repository Public?
2. Is the repository included in Giscus App permissions?
3. Does the Discussion category exist?

Dark Mode Not Syncing

Solution: Add JavaScript Sync Code

Refer to “Advanced Configuration > Automatic Dark Mode Switching” above

Managing Giscus

Comment Management

Manage via GitHub Discussions

1. GitHub repository → Discussions tab
2. Click the relevant Discussion
3. Management actions:
 - Edit comment (own comments only)
 - Delete comment (admin)
 - Block user (admin)
 - Lock Discussion (admin)

Handling Spam Comments

1. Find spam comment in GitHub Discussions
2. ... menu next to comment → "Delete"
3. Block user: Profile → Block user

Notification Settings

Receive Comment Notifications via GitHub

1. GitHub → Settings → Notifications
2. Add repository to Watching
3. Configure email notifications

Receive Notifications for Specific Discussions Only

1. Discussions tab → Relevant Discussion
2. "Subscribe" button on right
3. Select "Notify me"

Statistics and Analytics

View Comment Statistics

In GitHub Discussions:

1. Discussions tab
2. Check number of Discussions by category
3. Check comment count for each Discussion

Utilize GitHub Insights

GitHub repository → Insights → Community
→ Check Discussions activity

Cost and Limitations

Cost

Completely Free

Only need a GitHub account
Unlimited comments within repository size limits

Limitations

GitHub API Rate Limit

60 requests/hour (unauthenticated)
5,000 requests/hour (authenticated)
Giscus is optimized with caching, so no issues

Repository Size

GitHub Free: 1GB per repository
Text comments alone won’t reach the limit

Discussions Limit

None (unlimited)

Alternative Comparisons

Giscus vs Utterances

Item	Giscus	Utterances
Backend	Discussions	Issues
Reactions	✅	❌
Nested Replies	Nested support	Flat
Recommendation	⭐⭐⭐⭐⭐	⭐⭐⭐

Conclusion: Giscus is recommended

Giscus vs Disqus

Item	Giscus	Disqus
Cost	Free	Free (with ads)
Ads	❌	✅
Anonymous Comments	❌	✅ (Guest)
Markdown	✅	⚠️
Data Ownership	✅	❌
Recommendation	Developer blogs	General blogs

Migration Guide

Utterances → Giscus

1. Convert GitHub Issues to Discussions
 - Manual work required (no automation)
 - Or leave Issues as-is and start fresh with Giscus

2. Replace comments.html file
 - Delete Utterances code
 - Add Giscus code

3. Deploy

Disqus → Giscus

1. Export Disqus data (XML)
2. Manual migration to GitHub Discussions
 - No automation tools available
 - Need to write custom script
 - Or starting fresh recommended

Additional Resources

Official Documentation

Community

Checklist

Installation completion checklist:

GitHub Discussions enabled
Giscus App installed
Created layouts/partials/comments.html
Inserted Giscus code (with your own IDs)
Set showComments = true in params.toml
Local testing complete
Pushed to GitHub
Verified on deployed site
Wrote test comment
Verified creation in GitHub Discussions

Conclusion

Giscus is the most suitable comment system for Hugo/GitHub Pages blogs:

Summary of Advantages

✅ Completely free ✅ Simple setup (10 minutes) ✅ No server required ✅ Full Markdown support ✅ GitHub integration ✅ Data ownership

Disadvantages

❌ GitHub account required (no anonymous comments) ❌ Best for technical blogs (barrier for general users)

Recommended For

✅ Developer blogs
✅ Technical documentation
✅ Open source projects

Complete Guide to Comment Systems for Static Blogs

Fri, 17 Oct 2025 11:00:00 +0900

Overview

This guide provides a comprehensive comparison of all methods to add comment functionality to blogs built with static site generators (Hugo). We present solutions for various requirements including anonymous comments, GitHub login, and social logins.

Comment System Classification

By Authentication Method

Authentication	Systems
GitHub Only	Giscus, Utterances
Anonymous Supported	Remark42, Commento, Comentario, HashOver
Anonymous + Social Login	Remark42, Commento, Disqus
Social Login Only	Disqus, Hyvor Talk

By Hosting Method

Hosting	Systems
SaaS (No Management)	Giscus, Utterances, Disqus, Hyvor Talk
Self-Hosted	Remark42, Commento, Comentario, HashOver
Hybrid	Cusdis (Free Vercel deployment)

1. Giscus (Highly Recommended - For GitHub Users)

Concept

Comment system using GitHub Discussions as backend

How It Works

1. User visits blog
 ↓
2. Giscus widget loads
 ↓
3. Login with GitHub OAuth
 ↓
4. Write comment
 ↓
5. Auto-saved to GitHub Discussions
 ↓
6. Displayed on blog in real-time

Advantages

✅ Completely free (leverages GitHub features)
✅ No server required (GitHub handles backend)
✅ Data ownership (stored in your repository)
✅ Markdown support (code blocks, images, etc.)
✅ Reactions support (👍, ❤️, etc.)
✅ Notifications (comment alerts via GitHub notifications)
✅ Dark mode (syncs with blog theme)
✅ Spam prevention (requires GitHub account)
✅ Easy management (manage in GitHub Discussions)
✅ Searchable (search comments via GitHub search)

Disadvantages

❌ No anonymous comments (GitHub account required)
❌ Best for tech blogs (general users may not have GitHub accounts)
❌ GitHub dependency (comments unavailable during GitHub outages)

Implementation Difficulty

⭐⭐ (2/5)

Setup Method

Step 1: Enable GitHub Discussions

1. GitHub Repository → Settings
2. Features section → Check Discussions

Step 2: Configure Giscus

Visit giscus.app
Enter repository: username/repository
Select settings:
- Page ↔️ Discussion mapping: pathname (recommended)
- Discussion category: Announcements or General
- Features: Reactions, comments above
- Theme: Match your blog theme

Step 3: Add to Blowfish

<!-- layouts/partials/comments.html -->
<script src="https://giscus.app/client.js"
 data-repo="0AndWild/0AndWild.github.io"
 data-repo-id="YOUR_REPO_ID"
 data-category="Announcements"
 data-category-id="YOUR_CATEGORY_ID"
 data-mapping="pathname"
 data-strict="0"
 data-reactions-enabled="1"
 data-emit-metadata="0"
 data-input-position="bottom"
 data-theme="preferred_color_scheme"
 data-lang="en"
 crossorigin="anonymous"
 async>
</script>

Step 4: Configure params.toml

[article]
 showComments = true

Theme Synchronization (Dark Mode)

<script>
 // Change Giscus theme when blog theme changes
 const giscusTheme = document.querySelector('iframe.giscus-frame');
 if (giscusTheme) {
 const theme = document.documentElement.getAttribute('data-theme');
 giscusTheme.contentWindow.postMessage({
 giscus: {
 setConfig: {
 theme: theme === 'dark' ? 'dark' : 'light'
 }
 }
 }, 'https://giscus.app');
 }
</script>

Cost

Completely free

Recommended For

✅ Developer blogs
✅ Technical documentation
✅ Open source project blogs

2. Utterances

Concept

Comment system using GitHub Issues as backend (predecessor of Giscus)

How It Works

1. GitHub OAuth login
 ↓
2. Write comment
 ↓
3. Save to GitHub Issues (each post = 1 Issue)
 ↓
4. Display on blog

Advantages

✅ Completely free
✅ Lightweight (TypeScript)
✅ Simple setup
✅ Markdown support

Disadvantages

❌ Uses Issues (less suitable than Discussions)
❌ Fewer features than Giscus
❌ No anonymous comments

Giscus vs Utterances

Feature	Giscus	Utterances
Backend	Discussions	Issues
Reactions	✅	❌
Nested Replies	✅ (nested)	⚠️ (flat)
Suitability	Comment-specific	Issue tracking

Conclusion: Giscus is a superior alternative to Utterances

Implementation Difficulty

⭐⭐ (2/5)

Setup Method

<!-- layouts/partials/comments.html -->
<script src="https://utteranc.es/client.js"
 repo="username/repository"
 issue-term="pathname"
 theme="github-light"
 crossorigin="anonymous"
 async>
</script>

Recommended For

Unless there’s a specific reason, use Giscus instead

Concept

Open-source self-hosted comment system supporting anonymous and various social logins

How It Works

1. Deploy Remark42 server (Docker)
 ↓
2. Insert Remark42 script on blog
 ↓
3. User chooses:
 - Write anonymous comment
 - Login with GitHub/Google/Twitter and write
 ↓
4. Save to Remark42 DB
 ↓
5. Display on blog

Advantages

✅ Anonymous comments supported (can be toggled on/off)
✅ Various social logins (GitHub, Google, Facebook, Twitter, Email)
✅ Completely free (open source)
✅ No ads
✅ Data ownership (your server)
✅ Markdown support
✅ Comment edit/delete
✅ Admin mode (approve/block/delete comments)
✅ Notifications (Email/Telegram)
✅ Import/Export (migrate from other systems)
✅ Voting (upvote/downvote)
✅ Spam filter

Disadvantages

❌ Self-hosting required (Docker server)
❌ Maintenance responsibility
❌ Hosting costs ($5/month~, free tier possible)

Implementation Difficulty

⭐⭐⭐⭐ (4/5)

Hosting Options

Option 1: Railway (Recommended)

1. Sign up for Railway.app
2. "New Project" → "Deploy from GitHub"
3. Select Remark42 Docker image
4. Configure environment variables:
 - REMARK_URL=https://your-remark42.railway.app
 - SECRET=your-random-secret
 - AUTH_ANON=true # Allow anonymous comments
 - AUTH_GITHUB_CID=your_client_id
 - AUTH_GITHUB_CSEC=your_client_secret

Railway Free Tier:

$5 credit per month
Sufficient for small blogs

Option 2: Fly.io

# fly.toml
app = "my-remark42"

[build]
 image = "umputun/remark42:latest"

[env]
 REMARK_URL = "https://my-remark42.fly.dev"
 AUTH_ANON = "true"
 AUTH_GITHUB_CID = "xxx"
 AUTH_GITHUB_CSEC = "xxx"

fly launch
fly deploy

Fly.io Free Tier:

3 apps
Sufficient for small blogs

Option 3: Docker Compose (VPS)

# docker-compose.yml
version: '3.8'

services:
 remark42:
 image: umputun/remark42:latest
 restart: always
 environment:
 - REMARK_URL=https://remark.your-blog.com
 - SECRET=your-secret-key-change-this
 - AUTH_ANON=true  # Allow anonymous
 - AUTH_GITHUB_CID=xxx  # GitHub login
 - AUTH_GITHUB_CSEC=xxx
 - AUTH_GOOGLE_CID=xxx  # Google login
 - AUTH_GOOGLE_CSEC=xxx
 - ADMIN_SHARED_ID=github_username  # Admin
 volumes:
 - ./data:/srv/var
 ports:
 - "8080:8080"

docker-compose up -d

Blog Embed Code

<!-- layouts/partials/comments.html -->
<div id="remark42"></div>
<script>
 var remark_config = {
 host: 'https://your-remark42.railway.app',
 site_id: '0andwild-blog',
 components: ['embed'],
 theme: 'light',
 locale: 'en',
 max_shown_comments: 10,
 simple_view: false,
 no_footer: false
 };

 (function(c) {
 for(var i = 0; i < c.length; i++){
 var d = document, s = d.createElement('script');
 s.src = remark_config.host + '/web/' +c[i] +'.js';
 s.defer = true;
 (d.head || d.body).appendChild(s);
 }
 })(remark_config.components || ['embed']);
</script>

Anonymous + GitHub Simultaneous Configuration

# Environment variables
AUTH_ANON=true # Allow anonymous
AUTH_GITHUB_CID=xxx # GitHub OAuth App ID
AUTH_GITHUB_CSEC=xxx # GitHub OAuth App Secret
ANON_VOTE=false # Disable voting for anonymous (spam prevention)

Users can choose:

“Comment anonymously”
“Login with GitHub”

Admin Features

# Designate admin
ADMIN_SHARED_ID=github_yourusername

# Or by email
ADMIN_SHARED_EMAIL=you@example.com

Admin capabilities:

Delete comments
Block users
Pin comments
Read-only mode

Cost

Railway: Free or $5/month
Fly.io: Free tier available
VPS (DigitalOcean, etc.): $5/month~

Recommended For

✅ Want both anonymous and social login
✅ Users comfortable with Docker
✅ Want complete data control

4. Commento / Comentario

Concept

Privacy-focused lightweight comment system

Commento vs Comentario

Item	Commento	Comentario
Status	Development stopped	Actively developed (Commento fork)
License	MIT	MIT
Language	Go	Go
Recommend	❌	✅

Conclusion: Comentario recommended

Comentario Advantages

✅ Anonymous comments supported
✅ Social logins (GitHub, Google, GitLab, SSO)
✅ Lightweight (Go-based)
✅ Privacy-focused
✅ Markdown support
✅ Voting feature

Disadvantages

❌ Self-hosting required
❌ Fewer features than Remark42

Implementation Difficulty

⭐⭐⭐⭐ (4/5)

Docker Deployment

version: '3.8'

services:
 comentario:
 image: registry.gitlab.com/comentario/comentario
 ports:
 - "8080:8080"
 environment:
 - COMENTARIO_ORIGIN=https://comments.your-blog.com
 - COMENTARIO_BIND=0.0.0.0:8080
 - COMENTARIO_POSTGRES=postgres://user:pass@db/comentario
 depends_on:
 - db

 db:
 image: postgres:15
 environment:
 - POSTGRES_DB=comentario
 - POSTGRES_USER=comentario
 - POSTGRES_PASSWORD=change-this
 volumes:
 - postgres_data:/var/lib/postgresql/data

volumes:
 postgres_data:

Blog Embed

<script defer src="https://comments.your-blog.com/js/commento.js"></script>
<div id="commento"></div>

Recommended For

Alternative to Remark42
Want simpler system

5. Disqus (Traditional SaaS)

Concept

Oldest and most widely used cloud comment system

How It Works

1. Create Disqus account and register site
 ↓
2. Insert Disqus script on blog
 ↓
3. User chooses:
 - Guest (anonymous - requires email)
 - Disqus account
 - Facebook/Twitter/Google login
 ↓
4. Save to Disqus server
 ↓
5. Display on blog

Advantages

✅ Extremely simple setup (5 minutes)
✅ No server required (SaaS)
✅ Guest mode (comment with just email)
✅ Social logins (Facebook, Twitter, Google)
✅ Powerful admin tools
✅ Spam filter (Akismet integration)
✅ Mobile apps (iOS/Android)
✅ Analytics/Statistics

Disadvantages

❌ Shows ads (free plan)
❌ Heavy (script size)
❌ Privacy concerns (data tracking)
❌ No data ownership (Disqus servers)
❌ No GitHub login
❌ Ad removal cost ($11.99/month~)

Implementation Difficulty

⭐ (1/5) - Easiest

Setup Method

Step 1: Register Disqus Site

1. Sign up at disqus.com
2. Select "I want to install Disqus on my site"
3. Enter Website Name (e.g., andwild-blog)
4. Select Category
5. Select Plan (Basic - Free)

Step 2: Configure Blowfish

# config/_default/config.toml
[services.disqus]
 shortname = "andwild-blog" # Name created in Step 1

# config/_default/params.toml
[article]
 showComments = true

Hugo has built-in Disqus support, so comments display automatically!

Step 3: Allow Guest Comments

Disqus Dashboard → Settings → Community
→ Guest Commenting: Allow guests to comment (check)

Ad Removal Methods

Method 1: Paid Plan ($11.99/month~)

Plus Plan: No ads
Pro Plan: No ads + advanced features

Method 2: Hide with CSS (Not recommended - may violate terms)

/* Not recommended: May violate Disqus terms */
#disqus_thread iframe[src*="ads"] {
 display: none !important;
}

Cost

Free: With ads
Plus: $11.99/month (no ads)
Pro: $89/month (advanced features)

Recommended For

✅ Want to add comments quickly
✅ Non-technical bloggers
✅ Don’t mind ads
❌ Not recommended for privacy-conscious users

6. Cusdis (Free Vercel Deployment)

Concept

Lightweight open-source comment system, deployable to Vercel for free

How It Works

1. Deploy Cusdis to Vercel (1-Click)
 ↓
2. Connect PostgreSQL (Vercel free)
 ↓
3. Add site in dashboard
 ↓
4. Insert script on blog
 ↓
5. Users comment with email + name

Advantages

✅ Completely free (Vercel free tier)
✅ Anonymous comments (just email + name)
✅ Lightweight (50KB)
✅ Simple setup (Vercel 1-Click deploy)
✅ Privacy-focused
✅ Open source

Disadvantages

❌ No Markdown support
❌ No social login
❌ Simple features

Implementation Difficulty

⭐⭐⭐ (3/5)

Setup Method

Step 1: Deploy to Vercel

1. Visit https://cusdis.com/
2. Click "Deploy with Vercel"
3. Connect GitHub
4. Add PostgreSQL (Vercel Storage)
5. Deployment complete

Step 2: Add Site

1. Access deployed Cusdis dashboard
2. Click "Add Website"
3. Enter Domain: 0andwild.github.io
4. Copy App ID

Step 3: Blog Embed

<!-- layouts/partials/comments.html -->
<div id="cusdis_thread"
 data-host="https://your-cusdis.vercel.app"
 data-app-id="YOUR_APP_ID"
 data-page-id="{{ .File.UniqueID }}"
 data-page-url="{{ .Permalink }}"
 data-page-title="{{ .Title }}">
</div>
<script async defer src="https://your-cusdis.vercel.app/js/cusdis.es.js"></script>

Cost

Completely free (Vercel free tier)

Recommended For

✅ Need only simple anonymous comments
✅ Want completely free solution
✅ Have Vercel experience

7. HashOver

Concept

PHP-based fully anonymous comment system

Advantages

✅ Fully anonymous (no information needed)
✅ PHP + flat file (no DB required)
✅ Open source

Disadvantages

❌ Requires PHP (unsuitable for static sites)
❌ No GitHub login
❌ Old project

Implementation Difficulty

⭐⭐⭐⭐ (4/5)

Recommended For

❌ Not recommended for static blogs
Consider only if you have a PHP server

8. Hyvor Talk (Premium SaaS)

Concept

Ad-free premium comment system

Advantages

✅ No ads
✅ Anonymous comments supported
✅ Social logins
✅ Powerful spam filter

Disadvantages

❌ Paid ($5/month~)
❌ No GitHub login

Cost

Starter: $5/month (1 site)
Pro: $15/month (3 sites)

Recommended For

Paid alternative to Disqus
Want ad-free SaaS

Comparison Tables

By Authentication Method

System	Anonymous	GitHub	Google	Other Social	Difficulty	Cost
Giscus	❌	✅	❌	❌	⭐⭐	Free
Utterances	❌	✅	❌	❌	⭐⭐	Free
Remark42	✅	✅	✅	✅	⭐⭐⭐⭐	$5/mo
Comentario	✅	✅	✅	✅	⭐⭐⭐⭐	$5/mo
Disqus	⚠️	❌	✅	✅	⭐	Free (ads)
Cusdis	✅	❌	❌	❌	⭐⭐⭐	Free
Hyvor Talk	✅	❌	✅	✅	⭐	$5/mo

By Features

System	Markdown	Reactions	Voting	Notifications	Admin	Spam Filter
Giscus	✅	✅	❌	✅	⚠️	✅
Remark42	✅	❌	✅	✅	✅	✅
Disqus	⚠️	❌	✅	✅	✅	✅
Cusdis	❌	❌	❌	⚠️	✅	⚠️

By Hosting

System	Hosting	Data Location	Dependency
Giscus	GitHub	GitHub Discussions	GitHub
Remark42	Self	Your server	Docker
Disqus	Disqus	Disqus servers	Disqus
Cusdis	Vercel	Vercel DB	Vercel

Selection Guide

Scenario-Based Recommendations

1. “Developer blog, targeting GitHub users”

→ Giscus ⭐⭐⭐⭐⭐

Free, simple, Markdown support
GitHub integration makes notifications convenient

2. “General blog, anonymous comments essential”

→ Cusdis (simple) or Remark42 (advanced)

Cusdis: 5-minute setup, completely free
Remark42: More features, includes social login

→ Remark42 ⭐⭐⭐⭐⭐

Only option supporting both
Powerful admin features

4. “No technical skills, quick setup”

→ Disqus

5-minute setup
Accept ads

5. “Completely free + don’t want server management”

→ Giscus (GitHub) or Cusdis (anonymous)

6. “Privacy is top priority”

→ Remark42 or Comentario (self-hosted)

Complete data control

Practical Implementation: Blowfish + Giscus

Complete Setup Process

1. Enable GitHub Discussions

GitHub Repository → Settings → Features → Check Discussions

2. Install Giscus App

Visit https://github.com/apps/giscus → Install
→ Select repository

3. Generate Giscus Configuration

At giscus.app:

Repository: 0AndWild/0AndWild.github.io
Mapping: pathname
Category: Announcements
Theme: preferred_color_scheme
Language: en

Copy generated code

4. Create File

# Create directory (if not exists)
mkdir -p layouts/partials

# Create file
touch layouts/partials/comments.html

5. Insert Code

<!-- layouts/partials/comments.html -->
<script src="https://giscus.app/client.js"
 data-repo="0AndWild/0AndWild.github.io"
 data-repo-id="R_xxxxxxxxxxxxx"
 data-category="Announcements"
 data-category-id="DIC_xxxxxxxxxxxxx"
 data-mapping="pathname"
 data-strict="0"
 data-reactions-enabled="1"
 data-emit-metadata="0"
 data-input-position="bottom"
 data-theme="preferred_color_scheme"
 data-lang="en"
 crossorigin="anonymous"
 async>
</script>

6. Modify params.toml

[article]
 showComments = true

7. Local Testing

hugo server -D
# Check at http://localhost:1313

8. Deploy

git add .
git commit -m "Add Giscus comments"
git push

Practical Implementation: Blowfish + Remark42 (Railway)

Complete Setup Process

1. Create GitHub OAuth App

GitHub → Settings → Developer settings → OAuth Apps → New OAuth App

Application name: AndWild Blog Comments
Homepage URL: https://0andwild.github.io
Authorization callback URL: https://your-remark42.railway.app/auth/github/callback

After creation:
Copy Client ID
Generate and copy Client Secret

2. Deploy to Railway

1. Sign up for railway.app
2. "New Project" → "Deploy Docker Image"
3. Image: umputun/remark42:latest
4. Add environment variables:

REMARK_URL=https://your-project.railway.app
SECRET=randomly-generated-secret-key-change-this
SITE=0andwild-blog
AUTH_ANON=true
AUTH_GITHUB_CID=your_github_client_id
AUTH_GITHUB_CSEC=your_github_client_secret
ADMIN_SHARED_ID=github_yourusername

3. Verify Deployment

Railway automatically generates URL:
https://your-project.railway.app

Access in browser to verify Remark42 UI

4. Configure Blowfish

mkdir -p layouts/partials
touch layouts/partials/comments.html

<!-- layouts/partials/comments.html -->
<div id="remark42"></div>
<script>
 var remark_config = {
 host: 'https://your-project.railway.app',
 site_id: '0andwild-blog',
 components: ['embed'],
 theme: 'light',
 locale: 'en'
 };

 (function(c) {
 for(var i = 0; i < c.length; i++){
 var d = document, s = d.createElement('script');
 s.src = remark_config.host + '/web/' +c[i] +'.js';
 s.defer = true;
 (d.head || d.body).appendChild(s);
 }
 })(remark_config.components || ['embed']);
</script>

5. params.toml

[article]
 showComments = true

6. Test and Deploy

hugo server -D
# After verification
git add .
git commit -m "Add Remark42 comments"
git push

Migration Guide

Disqus → Giscus

1. Export data from Disqus (XML)
2. Manual migration to GitHub Discussions
 (No automation script, manual work required)

Disqus → Remark42

1. Disqus XML Export
2. Remark42 Admin → Import → Select Disqus
3. Upload XML file

Conclusion

Final Recommendations

Situation	Recommended System	Reason
Developer blog	Giscus	Free, GitHub integration, Markdown
General blog (anonymous needed)	Cusdis	Free, simple, anonymous
Both anonymous + social	Remark42	Flexible, all features
Quick setup	Disqus	5-minute completion (accept ads)
Complete control	Remark42	Self-hosted, customizable

Personal Recommendation (0AndWild Blog)

Giscus recommended

Perfect fit for GitHub Pages blog
Tech blog’s main audience is GitHub users
Free, simple, no maintenance

Alternative: Remark42 (when anonymous comments desired)

Quick Start

Start with Giscus (10 minutes)
Collect user feedback
Consider switching to Remark42 if many requests for anonymous comments

Comment systems can be changed later, so strongly recommend starting with Giscus!

Complete Guide to Blog Subscription and Email Notification Systems

Fri, 17 Oct 2025 10:00:00 +0900

Overview

This guide analyzes methods to add subscription and email notification features to blogs built with static site generators (Hugo). We’ll cover everything from basic subscriptions to keyword-based selective notifications.

1. RSS Feed + Email Services

Concept

Leverage services that convert Hugo’s built-in RSS Feed into email notifications.

Method A: Blogtrottr

How It Works

1. Hugo automatically generates RSS Feed (index.xml)
 ↓
2. Users register RSS URL on Blogtrottr
 ↓
3. Blogtrottr periodically checks RSS
 ↓
4. Sends email when new posts detected

Advantages

✅ No developer work (just provide link)
✅ Completely free
✅ Works immediately
✅ No server required

Disadvantages

❌ No subscriber management
❌ No email design customization
❌ No analytics
❌ No keyword filtering
❌ Users must register on external site

Implementation Difficulty

⭐ (1/5) - Easiest

Usage Example

Add link to blog:
[Subscribe via Email](https://blogtrottr.com)
(Enter https://0andwild.github.io/index.xml on the site)

Method B: FeedBurner (Google)

How It Works

1. Register RSS Feed with FeedBurner
 ↓
2. FeedBurner proxies/manages RSS
 ↓
3. Embed subscription form on blog
 ↓
4. Users subscribe directly from blog
 ↓
5. Auto-sends email when new posts published

Advantages

✅ Basic analytics provided
✅ Subscription form provided
✅ Free
✅ RSS management features

Disadvantages

❌ Google may discontinue support (updates stopped)
❌ No keyword filtering
❌ Limited customization
❌ Outdated UI

Implementation Difficulty

⭐⭐ (2/5)

2. Mailchimp + RSS Campaign (Recommended)

Concept

Leverage professional email marketing platform to automatically convert RSS Feed to emails

How It Works

1. Create RSS Campaign in Mailchimp
 ↓
2. Register RSS URL and set check frequency (daily/weekly/monthly)
 ↓
3. Embed Mailchimp subscription form on blog
 ↓
4. Users enter email to subscribe
 ↓
5. Auto-generates email template when new post detected
 ↓
6. Sends to all subscribers

Advantages

✅ Free tier: Up to 2,000 subscribers
✅ Professional email design (drag-and-drop editor)
✅ Subscriber management (add/delete/segment)
✅ Detailed analytics (open rate, click rate, unsubscribe rate)
✅ Auto-generated subscription forms (embed code provided)
✅ Automation (only sends on new posts)
✅ Mobile optimized
✅ Spam filter avoidance (professional sending servers)

Disadvantages

❌ No keyword filtering by default (tag-based segmentation on Pro plan)
❌ Mailchimp logo shown on free tier
❌ Paid after 2,000 subscribers ($13/month+)

Implementation Difficulty

⭐⭐ (2/5)

Setup Steps

1. Create Mailchimp account
2. Create Audience
3. Campaign → Create → Email → RSS Campaign
4. Enter RSS URL: https://your-blog.com/index.xml
5. Set sending frequency (Daily/Weekly)
6. Design email template
7. Copy subscription form code
8. Insert in Hugo (layouts/partials/subscribe.html)

Blog Embed Code Example

<!-- Mailchimp subscription form -->
<div id="mc_embed_signup">
 <form action="https://your-mailchimp-url.com/subscribe" method="post">
 <input type="email" name="EMAIL" placeholder="Email address" required>
 <button type="submit">Subscribe</button>
 </form>
</div>

3. Buttondown (Developer-Friendly, Recommended)

Concept

Markdown-based newsletter platform with API for customization

How It Works

1. Connect RSS Feed to Buttondown
 ↓
2. Auto-converts RSS items to Markdown emails
 ↓
3. Subscribers can select tags/keywords
 ↓
4. Filter subscribers by specific tags via API
 ↓
5. Send only to matching subscribers

Advantages

✅ Free tier: Up to 1,000 subscribers
✅ Markdown-based (developer-friendly)
✅ Powerful API (customizable)
✅ Tag-based subscriptions (keyword filtering possible)
✅ No ads
✅ Clean UI
✅ RSS import automation
✅ Privacy-focused

Disadvantages

❌ Simple email design (Markdown only)
❌ Analytics weaker than Mailchimp
❌ Limited Korean support

Implementation Difficulty

⭐⭐⭐ (3/5) - Increases with API usage

Keyword Notification Example

Step 1: Add tag selection to subscription form

<form action="https://buttondown.email/api/emails/embed-subscribe/YOUR_ID" method="post">
 <input type="email" name="email" placeholder="Email" required>

 <label>Select topics of interest:</label>
 <input type="checkbox" name="tags" value="kubernetes"> Kubernetes
 <input type="checkbox" name="tags" value="docker"> Docker
 <input type="checkbox" name="tags" value="golang"> Go

 <button type="submit">Subscribe</button>
</form>

Step 2: Selective sending via GitHub Actions

name: Send Newsletter
on:
 push:
 paths:
 - 'content/posts/**'

jobs:
 send:
 runs-on: ubuntu-latest
 steps:
 - name: Extract tags from post
 run: |
 TAGS=$(grep "^tags = " content/posts/*/index.md | cut -d'"' -f2)
 echo "POST_TAGS=$TAGS" >> $GITHUB_ENV

 - name: Send to matching subscribers
 run: |
 curl -X POST https://api.buttondown.email/v1/emails \
 -H "Authorization: Token ${{ secrets.BUTTONDOWN_API_KEY }}" \
 -d "subject=New Post" \
 -d "body=..." \
 -d "tag=$POST_TAGS"

4. SendGrid + GitHub Actions (Fully Custom)

Concept

Build fully customized notification system combining email sending API with CI/CD

How It Works

1. Write new post and Git Push
 ↓
2. GitHub Actions triggered
 ↓
3. Action parses Front Matter
 - Extract title, summary, tags
 ↓
4. Query subscriber DB (Supabase/JSON file)
 - Match each subscriber's keywords
 ↓
5. Filter matching subscribers only
 ↓
6. Send individual emails via SendGrid API

Advantages

✅ Complete control (customize all logic)
✅ Perfect keyword notification implementation
✅ Free tier: SendGrid 100 emails/month
✅ Automation (just git push)
✅ Scalable (DB, logic freely customizable)
✅ Own subscriber data

Disadvantages

❌ Development work required
❌ Maintenance burden
❌ SendGrid free tier limited (100 emails/month)
❌ Must implement subscription form and DB yourself
❌ Spam filter avoidance setup needed

Implementation Difficulty

⭐⭐⭐⭐⭐ (5/5) - Most complex

Architecture

Subscriber Database Options

Option A: JSON File (Simple)

// subscribers.json (encrypted in GitHub repository)
[
 {
 "email": "user@example.com",
 "keywords": ["kubernetes", "docker"],
 "active": true
 },
 {
 "email": "dev@example.com",
 "keywords": ["golang", "rust"],
 "active": true
 }
]

Option B: Supabase (Recommended)

-- subscribers table
CREATE TABLE subscribers (
 id UUID PRIMARY KEY,
 email TEXT UNIQUE NOT NULL,
 keywords TEXT[], -- array type
 active BOOLEAN DEFAULT true,
 created_at TIMESTAMP DEFAULT NOW()
);

GitHub Actions Workflow

name: Email Notification
on:
 push:
 branches: [main]
 paths:
 - 'content/posts/**'

jobs:
 notify:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3

 - name: Setup Node.js
 uses: actions/setup-node@v3
 with:
 node-version: '18'

 - name: Extract Post Metadata
 id: metadata
 run: |
 # Find most recently modified post
 POST_FILE=$(git diff-tree --no-commit-id --name-only -r ${{ github.sha }} | grep 'content/posts' | head -1)

 # Parse Front Matter
 TITLE=$(grep "^title = " $POST_FILE | cut -d'"' -f2)
 TAGS=$(grep "^tags = " $POST_FILE | sed 's/tags = \[//;s/\]//;s/"//g')
 SUMMARY=$(grep "^summary = " $POST_FILE | cut -d'"' -f2)
 URL="https://0andwild.github.io/$(dirname $POST_FILE | sed 's/content\///')"

 echo "title=$TITLE" >> $GITHUB_OUTPUT
 echo "tags=$TAGS" >> $GITHUB_OUTPUT
 echo "summary=$SUMMARY" >> $GITHUB_OUTPUT
 echo "url=$URL" >> $GITHUB_OUTPUT

 - name: Query Matching Subscribers
 id: subscribers
 run: |
 # Query matching subscribers from Supabase
 curl -X POST https://YOUR_PROJECT.supabase.co/rest/v1/rpc/get_matching_subscribers \
 -H "apikey: ${{ secrets.SUPABASE_KEY }}" \
 -H "Content-Type: application/json" \
 -d "{\"post_tags\": \"${{ steps.metadata.outputs.tags }}\"}" \
 > subscribers.json

 - name: Send Emails via SendGrid
 run: |
 # Execute Node.js script
 cat > send-emails.js << 'EOF'
 const sgMail = require('@sendgrid/mail');
 const fs = require('fs');

 sgMail.setApiKey(process.env.SENDGRID_API_KEY);

 const subscribers = JSON.parse(fs.readFileSync('subscribers.json'));
 const title = process.env.POST_TITLE;
 const summary = process.env.POST_SUMMARY;
 const url = process.env.POST_URL;

 subscribers.forEach(async (subscriber) => {
 const msg = {
 to: subscriber.email,
 from: 'noreply@0andwild.github.io',
 subject: `New Post: ${title}`,
 html: `
 <h2>${title}</h2>
 <p>${summary}</p>
 <p>Matched keywords: ${subscriber.matched_keywords.join(', ')}</p>
 <a href="${url}">Read Post</a>
 <hr>
 <small><a href="https://0andwild.github.io/unsubscribe?token=${subscriber.token}">Unsubscribe</a></small>
 `
 };

 await sgMail.send(msg);
 console.log(`Email sent to ${subscriber.email}`);
 });
 EOF

 npm install @sendgrid/mail
 node send-emails.js
 env:
 SENDGRID_API_KEY: ${{ secrets.SENDGRID_API_KEY }}
 POST_TITLE: ${{ steps.metadata.outputs.title }}
 POST_SUMMARY: ${{ steps.metadata.outputs.summary }}
 POST_URL: ${{ steps.metadata.outputs.url }}

Subscription Form Implementation (Hugo Shortcode)

<!-- layouts/shortcodes/subscribe.html -->
<div class="subscription-form">
 <h3>Subscribe to Blog</h3>
 <form id="subscribe-form">
 <input type="email" id="email" placeholder="Email address" required>

 <fieldset>
 <legend>Select topics of interest (get notified only for selected topics)</legend>
 <label><input type="checkbox" name="keywords" value="kubernetes"> Kubernetes</label>
 <label><input type="checkbox" name="keywords" value="docker"> Docker</label>
 <label><input type="checkbox" name="keywords" value="golang"> Go</label>
 <label><input type="checkbox" name="keywords" value="rust"> Rust</label>
 <label><input type="checkbox" name="keywords" value="devops"> DevOps</label>
 </fieldset>

 <button type="submit">Subscribe</button>
 </form>

 <script>
 document.getElementById('subscribe-form').addEventListener('submit', async (e) => {
 e.preventDefault();

 const email = document.getElementById('email').value;
 const keywords = Array.from(document.querySelectorAll('input[name="keywords"]:checked'))
 .map(cb => cb.value);

 // Save to Supabase
 const response = await fetch('https://YOUR_PROJECT.supabase.co/rest/v1/subscribers', {
 method: 'POST',
 headers: {
 'apikey': 'YOUR_ANON_KEY',
 'Content-Type': 'application/json'
 },
 body: JSON.stringify({ email, keywords, active: true })
 });

 if (response.ok) {
 alert('Successfully subscribed!');
 } else {
 alert('An error occurred.');
 }
 });
 </script>
</div>

Supabase Function (Keyword Matching)

-- Function to find matching subscribers
CREATE OR REPLACE FUNCTION get_matching_subscribers(post_tags TEXT)
RETURNS TABLE(email TEXT, matched_keywords TEXT[], token TEXT) AS $$
BEGIN
 RETURN QUERY
 SELECT
 s.email,
 ARRAY(
 SELECT unnest(s.keywords)
 INTERSECT
 SELECT unnest(string_to_array(post_tags, ','))
 ) as matched_keywords,
 s.unsubscribe_token as token
 FROM subscribers s
 WHERE s.active = true
 AND s.keywords && string_to_array(post_tags, ',') -- array overlap operator
 ;
END;
$$ LANGUAGE plpgsql;

Cost Analysis

SendGrid: 100 emails/month free (then $19.95/month)
Supabase: 500MB DB, 2GB transfer free per month
GitHub Actions: 2,000 minutes/month free
Total cost: Completely free (for small blogs)

5. Fully Custom (Supabase + GitHub Actions + Resend)

SendGrid Alternative: Resend

More developer-friendly modern email API than SendGrid

Advantages

✅ Free tier: 3,000 emails/month (30x more than SendGrid!)
✅ Simpler API
✅ React Email support (write emails in JSX)
✅ Better developer experience

Resend Usage Example

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

await resend.emails.send({
 from: 'blog@0andwild.github.io',
 to: subscriber.email,
 subject: `New Post: ${title}`,
 html: `<p>${summary}</p><a href="${url}">Read</a>`
});

Comparison Table

Method	Free Limit	Keyword Alerts	Difficulty	Subscriber Mgmt	Custom	Recommend
Blogtrottr	Unlimited	❌	⭐	❌	❌	Testing only
FeedBurner	Unlimited	❌	⭐⭐	⚠️	⚠️	Not recommended (discontinued)
Mailchimp	2,000	⚠️ (Pro)	⭐⭐	✅	⚠️	General subscriptions
Buttondown	1,000	✅	⭐⭐⭐	✅	✅	For developers
SendGrid + Actions	100/month	✅	⭐⭐⭐⭐⭐	✅	✅✅	Advanced users
Resend + Actions	3,000/month	✅	⭐⭐⭐⭐⭐	✅	✅✅	Perfect control

Recommended Roadmap

Stage 1: Quick Start (Immediate)

Mailchimp RSS Campaign

10-minute setup
All subscribers get all posts

Stage 2: Improvement (After 1 week)

Migrate to Buttondown

Cleaner experience
Basic tag features

Stage 3: Advanced Features (When needed)

Resend + GitHub Actions + Supabase

Keyword-based selective notifications
Complete control
Scalability

Conclusion

For general bloggers:

→ Mailchimp (easiest and most professional)

For developer blogs:

→ Buttondown (developer-friendly, provides API)

If keyword alerts are essential:

→ Resend + GitHub Actions + Supabase (fully custom)

To test without spending money:

→ Blogtrottr (30-second setup)

Quick Start

If you want actual implementation:

Start with Mailchimp (low learning curve)
Consider Buttondown when traffic grows
Build custom solution when advanced features needed

Keyword alerts may be overkill initially, so it’s recommended to start with basic subscriptions.

Hugo Markdown Guide

Thu, 16 Oct 2025 18:36:52 +0900

Heading (H2)

Subheading (H3)

Regular text. Bold, Italic, ~~Strikethrough~~

Images

Method 1: Local Image

Place image file in the post folder:

![Image description](image.jpg)

Method 2: External Image URL

![Image description](https://example.com/image.jpg)

Method 3: HTML Tag (with size control)

<img src="image.jpg" alt="Image description" width="500" />

Carousel Images (Slideshow)

16:9

21:9

Code Blocks

Inline Code

Use inline code format

Code Blocks

package main

import "fmt"

func main() {
 fmt.Println("Hello, World!")
}

def hello():
 print("Hello, World!")

docker run -d -p 8080:80 nginx

Lists

Unordered List

Item 1
Item 2
- Sub-item 2-1
- Sub-item 2-2
Item 3

Ordered List

First
Second
Third

Checklist

Todo 1
Completed
Todo 2

Blockquote

This is a blockquote. Multiple lines are supported.

Table

Item	Description	Note
A	Description A	Note A
B	Description B	Note B

Embedded Links (Shortcodes)

YouTube Video

Twitter/X

GitHub Gist

Alert Boxes (Blowfish Alert)

{{< alert “circle-info” >}} Information alert. {{< /alert >}}

{{< alert “lightbulb” >}} Tips and ideas. {{< /alert >}}

{{< alert “triangle-exclamation” >}} Warning message. {{< /alert >}}

Collapsible (Details)

Click to expand

Hidden content appears here.

Comments

Horizontal Rule

Use to create dividing lines:

Footnotes

You can add footnotes¹ to text.

Chart

Mermaid Diagram

graph LR;
A[Lemons]-->B[Lemonade];
B-->C[Profit]

Swatches (color showcase)

#64748b

#3b82f6

#06b6d4

TypeIt

(Ex1)

(Ex2)

(Ex3)

Youtube Lite

Writing Tips:

Change draft: true to false in front matter to publish
Writing description and summary helps with SEO
It’s recommended to place images in the post folder

This is the footnote content. ↩︎

Why I Switched to Hugo & GitHub Pages

Wed, 15 Oct 2025 17:21:09 +0900

Why I Moved to Hugo & GitHub Pages

I decided to migrate my tech blog from Tstory to Hugo & GitHub Pages.

1. Scattered Content Management

As I used various note-taking tools, the content I wrote at work or while studying became scattered everywhere. Having to transfer these notes to the blog repeatedly became burdensome, which led me to neglect blog management.

2. Markdown Compatibility Issues

The markdown syntax used in my note-taking tools wasn’t fully compatible with Tstory, requiring frequent modifications when publishing posts. This was also a source of frustration.

Specific issues included:

Insufficient syntax highlighting support for code blocks
Table rendering errors
Image path handling problems
Limited mathematical expression support

3. Tstory Open API Support Ended

Recently, I wanted to reorganize my study materials and post them on Tstory while redesigning the blog skin. I also planned to integrate existing note-taking tools using the Tstory Official Open API. However, I discovered that Open API support had been discontinued, and there was no longer a reason to continue using Tstory.

Blog Platform Selection Criteria

After researching various blogs and considering what approach would work best, I settled on Hugo & GitHub Pages based on the following criteria:

Is it easy to set up the blog?
Can it be managed with code?
Is there high flexibility to add features I want?
Is the build and deployment speed fast when using GitHub Pages?
Is it easy to integrate with note-taking tools like Obsidian?

What is Hugo?

Hugo is a fast and flexible Static Site Generator written in the Go language.

Key Features:

Fast build speed: Thousands of pages can be built in seconds
Simple structure: Write content in Markdown and Hugo converts it to HTML
Zero dependencies: Runs as a single binary without requiring separate runtime or database
Rich theme ecosystem: Easy to apply themes for various purposes

Comparing Static Site Generators Used with GitHub Pages

Feature	Hugo	Jekyll	Gatsby	Next.js (SSG)	VuePress
Language	Go	Ruby	React (JavaScript)	React (JavaScript)	Vue.js
Build Speed	⚡ Very Fast (< 1ms/page)	🐢 Slow	🚶 Moderate	🚶 Moderate	🚶 Moderate
Installation Complexity	✅ Single Binary	⚠️ Ruby environment required	⚠️ Node.js + many dependencies	⚠️ Node.js + dependencies	⚠️ Node.js + dependencies
GitHub Pages Native Support	❌ (Actions required)	✅ Native support	❌ (Actions required)	❌ (Actions required)	❌ (Actions required)
Learning Curve	Low	Low	High	Medium-High	Medium
Themes/Plugins	Rich	Very Rich	Rich (React ecosystem)	Rich (React ecosystem)	Moderate
Best For	Blog, Docs, Portfolio	Blog, GitHub default	Complex web apps, Blog	Complex web apps, Hybrid	Technical docs
Build Time (1000 pages)	~1s	~2min	~30s	~30s	~20s

Why I Chose Hugo:

Overwhelming build speed: Build time barely increases even with more content
Simple setup: Focus on Markdown without complex JavaScript frameworks
Zero dependencies: No environment setup issues with a single executable
Rich themes: Easy to apply high-quality themes like Blowfish

GitHub Pages Deployment

Blogs written with Hugo are automatically built and deployed through GitHub Actions.

Deployment Workflow

Push changes to the main branch
GitHub Actions automatically triggers
Hugo builds the static site
Built files are automatically deployed to GitHub Pages

Benefits

Automated deployment: Automatically deploys when you push code
Version control: Track all changes through Git
Free hosting: GitHub Pages is provided for free
Custom domain: Can connect your desired domain
HTTPS support: HTTPS is provided by default

Obsidian Integration

Hugo is markdown-based, making it perfectly compatible with note-taking tools like Obsidian.

Integration Method

Set Hugo blog’s content/posts directory as Obsidian vault
Write and edit posts in Obsidian
When finished writing, commit & push through Git
GitHub Actions automatically builds and deploys

Benefits

Consistent writing environment: Manage all notes and blog posts in the same tool
Perfect markdown compatibility: No additional conversion work needed
Local-first: Can write posts without internet connection
Powerful linking features: Utilize Obsidian’s backlinks and graph view

Terminal Commands

Running Development Server

hugo server

Starts a local development server. By default, you can view the site at http://localhost:1313.

Key Options:

-D or --buildDrafts: Builds draft content as well
--bind 0.0.0.0: Makes server accessible from all network interfaces
--port 8080: Uses a different port instead of the default (1313)
Browser automatically refreshes when files change (Live Reload)

Examples:

hugo server -D
hugo server --bind 0.0.0.0 --port 8080

Production Build

hugo --cleanDestinationDir

Builds the static site for production. Output is generated in the public/ directory.

Key Features:

--cleanDestinationDir: Completely cleans the destination directory (public/) before building
Removes unnecessary files from previous builds for a clean build
Ensures no old versions of files remain even when filenames are changed or deleted

Examples:

hugo --cleanDestinationDir
hugo --cleanDestinationDir --minify # Add file minification option

Theme Information

Hugo Blowfish Theme

This blog uses the Blowfish theme.

Features:

Provides modern and responsive design
Supports dark mode
Fast loading speed and SEO optimized
Multilingual support
Rich customization options

Configuration Files:

config/_default/hugo.toml - Basic Hugo configuration
config/_default/params.toml - Blowfish theme parameters
config/_default/languages.en.toml - Language-specific settings
config/_default/menus.en.toml - Menu configuration

Conclusion

The migration from Tstory to Hugo & GitHub Pages was a choice for a developer-friendly environment. Now I can manage my blog the same way I manage code versions, and with perfect Obsidian integration, I’ve unified the workflow from note-taking to blog posting.

Above all, Hugo’s fast build speed and GitHub Actions’ automated deployment allow me to focus solely on writing, and I can freely customize without being bound by platform constraints.

Going forward, I plan to gradually migrate existing posts from Tstory while steadily adding new content.

References

Hugo Official Site: https://gohugo.io/
Blowfish Theme: https://blowfish.page/
Blowfish Creator: @nunocoracao
Creator Blog: https://n9o.xyz/
Official Docs: https://blowfish.page/docs/
License: MIT License

Blog on 0AndWild_log

Adding Comments to Hugo Blog with Giscus

What is Giscus?

Key Features

Differences from Utterances

Prerequisites

Requirements

Limitations

Step 1: Enable GitHub Discussions

1.1 Navigate to Repository Settings

1.2 Enable Discussions

1.3 Verify

Step 2: Install Giscus App

2.1 Install Giscus GitHub App

2.2 Verify Permissions

Step 3: Generate Giscus Configuration

3.1 Visit Giscus Website

3.2 Connect Repository

3.3 Page ↔️ Discussion Mapping

Recommended: pathname (path name)

Alternatives:

3.4 Select Discussion Category

Recommended: Announcements

Alternative: General

3.5 Feature Selection

Enable Reactions

Emit Metadata

Comment Input Position

Lazy Loading

3.6 Theme Selection

Recommended: preferred_color_scheme

Alternatives:

3.7 Language Setting

Step 4: Copy Generated Code

4.1 Copy Script

4.2 Important Values

Step 5: Integrate with Blowfish Theme

5.1 Create Directory

5.2 Create comments.html File

5.3 Insert Giscus Code

5.4 Configure params.toml

Step 6: Local Testing

6.1 Run Hugo Server

6.2 Verify in Browser

6.3 Write Test Comment

6.4 Check GitHub Discussions

Step 7: Deploy

7.1 Commit to Git

7.2 Push to GitHub

7.3 Check GitHub Actions

7.4 Verify Deployed Site

Advanced Configuration

Dynamic Dark Mode and Language Setting (Recommended)

Complete Dynamic Configuration

How It Works

1. Dynamic Language Setting

2. Dynamic Dark Mode Setting

3. Unified Comments Across Languages

4. Real-time Theme Change Detection

Testing Method

Changing Theme Options

Static Theme Configuration (Simple Method)

Hide Comments on Specific Posts

Separate Comments by Category

Troubleshooting

Comment Widget Not Displaying

Cause 1: Discussions Not Enabled

Cause 2: Giscus App Not Installed

Cause 3: Repository ID Error

Cause 4: showComments Setting Missing

Only Login Button Shows, Can’t Comment

Cause: GitHub OAuth Authorization Needed

Comments Not Saving

Cause: Repository Permission Issue

Dark Mode Not Syncing

Solution: Add JavaScript Sync Code

Managing Giscus

Comment Management

Manage via GitHub Discussions

Handling Spam Comments

Recommended: `pathname` (path name)

Recommended: `Announcements`

Alternative: `General`

Recommended: `preferred_color_scheme`