Blog on 0AndWild_log

Giscus로 Hugo 블로그에 댓글 기능 추가하기

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

Giscus란?

Giscus는 GitHub Discussions를 백엔드로 사용하는 오픈소스 댓글 시스템입니다.

주요 특징

✅ 완전 무료 (GitHub 기능 활용)
✅ 서버 불필요 (GitHub이 모든 것을 처리)
✅ Markdown 완벽 지원 (코드 블록, 이미지, 표 등)
✅ 반응(Reactions) (👍, ❤️, 😄 등)
✅ GitHub 알림 (댓글 달리면 알림 받음)
✅ 다크모드 (블로그 테마와 자동 동기화)
✅ 데이터 소유 (본인 저장소에 저장)

Utterances와의 차이점

기능	Giscus	Utterances
백엔드	GitHub Discussions	GitHub Issues
반응	✅	❌
대댓글	✅ (중첩)	⚠️ (flat)
댓글 정렬	✅	⚠️
적합성	댓글 전용	이슈 트래킹

결론: Giscus가 Utterances의 상위 호환입니다.

사전 준비

필요한 것

GitHub 계정
Public GitHub 저장소 (블로그 저장소)
Hugo + Blowfish 테마

제약사항

⚠️ Public 저장소만 가능 (Private 저장소는 Discussions 기능 제한)
⚠️ GitHub 계정 필요 (익명 댓글 불가)

1단계: GitHub Discussions 활성화

1.1 저장소 설정 페이지 이동

GitHub에서 블로그 저장소 접속

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

Settings 탭 클릭

1.2 Discussions 활성화

페이지를 아래로 스크롤하여 Features 섹션 찾기
Discussions 체크박스를 ✅ 체크
자동으로 저장됨

1.3 확인

저장소 상단에 Discussions 탭이 생성되었는지 확인

Code | Issues | Pull requests | Discussions | ← 새로 생김!

2단계: Giscus App 설치

2.1 Giscus GitHub App 설치

https://github.com/apps/giscus 접속
Install 버튼 클릭
권한 선택:
- All repositories (모든 저장소)
- Only select repositories (특정 저장소만 - 권장)
블로그 저장소 선택:
```
0AndWild/0AndWild.github.io
```
Install 클릭

2.2 권한 확인

Giscus가 요청하는 권한:

✅ Read access to discussions (토론 읽기)
✅ Write access to discussions (토론 쓰기)
✅ Read access to metadata (메타데이터 읽기)

3단계: Giscus 설정 생성

3.1 Giscus 웹사이트 접속

https://giscus.app/ko 방문

3.2 저장소 연결

저장소 섹션에 입력:

0AndWild/0AndWild.github.io

아래에 성공 메시지가 표시되어야 함:

✅ 성공! 이 저장소는 모든 조건을 만족합니다.

만약 오류가 뜨면:

Discussions 활성화 확인
Giscus App 설치 확인
저장소가 Public인지 확인

3.3 페이지 ↔️ Discussion 연결 방식

Discussion 카테고리 섹션에서 선택:

권장: `pathname` (경로명)

매핑: pathname 선택

각 블로그 포스트의 경로가 Discussion 제목이 됩니다.

예시:

포스트: /posts/giscus-guide/
Discussion 제목: posts/giscus-guide

대안들:

URL: 전체 URL 사용 (도메인 변경 시 문제)
title: 포스트 제목 사용 (제목 변경 시 문제)
og:title: OpenGraph 제목
specific term: 직접 지정

3.4 Discussion 카테고리 선택

Discussion 카테고리 드롭다운에서 선택:

권장: `Announcements`

카테고리: Announcements 선택

특징:

관리자만 새 Discussion 생성 가능
댓글은 누구나 가능
블로그 포스트용으로 최적

대안: `General`

누구나 Discussion 생성 가능
더 개방적

추천: Announcements (블로그에 적합)

3.5 기능 선택

반응 활성화

✅ 반응 활성화

사용자가 👍, ❤️, 😄 등으로 반응 가능

메타데이터 보내기

□ 메타데이터 보내기 (체크 해제 권장)

불필요한 기능, 꺼두는 것이 좋음

댓글 입력란 위치

⚪ 댓글 위에
⚪ 댓글 아래 (권장)

권장: 댓글 아래

기존 댓글을 먼저 읽고 작성하도록 유도

느긋한 로딩

✅ 느긋한 로딩

페이지 로딩 속도 향상 (권장)

3.6 테마 선택

권장: `preferred_color_scheme`

테마: preferred_color_scheme

동작:

사용자의 시스템 설정에 따라 자동 전환
다크모드 ↔️ 라이트모드 자동

대안:

light: 항상 밝은 테마
dark: 항상 어두운 테마
transparent_dark: 투명 다크
기타 GitHub 테마들

추천: preferred_color_scheme (자동 전환)

3.7 언어 설정

언어: ko (한국어)

4단계: 생성된 코드 복사

4.1 스크립트 복사

페이지 하단에 Enable giscus 섹션에서 생성된 코드 복사:

<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="ko"
 data-loading="lazy"
 crossorigin="anonymous"
 async>
</script>

4.2 중요한 값들

data-repo-id: 저장소 고유 ID (자동 생성)
data-category-id: 카테고리 고유 ID (자동 생성)

이 값들은 본인의 저장소마다 다르므로, 반드시 Giscus 웹사이트에서 생성된 코드를 사용해야 합니다.

5단계: Blowfish 테마에 통합

5.1 디렉토리 생성

터미널에서 블로그 루트 디렉토리로 이동 후:

mkdir -p layouts/partials

5.2 comments.html 파일 생성

touch layouts/partials/comments.html

또는 IDE/에디터에서 직접 생성:

layouts/
 └── partials/
 └── comments.html ← 새로 생성

5.3 Giscus 코드 삽입

layouts/partials/comments.html 파일에 다음 내용 추가:

<!-- Giscus 댓글 시스템 -->
<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="ko"
 data-loading="lazy"
 crossorigin="anonymous"
 async>
</script>

⚠️ 주의: 위의 data-repo-id와 data-category-id 값을 본인의 값으로 교체해야 합니다!

5.4 params.toml 설정

config/_default/params.toml 파일을 열고 [article] 섹션에 추가:

[article]
 showComments = true # 이 줄 추가 또는 확인
 # ... 기타 설정들

이미 showComments 항목이 있다면 true로 설정되어 있는지 확인하세요.

6단계: 로컬 테스트

6.1 Hugo 서버 실행

hugo server -D

6.2 브라우저에서 확인

http://localhost:1313

포스트 페이지 하단에 Giscus 댓글 위젯이 표시되어야 합니다.

6.3 테스트 댓글 작성

GitHub으로 로그인 버튼 클릭
GitHub OAuth 인증
테스트 댓글 작성
댓글이 표시되는지 확인

6.4 GitHub Discussions 확인

GitHub 저장소 → Discussions 탭
Announcements 카테고리에 새 Discussion 생성되었는지 확인
Discussion 제목이 포스트 경로인지 확인

7단계: 배포

7.1 Git에 커밋

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

7.2 GitHub에 푸시

git push origin main

7.3 GitHub Actions 확인

GitHub Actions가 자동으로 빌드 및 배포를 진행합니다.

배포 상태 확인:

GitHub 저장소 → Actions 탭

7.4 배포된 사이트 확인

https://0andwild.github.io

포스트 페이지에 댓글 위젯이 정상적으로 표시되는지 확인하세요.

고급 설정

다크모드 및 언어 동적 설정 (권장)

Blowfish 테마의 다크모드 토글과 언어 전환에 따라 Giscus가 자동으로 변경되도록 설정하는 완전한 방법입니다.

완전한 동적 설정

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>

동작 방식 설명

1. 언어 동적 설정

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

Hugo 템플릿에서 현재 페이지 언어 가져오기
한국어 페이지: ko, 영어 페이지: en
Giscus에 해당 언어로 설정

결과:

한국어 페이지 → Giscus UI가 한국어로 표시
영어 페이지 → Giscus UI가 영어로 표시
언어 전환 시 페이지 리로드되면서 자동으로 변경

2. 다크모드 동적 설정

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

Blowfish 테마는 다크모드 시 <html class="dark"> 추가
이를 감지하여 테마 결정
dark_tritanopia / light_tritanopia 테마 사용 (색맹 친화적)

결과:

페이지 로드 시: 현재 테마 상태로 Giscus 로드
다크모드 토글 클릭 시: 실시간으로 Giscus 테마 변경

3. 언어별 댓글 통합

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

파일 디렉토리 경로를 Discussion ID로 사용
content/posts/subscription_alert/index.ko.md → posts/subscription_alert
content/posts/subscription_alert/index.en.md → posts/subscription_alert
같은 ID이므로 한국어/영어 버전이 같은 댓글 공유

결과:

한국어 포스트에서 작성한 댓글
영어 포스트에서도 동일하게 표시
포스트별로는 별도 Discussion 생성

4. 실시간 테마 변경 감지

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

MutationObserver로 HTML 클래스 변경 감지
다크모드 토글 클릭 시 즉시 감지
postMessage로 Giscus iframe에 테마 변경 명령 전송

테스트 방법

# 1. 로컬 서버 실행
hugo server -D

# 2. 브라우저에서 확인
http://localhost:1313/posts/subscription_alert/

테스트 항목:

✅ 페이지 로드 시 현재 테마(라이트/다크)로 Giscus 표시
✅ 다크모드 토글 클릭 시 Giscus 테마 즉시 변경
✅ 언어 전환 (ko → en) 시 Giscus 언어 변경
✅ 한국어/영어 페이지에서 같은 댓글 표시

테마 옵션 변경

다른 테마를 사용하려면 getGiscusTheme() 함수 수정:

// 기본 테마
function getGiscusTheme() {
 const isDark = document.documentElement.classList.contains('dark');
 return isDark ? 'dark' : 'light';
}

// 고대비 테마
function getGiscusTheme() {
 const isDark = document.documentElement.classList.contains('dark');
 return isDark ? 'dark_high_contrast' : 'light_high_contrast';
}

// GitHub 스타일 테마
function getGiscusTheme() {
 const isDark = document.documentElement.classList.contains('dark');
 return isDark ? 'dark_dimmed' : 'light';
}

사용 가능한 테마:

light / dark
light_high_contrast / dark_high_contrast
light_tritanopia / dark_tritanopia (색맹 친화적)
dark_dimmed
transparent_dark
preferred_color_scheme (시스템 설정 따름)

정적 테마 설정 (간단한 방법)

동적 변경이 필요 없다면 정적으로 설정 가능:

<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="ko"
 crossorigin="anonymous"
 async>
</script>

장점: 간단함 단점: 실시간 테마 변경 불가, 언어별 댓글 분리됨

포스트별 댓글 숨기기

특정 포스트에서만 댓글을 숨기려면, 해당 포스트의 front matter에:

---
title: "댓글 없는 포스트"
showComments: false # 이 포스트만 댓글 숨김
---

카테고리별 댓글 분리

다른 카테고리의 포스트에 다른 Discussion 카테고리를 사용하려면:

<!-- 조건부 카테고리 설정 -->
<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>

문제 해결

댓글 위젯이 표시되지 않음

원인 1: Discussions 미활성화

해결: GitHub 저장소 → Settings → Discussions 체크

원인 2: Giscus App 미설치

해결: https://github.com/apps/giscus 에서 Install

원인 3: 저장소 ID 오류

해결: giscus.app에서 코드 재생성

원인 4: showComments 설정 누락

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

로그인 버튼만 보이고 댓글 못 씀

원인: GitHub OAuth 승인 필요

1. "GitHub으로 로그인" 클릭
2. OAuth 권한 승인
3. 저장소로 리다이렉트
4. 댓글 작성 가능

댓글이 저장되지 않음

원인: 저장소 권한 문제

확인 사항:
1. 저장소가 Public인지
2. Giscus App 권한에 저장소 포함되어 있는지
3. Discussion 카테고리가 존재하는지

다크모드가 동기화 안 됨

해결: JavaScript 동기화 코드 추가

위의 “고급 설정 > 다크모드 자동 전환” 참고

Giscus 관리

댓글 관리

GitHub Discussions에서 관리

1. GitHub 저장소 → Discussions 탭
2. 해당 Discussion 클릭
3. 관리 작업:
 - 댓글 수정 (본인 댓글만)
 - 댓글 삭제 (관리자)
 - 사용자 차단 (관리자)
 - Discussion 잠금 (관리자)

스팸 댓글 처리

1. GitHub Discussions에서 스팸 댓글 찾기
2. 댓글 옆 ... 메뉴 → "Delete"
3. 사용자 차단: 프로필 → Block user

알림 설정

GitHub 알림으로 댓글 알림 받기

1. GitHub → Settings → Notifications
2. Watching에 저장소 추가
3. 이메일로 알림 받기 설정

특정 Discussion만 알림 받기

1. Discussions 탭 → 해당 Discussion
2. 오른쪽 "Subscribe" 버튼
3. "Notify me" 선택

통계 및 분석

댓글 통계 보기

GitHub Discussions에서:

1. Discussions 탭
2. 카테고리별 Discussion 수 확인
3. 각 Discussion의 댓글 수 확인

GitHub Insights 활용

GitHub 저장소 → Insights → Community
→ Discussions 활동 확인

비용 및 제한사항

비용

완전 무료

GitHub 계정만 있으면 사용 가능
저장소 크기 제한 내에서 무제한 댓글

제한사항

GitHub API Rate Limit

시간당 60회 (미인증)
시간당 5,000회 (인증)
Giscus는 캐싱으로 최적화되어 있어 문제 없음

저장소 크기

GitHub Free: 저장소당 1GB
텍스트 댓글만으로는 제한 도달 불가능

Discussions 제한

없음 (무제한)

대안 비교

Giscus vs Utterances

항목	Giscus	Utterances
백엔드	Discussions	Issues
반응	✅	❌
대댓글	중첩 지원	Flat
추천	⭐⭐⭐⭐⭐	⭐⭐⭐

결론: Giscus 사용 권장

Giscus vs Disqus

항목	Giscus	Disqus
비용	무료	무료 (광고)
광고	❌	✅
익명 댓글	❌	✅ (Guest)
Markdown	✅	⚠️
데이터 소유	✅	❌
추천	개발자 블로그	일반 블로그

마이그레이션 가이드

Utterances → Giscus

1. GitHub Issues를 Discussions로 변환
 - 수동 작업 필요 (자동화 없음)
 - 또는 Issues 그대로 두고 Giscus 새로 시작

2. comments.html 파일 교체
 - Utterances 코드 삭제
 - Giscus 코드 추가

3. 배포

Disqus → Giscus

1. Disqus 데이터 Export (XML)
2. GitHub Discussions로 수동 이전
 - 자동화 도구 없음
 - 스크립트 직접 작성 필요
 - 또는 새로 시작 권장

추가 리소스

공식 문서

커뮤니티

체크리스트

설치 완료 확인:

GitHub Discussions 활성화
Giscus App 설치
layouts/partials/comments.html 생성
Giscus 코드 삽입 (본인의 ID로)
params.toml에 showComments = true
로컬 테스트 완료
GitHub에 푸시
배포된 사이트에서 확인
테스트 댓글 작성
GitHub Discussions에 생성 확인

결론

Giscus는 Hugo/GitHub Pages 블로그에 가장 적합한 댓글 시스템입니다:

장점 정리

✅ 완전 무료 ✅ 설정 간단 (10분) ✅ 서버 불필요 ✅ Markdown 완벽 지원 ✅ GitHub 통합 ✅ 데이터 소유

단점

❌ GitHub 계정 필수 (익명 불가) ❌ 기술 블로그에 적합 (일반 사용자는 허들 있음)

Hugo & GithubPages 블로그 댓글 시스템 구현 가이드

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

개요

정적 사이트 생성기(Hugo)로 만든 블로그에 댓글 기능을 추가하는 모든 방법을 비교 분석합니다. 익명 댓글, GitHub 로그인, 소셜 로그인 등 다양한 요구사항에 맞는 솔루션을 제시합니다.

댓글 시스템 분류

인증 방식에 따른 분류

인증 방식	시스템
GitHub 전용	Giscus, Utterances
익명 가능	Remark42, Commento, Comentario, HashOver
익명 + 소셜 로그인	Remark42, Commento, Disqus
소셜 로그인만	Disqus, Hyvor Talk

호스팅 방식에 따른 분류

호스팅	시스템
SaaS (관리 불필요)	Giscus, Utterances, Disqus, Hyvor Talk
셀프 호스팅	Remark42, Commento, Comentario, HashOver
하이브리드	Cusdis (Vercel 무료 배포)

1. Giscus (최고 추천 - GitHub 사용자용)

개념

GitHub Discussions를 백엔드로 사용하는 댓글 시스템

동작 방식

1. 사용자가 블로그 방문
 ↓
2. Giscus 위젯 로드
 ↓
3. GitHub OAuth로 로그인
 ↓
4. 댓글 작성
 ↓
5. GitHub Discussions에 자동 저장
 ↓
6. 블로그에 실시간 표시

장점

✅ 완전 무료 (GitHub 기능 활용)
✅ 서버 불필요 (GitHub이 백엔드)
✅ 데이터 소유 (본인 저장소에 저장)
✅ Markdown 지원 (코드 블록, 이미지 등)
✅ 반응(Reactions) 지원 (👍, ❤️ 등)
✅ 알림 (GitHub 알림으로 댓글 알림)
✅ 다크 모드 (블로그 테마와 동기화)
✅ 스팸 방지 (GitHub 계정 필요)
✅ 관리 간편 (GitHub Discussions에서 관리)
✅ 검색 가능 (GitHub 검색으로 댓글 검색)

단점

❌ 익명 댓글 불가 (GitHub 계정 필수)
❌ 기술 블로그에 적합 (일반 사용자는 GitHub 계정 없을 수 있음)
❌ GitHub 의존성 (GitHub 장애 시 댓글 불가)

구현 난이도

⭐⭐ (2/5)

설정 방법

1단계: GitHub Discussions 활성화

1. GitHub 저장소 → Settings
2. Features 섹션 → Discussions 체크

2단계: Giscus 설정

giscus.app 방문
저장소 입력: username/repository
설정 선택:
- 페이지 ↔️ Discussion 연결: pathname (권장)
- Discussion 카테고리: Announcements 또는 General
- 기능: 반응, 댓글 위로
- 테마: 블로그에 맞게 선택

3단계: 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="ko"
 crossorigin="anonymous"
 async>
</script>

4단계: params.toml 설정

[article]
 showComments = true

테마 동기화 (다크모드)

<script>
 // 블로그 테마 변경 시 Giscus 테마도 변경
 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>

비용

완전 무료

2. Utterances

개념

GitHub Issues를 백엔드로 사용하는 댓글 시스템 (Giscus의 전신)

동작 방식

1. GitHub OAuth 로그인
 ↓
2. 댓글 작성
 ↓
3. GitHub Issues에 저장 (각 포스트 = 1개 Issue)
 ↓
4. 블로그에 표시

장점

✅ 완전 무료
✅ 가벼움 (TypeScript)
✅ 간단한 설정
✅ Markdown 지원

단점

❌ Issues 사용 (Discussions보다 덜 적합)
❌ Giscus보다 기능 적음
❌ 익명 불가

Giscus vs Utterances

기능	Giscus	Utterances
백엔드	Discussions	Issues
반응	✅	❌
댓글에 댓글	✅ (nested)	⚠️ (flat)
적합성	댓글 전용	이슈 트래킹용

결론: Giscus가 Utterances의 상위 호환

구현 난이도

⭐⭐ (2/5)

설정 방법

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

3. Remark42 (최고 추천 - 익명 + 소셜 로그인)

개념

오픈소스 셀프 호스팅 댓글 시스템으로, 익명 및 다양한 소셜 로그인 지원

동작 방식

1. Remark42 서버 배포 (Docker)
 ↓
2. 블로그에 Remark42 스크립트 삽입
 ↓
3. 사용자 선택:
 - 익명 댓글 작성
 - GitHub/Google/Twitter 로그인 후 작성
 ↓
4. Remark42 DB에 저장
 ↓
5. 블로그에 표시

장점

✅ 익명 댓글 가능 (설정으로 켜고 끌 수 있음)
✅ 다양한 소셜 로그인 (GitHub, Google, Facebook, Twitter, Email)
✅ 완전 무료 (오픈소스)
✅ 광고 없음
✅ 데이터 소유 (본인 서버)
✅ Markdown 지원
✅ 댓글 수정/삭제
✅ 관리자 모드 (댓글 승인/차단/삭제)
✅ 알림 (이메일/Telegram)
✅ Import/Export (다른 시스템에서 마이그레이션)
✅ 투표 (찬성/반대)
✅ 스팸 필터

단점

❌ 셀프 호스팅 필요 (Docker 서버)
❌ 유지보수 책임
❌ 호스팅 비용 (월 $5~, 무료 티어 가능)

구현 난이도

⭐⭐⭐⭐ (4/5)

호스팅 옵션

옵션 1: Railway (추천)

1. Railway.app 회원가입
2. "New Project" → "Deploy from GitHub"
3. Remark42 Docker 이미지 선택
4. 환경변수 설정:
 - REMARK_URL=https://your-remark42.railway.app
 - SECRET=your-random-secret
 - AUTH_ANON=true # 익명 댓글 허용
 - AUTH_GITHUB_CID=your_client_id
 - AUTH_GITHUB_CSEC=your_client_secret

Railway 무료 티어:

월 $5 크레딧
소규모 블로그 충분

옵션 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 무료 티어:

3개 앱
소규모 블로그 충분

옵션 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  # 익명 허용
 - AUTH_GITHUB_CID=xxx  # GitHub 로그인
 - AUTH_GITHUB_CSEC=xxx
 - AUTH_GOOGLE_CID=xxx  # Google 로그인
 - AUTH_GOOGLE_CSEC=xxx
 - ADMIN_SHARED_ID=github_username  # 관리자
 volumes:
 - ./data:/srv/var
 ports:
 - "8080:8080"

docker-compose up -d

블로그 삽입 코드

<!-- 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: 'ko',
 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>

익명 + GitHub 동시 사용 설정

# 환경변수
AUTH_ANON=true # 익명 허용
AUTH_GITHUB_CID=xxx # GitHub OAuth App ID
AUTH_GITHUB_CSEC=xxx # GitHub OAuth App Secret
ANON_VOTE=false # 익명 사용자 투표 불가 (스팸 방지)

사용자는 선택 가능:

“익명으로 댓글 달기”
“GitHub으로 로그인”

관리자 기능

# 관리자 지정
ADMIN_SHARED_ID=github_yourusername

# 또는 이메일
ADMIN_SHARED_EMAIL=you@example.com

관리자 가능 작업:

댓글 삭제
사용자 차단
댓글 고정
읽기 전용 모드

비용

Railway: 무료 또는 월 $5
Fly.io: 무료 티어 가능
VPS (DigitalOcean 등): 월 $5~

4. Commento / Comentario

개념

프라이버시 중심의 경량 댓글 시스템

Commento vs Comentario

항목	Commento	Comentario
상태	개발 중단	활발히 개발 중 (Commento 포크)
라이선스	MIT	MIT
언어	Go	Go
추천	❌	✅

결론: Comentario 사용 권장

Comentario 장점

✅ 익명 댓글 가능
✅ 소셜 로그인 (GitHub, Google, GitLab, SSO)
✅ 가벼움 (Go 기반)
✅ 프라이버시 중심
✅ Markdown 지원
✅ 투표 기능

단점

❌ 셀프 호스팅 필요
❌ Remark42보다 기능 적음

구현 난이도

⭐⭐⭐⭐ (4/5)

Docker 배포

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:

블로그 삽입

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

5. Disqus (전통적 SaaS)

개념

가장 오래되고 널리 사용되는 클라우드 댓글 시스템

동작 방식

1. Disqus 계정 생성 및 사이트 등록
 ↓
2. 블로그에 Disqus 스크립트 삽입
 ↓
3. 사용자 선택:
 - Guest (익명 - 이메일 필요)
 - Disqus 계정
 - Facebook/Twitter/Google 로그인
 ↓
4. Disqus 서버에 저장
 ↓
5. 블로그에 표시

장점

✅ 설정 초간단 (5분)
✅ 서버 불필요 (SaaS)
✅ Guest 모드 (이메일만으로 댓글)
✅ 소셜 로그인 (Facebook, Twitter, Google)
✅ 강력한 관리자 도구
✅ 스팸 필터 (Akismet 통합)
✅ 모바일 앱 (iOS/Android)
✅ 분석/통계

단점

❌ 광고 표시 (무료 플랜)
❌ 무거움 (스크립트 크기)
❌ 프라이버시 우려 (데이터 추적)
❌ 데이터 소유권 없음 (Disqus 서버)
❌ GitHub 로그인 없음
❌ 광고 제거 비용 (월 $11.99~)

구현 난이도

⭐ (1/5) - 가장 쉬움

설정 방법

1단계: Disqus 사이트 등록

1. disqus.com 가입
2. "I want to install Disqus on my site" 선택
3. Website Name 입력 (예: andwild-blog)
4. Category 선택
5. Plan 선택 (Basic - Free)

2단계: Blowfish 설정

# config/_default/config.toml
[services.disqus]
 shortname = "andwild-blog" # 1단계에서 생성한 이름

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

Hugo는 Disqus를 기본 지원하므로 자동으로 댓글 표시됨!

3단계: Guest 댓글 허용

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

광고 제거 방법

방법 1: 유료 플랜 ($11.99/월~)

Plus Plan: 광고 없음
Pro Plan: 광고 없음 + 고급 기능

방법 2: CSS로 숨기기 (비추천 - 약관 위반 가능)

/* 비추천: Disqus 약관 위반 가능 */
#disqus_thread iframe[src*="ads"] {
 display: none !important;
}

비용

무료: 광고 있음
Plus: $11.99/월 (광고 없음)
Pro: $89/월 (고급 기능)

6. Cusdis (Vercel 무료 배포)

개념

경량 오픈소스 댓글 시스템, Vercel에 무료 배포 가능

동작 방식

1. Cusdis를 Vercel에 배포 (1-Click)
 ↓
2. PostgreSQL 연결 (Vercel 무료)
 ↓
3. 대시보드에서 사이트 추가
 ↓
4. 블로그에 스크립트 삽입
 ↓
5. 사용자가 이메일 + 이름으로 댓글

장점

✅ 완전 무료 (Vercel 무료 티어)
✅ 익명 댓글 (이메일 + 이름만)
✅ 가벼움 (50KB)
✅ 설정 간단 (Vercel 1-Click 배포)
✅ 프라이버시 중심
✅ 오픈소스

단점

❌ Markdown 미지원
❌ 소셜 로그인 없음
❌ 기능 단순

구현 난이도

⭐⭐⭐ (3/5)

설정 방법

1단계: Vercel 배포

1. https://cusdis.com/ 방문
2. "Deploy with Vercel" 클릭
3. GitHub 연결
4. PostgreSQL 추가 (Vercel Storage)
5. 배포 완료

2단계: 사이트 추가

1. 배포된 Cusdis 대시보드 접속
2. "Add Website" 클릭
3. Domain 입력: 0andwild.github.io
4. App ID 복사

3단계: 블로그 삽입

<!-- 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>

비용

완전 무료 (Vercel 무료 티어)

7. HashOver

개념

PHP 기반의 완전 익명 댓글 시스템

장점

✅ 완전 익명 (아무 정보도 필요 없음)
✅ PHP + flat file (DB 불필요)
✅ 오픈소스

단점

❌ PHP 필요 (정적 사이트에 부적합)
❌ GitHub 로그인 없음
❌ 오래된 프로젝트

구현 난이도

⭐⭐⭐⭐ (4/5)

8. Hyvor Talk (프리미엄 SaaS)

개념

광고 없는 프리미엄 댓글 시스템

장점

✅ 광고 없음
✅ 익명 댓글 가능
✅ 소셜 로그인
✅ 강력한 스팸 필터

단점

❌ 유료 (월 $5~)
❌ GitHub 로그인 없음

비용

Starter: $5/월 (1 사이트)
Pro: $15/월 (3 사이트)

비교표

인증 방식별

시스템	익명	GitHub	Google	기타 소셜	난이도	비용
Giscus	❌	✅	❌	❌	⭐⭐	무료
Utterances	❌	✅	❌	❌	⭐⭐	무료
Remark42	✅	✅	✅	✅	⭐⭐⭐⭐	$5/월
Comentario	✅	✅	✅	✅	⭐⭐⭐⭐	$5/월
Disqus	⚠️	❌	✅	✅	⭐	무료 (광고)
Cusdis	✅	❌	❌	❌	⭐⭐⭐	무료
Hyvor Talk	✅	❌	✅	✅	⭐	$5/월

기능별

시스템	Markdown	반응	투표	알림	관리자	스팸필터
Giscus	✅	✅	❌	✅	⚠️	✅
Remark42	✅	❌	✅	✅	✅	✅
Disqus	⚠️	❌	✅	✅	✅	✅
Cusdis	❌	❌	❌	⚠️	✅	⚠️

호스팅별

시스템	호스팅	데이터 위치	의존성
Giscus	GitHub	GitHub Discussions	GitHub
Remark42	셀프	본인 서버	Docker
Disqus	Disqus	Disqus 서버	Disqus
Cusdis	Vercel	Vercel DB	Vercel

선택 가이드

시나리오별 추천

1. “개발자 블로그, GitHub 사용자 대상”

→ Giscus ⭐⭐⭐⭐⭐

무료, 간단, Markdown 지원
GitHub 통합으로 알림도 편함

2. “일반 블로그, 익명 댓글 필수”

→ Cusdis (간단) 또는 Remark42 (고급)

Cusdis: 5분 설정, 완전 무료
Remark42: 더 많은 기능, 소셜 로그인 포함

3. “익명 + GitHub 로그인 둘 다”

→ Remark42 ⭐⭐⭐⭐⭐

유일하게 둘 다 지원
관리자 기능 강력

4. “기술 없음, 빠르게 설정”

→ Disqus

5분 설정
광고는 감수

5. “완전 무료 + 서버 관리 싫음”

→ Giscus (GitHub) 또는 Cusdis (익명)

6. “프라이버시 최우선”

→ Remark42 또는 Comentario (셀프 호스팅)

데이터 완전 통제

실전 구현: Blowfish + Giscus

전체 설정 과정

1. GitHub Discussions 활성화

GitHub 저장소 → Settings → Features → Discussions 체크

2. Giscus App 설치

https://github.com/apps/giscus 방문 → Install
→ 저장소 선택

3. Giscus 설정 생성

giscus.app/ko에서:

저장소: 0AndWild/0AndWild.github.io
매핑: pathname
카테고리: Announcements
테마: preferred_color_scheme
언어: ko

생성된 코드 복사

4. 파일 생성

# 디렉토리 생성 (없으면)
mkdir -p layouts/partials

# 파일 생성
touch layouts/partials/comments.html

5. 코드 삽입

<!-- 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="ko"
 crossorigin="anonymous"
 async>
</script>

6. params.toml 수정

[article]
 showComments = true

7. 로컬 테스트

hugo server -D
# http://localhost:1313 에서 확인

8. 배포

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

실전 구현: Blowfish + Remark42 (Railway)

전체 설정 과정

1. 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

생성 후:
Client ID 복사
Client Secret 생성 및 복사

2. Railway 배포

1. railway.app 가입
2. "New Project" → "Deploy Docker Image"
3. Image: umputun/remark42:latest
4. 환경변수 추가:

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. 배포 확인

Railway가 자동으로 URL 생성:
https://your-project.railway.app

브라우저에서 접속하여 Remark42 UI 확인

4. 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: 'ko'
 };

 (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. 테스트 및 배포

hugo server -D
# 확인 후
git add .
git commit -m "Add Remark42 comments"
git push

마이그레이션 가이드

Disqus → Giscus

1. Disqus에서 데이터 Export (XML)
2. GitHub Discussions로 수동 이전
 (자동화 스크립트 없음, 수동 작업 필요)

Disqus → Remark42

1. Disqus XML Export
2. Remark42 Admin → Import → Disqus 선택
3. XML 파일 업로드

결론

최종 추천

상황	추천 시스템	이유
개발자 블로그	Giscus	무료, GitHub 통합, Markdown
일반 블로그 (익명 필요)	Cusdis	무료, 간단, 익명
익명 + 소셜 둘 다	Remark42	유연함, 모든 기능
빠른 설정	Disqus	5분 완료 (광고 감수)
완전 통제	Remark42	셀프 호스팅, 커스터마이징

개인 추천 (0AndWild 블로그)

Giscus 사용 권장

GitHub Pages 블로그에 완벽히 어울림
기술 블로그는 GitHub 사용자가 주 독자
무료, 간단, 유지보수 없음

대안: Remark42 (익명 댓글 원할 때)

빠른시작

Giscus로 시작 (10분)
사용자 피드백 수집
익명 댓글 요청 많으면 Remark42로 전환 고려

댓글 시스템은 나중에도 바꿀 수 있으니, 일단 Giscus로 시작하는 것을 강력히 권장합니다!

Hugo & GithubPages 블로그 구독 및 이메일 알림 시스템 구현 가이드

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

개요

정적 사이트 생성기(Hugo)로 만든 블로그에 구독 및 이메일 알림 기능을 추가하는 방법을 분석합니다. 특히 키워드 기반 선택적 알림 기능 구현까지 다룹니다.

1. RSS Feed + 이메일 서비스

개념

Hugo의 기본 RSS Feed를 이메일로 변환하는 서비스를 활용하는 방식입니다.

방법 A: Blogtrottr

동작 방식

1. Hugo가 자동 생성한 RSS Feed (index.xml)
 ↓
2. 사용자가 Blogtrottr에 RSS URL 등록
 ↓
3. Blogtrottr가 주기적으로 RSS 확인
 ↓
4. 새 글 감지 시 이메일 발송

장점

✅ 개발자 작업 없음 (링크만 제공)
✅ 완전 무료
✅ 즉시 사용 가능
✅ 서버 없이 동작

단점

❌ 구독자 관리 불가
❌ 이메일 디자인 커스텀 불가
❌ 통계 없음
❌ 키워드 필터링 불가
❌ 사용자가 직접 외부 사이트에서 등록해야 함

구현 난이도

⭐ (1/5) - 가장 쉬움

사용 예시

블로그에 링크 추가:
[이메일로 구독하기](https://blogtrottr.com)
(사이트에서 https://0andwild.github.io/index.xml 입력)

방법 B: FeedBurner (Google)

동작 방식

1. FeedBurner에 RSS Feed 등록
 ↓
2. FeedBurner가 RSS를 프록시/관리
 ↓
3. 구독 폼을 블로그에 삽입
 ↓
4. 사용자가 블로그에서 직접 구독
 ↓
5. 새 글 발행 시 자동 이메일 발송

장점

✅ 기본 통계 제공
✅ 구독 폼 제공
✅ 무료
✅ RSS 관리 기능

단점

❌ Google의 지원 중단 가능성 (업데이트 중단됨)
❌ 키워드 필터링 불가
❌ 커스텀 제한적
❌ 오래된 UI

구현 난이도

⭐⭐ (2/5)

2. Mailchimp + RSS Campaign (추천)

개념

전문 이메일 마케팅 플랫폼을 활용하여 RSS Feed를 자동으로 이메일로 변환

동작 방식

1. Mailchimp에 RSS Campaign 생성
 ↓
2. RSS URL 등록 및 체크 주기 설정 (일/주/월)
 ↓
3. 블로그에 Mailchimp 구독 폼 삽입
 ↓
4. 사용자가 이메일 입력하여 구독
 ↓
5. 새 글 감지 시 자동으로 이메일 템플릿 생성
 ↓
6. 전체 구독자에게 발송

장점

✅ 무료 티어: 2,000명 구독자까지
✅ 전문적인 이메일 디자인 (드래그 앤 드롭 에디터)
✅ 구독자 관리 (추가/삭제/세그먼트)
✅ 상세한 통계 (오픈율, 클릭율, 구독 해지율)
✅ 구독 폼 자동 생성 (임베드 코드 제공)
✅ 자동화 (새 글만 발송)
✅ 모바일 최적화
✅ 스팸 필터 회피 (전문 발송 서버)

단점

❌ 키워드 필터링 기본 미지원 (Pro 플랜에서 태그별 세그먼트 가능)
❌ 무료 티어에서 Mailchimp 로고 표시
❌ 2,000명 초과 시 유료 ($13/월~)

구현 난이도

⭐⭐ (2/5)

설정 단계

1. Mailchimp 계정 생성
2. Audience 생성
3. Campaign → Create → Email → RSS Campaign
4. RSS URL 입력: https://your-blog.com/index.xml
5. 발송 주기 설정 (Daily/Weekly)
6. 이메일 템플릿 디자인
7. 구독 폼 코드 복사
8. Hugo에 삽입 (layouts/partials/subscribe.html)

블로그 삽입 코드 예시

<!-- Mailchimp 구독 폼 -->
<div id="mc_embed_signup">
 <form action="https://your-mailchimp-url.com/subscribe" method="post">
 <input type="email" name="EMAIL" placeholder="이메일 주소" required>
 <button type="submit">구독하기</button>
 </form>
</div>

3. Buttondown (개발자 친화적, 추천)

개념

Markdown 기반의 뉴스레터 플랫폼으로, API를 통한 커스터마이징이 가능

동작 방식

1. Buttondown에 RSS Feed 연동
 ↓
2. 자동으로 RSS 항목을 Markdown 이메일로 변환
 ↓
3. 구독자가 태그/키워드 선택 가능
 ↓
4. API를 통해 특정 태그 구독자만 필터링 가능
 ↓
5. 매칭되는 구독자에게만 발송

장점

✅ 무료 티어: 1,000명까지
✅ Markdown 기반 (개발자 친화적)
✅ 강력한 API (커스텀 가능)
✅ 태그 기반 구독 (키워드 필터링 구현 가능)
✅ 광고 없음
✅ 깔끔한 UI
✅ RSS import 자동화
✅ 프라이버시 중심

단점

❌ 이메일 디자인이 단순 (Markdown만)
❌ 통계 기능이 Mailchimp보다 약함
❌ 한국어 지원 부족

구현 난이도

⭐⭐⭐ (3/5) - API 사용 시 난이도 증가

키워드 알림 구현 예시

1단계: 구독 폼에 태그 선택 추가

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

 <label>관심 주제 선택:</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">구독하기</button>
</form>

2단계: 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 (완전 커스텀)

개념

이메일 발송 API와 CI/CD를 결합하여 완전히 커스터마이징된 알림 시스템 구축

동작 방식

1. 새 글 작성 후 Git Push
 ↓
2. GitHub Actions 트리거
 ↓
3. Action에서 Front Matter 파싱
 - 글 제목, 요약, 태그 추출
 ↓
4. 구독자 DB 조회 (Supabase/JSON 파일)
 - 각 구독자의 관심 키워드와 매칭
 ↓
5. 매칭되는 구독자만 필터링
 ↓
6. SendGrid API로 개별 이메일 발송

장점

✅ 완전한 통제 (모든 로직 커스터마이징)
✅ 키워드 알림 완벽 구현
✅ 무료 티어: SendGrid 월 100통
✅ 자동화 (Git push만 하면 됨)
✅ 확장 가능 (DB, 로직 자유롭게)
✅ 구독자 데이터 소유

단점

❌ 개발 작업 필요
❌ 유지보수 부담
❌ SendGrid 무료 티어 제한적 (월 100통)
❌ 구독 폼, DB 직접 구현 필요
❌ 스팸 필터 회피 설정 필요

구현 난이도

⭐⭐⭐⭐⭐ (5/5) - 가장 복잡

아키텍처

구독자 데이터베이스 옵션

옵션 A: JSON 파일 (간단)

// subscribers.json (GitHub 저장소에 암호화하여 저장)
[
 {
 "email": "user@example.com",
 "keywords": ["kubernetes", "docker"],
 "active": true
 },
 {
 "email": "dev@example.com",
 "keywords": ["golang", "rust"],
 "active": true
 }
]

옵션 B: Supabase (권장)

-- subscribers 테이블
CREATE TABLE subscribers (
 id UUID PRIMARY KEY,
 email TEXT UNIQUE NOT NULL,
 keywords TEXT[], -- 배열 형태
 active BOOLEAN DEFAULT true,
 created_at TIMESTAMP DEFAULT NOW()
);

GitHub Actions 워크플로우

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: |
 # 가장 최근 수정된 포스트 찾기
 POST_FILE=$(git diff-tree --no-commit-id --name-only -r ${{ github.sha }} | grep 'content/posts' | head -1)

 # 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: |
 # 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: |
 # Node.js 스크립트 실행
 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: `새 글: ${title}`,
 html: `
 <h2>${title}</h2>
 <p>${summary}</p>
 <p>관심 키워드와 일치: ${subscriber.matched_keywords.join(', ')}</p>
 <a href="${url}">글 읽기</a>
 <hr>
 <small><a href="https://0andwild.github.io/unsubscribe?token=${subscriber.token}">구독 취소</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 }}

구독 폼 구현 (Hugo Shortcode)

<!-- layouts/shortcodes/subscribe.html -->
<div class="subscription-form">
 <h3>블로그 구독하기</h3>
 <form id="subscribe-form">
 <input type="email" id="email" placeholder="이메일 주소" required>

 <fieldset>
 <legend>관심 주제 선택 (선택한 주제의 글만 알림)</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">구독하기</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);

 // 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('구독이 완료되었습니다!');
 } else {
 alert('오류가 발생했습니다.');
 }
 });
 </script>
</div>

Supabase 함수 (키워드 매칭)

-- 매칭되는 구독자를 찾는 함수
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, ',') -- 배열 겹침 연산자
 ;
END;
$$ LANGUAGE plpgsql;

비용 분석

SendGrid: 월 100통 무료 (이후 $19.95/월)
Supabase: 월 500MB DB, 2GB 전송 무료
GitHub Actions: 월 2,000분 무료
총 비용: 완전 무료 (소규모 블로그)

5. 완전 커스텀 (Supabase + GitHub Actions + Resend)

SendGrid 대안: Resend

SendGrid보다 개발자 친화적인 최신 이메일 API

장점

✅ 무료 티어: 월 3,000통 (SendGrid의 30배!)
✅ 더 간단한 API
✅ React Email 지원 (JSX로 이메일 작성)
✅ 더 나은 개발자 경험

Resend 사용 예시

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: `새 글: ${title}`,
 html: `<p>${summary}</p><a href="${url}">읽기</a>`
});

비교표

방법	무료 한도	키워드 알림	난이도	구독자 관리	커스텀	추천
Blogtrottr	무제한	❌	⭐	❌	❌	테스트용
FeedBurner	무제한	❌	⭐⭐	⚠️	⚠️	비추천 (지원 중단)
Mailchimp	2,000명	⚠️ (Pro)	⭐⭐	✅	⚠️	일반 구독용
Buttondown	1,000명	✅	⭐⭐⭐	✅	✅	개발자용
SendGrid + Actions	100통/월	✅	⭐⭐⭐⭐⭐	✅	✅✅	고급 사용자
Resend + Actions	3,000통/월	✅	⭐⭐⭐⭐⭐	✅	✅✅	완벽한 통제

결론

일반 블로거라면:

→ Mailchimp (가장 쉽고 전문적)

개발자 블로그라면:

→ Buttondown (개발자 친화적, API 제공)

키워드 알림이 필수라면:

→ Resend + GitHub Actions + Supabase (완전 커스텀)

돈 안 쓰고 테스트하려면:

→ Blogtrottr (30초 설정)

빠른시작

실제 구현을 원하신다면:

Mailchimp로 시작 (학습 곡선 낮음)
트래픽 증가 시 Buttondown 고려
고급 기능 필요 시 커스텀 솔루션 구축

키워드 알림은 초기엔 과한 기능일 수 있으니, 기본 구독부터 시작하는 것을 권장합니다.

Hugo markdown 설명서

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

제목 (H2)

소제목 (H3)

일반 텍스트입니다. 굵게, 기울임, ~~취소선~~

이미지 삽입

방법 1: 로컬 이미지

포스트 폴더 내에 이미지 파일을 넣고 사용:

![이미지 설명](image.jpg)

방법 2: 외부 이미지 URL

![이미지 설명](https://example.com/image.jpg)

방법 3: HTML 태그 (크기 조정 가능)

<img src="image.jpg" alt="이미지 설명" width="500" />

캐러셀 이미지 (슬라이드 효과)

16:9

21:9

코드 삽입

인라인 코드

inline code 형식으로 작성

코드 블록

package main

import "fmt"

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

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

docker run -d -p 8080:80 nginx

링크

리스트

순서 없는 리스트

항목 1
항목 2
- 하위 항목 2-1
- 하위 항목 2-2
항목 3

순서 있는 리스트

첫 번째
두 번째
세 번째

체크리스트

할 일 1
완료된 일
할 일 2

인용문

인용문 내용입니다. 여러 줄도 가능합니다.

표 (Table)

항목	설명	비고
A	설명 A	비고 A
B	설명 B	비고 B

링크 임베드 (Shortcodes)

YouTube 영상

Twitter/X

GitHub Gist

알림 박스 (Blowfish Alert)

{{< alert “circle-info” >}} 정보 알림입니다. {{< /alert >}}

{{< alert “lightbulb” >}} 팁이나 아이디어입니다. {{< /alert >}}

{{< alert “triangle-exclamation” >}} 경고 메시지입니다. {{< /alert >}}

접기/펼치기 (Details)

클릭하여 펼치기

숨겨진 내용이 여기에 표시됩니다.

주석

수평선

위아래로 구분선을 만들 때 사용:

각주

텍스트에 각주¹를 추가할 수 있습니다.

그래프 차트

Mermaid 차트

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

Swatched (color showcase)

#64748b

#3b82f6

#06b6d4

TypeLt

(Ex1)

(Ex2)

(Ex3)

Youtube Lite

작성 팁:

Front matter의 draft: true를 false로 변경하면 배포됩니다
description과 summary를 작성하면 SEO에 도움이 됩니다
이미지는 포스트 폴더에 함께 넣는 것을 권장합니다

각주 내용입니다. ↩︎

Hugo & GithubPages 블로그로 넘어온 이유

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

왜 Hugo & GitHub Pages로 넘어왔는가?

기존 Tstory로 운영하였던 기술 블로그를 Hugo & GitHub Pages로 마이그레이션을 하기로 결심하게 되었다.

1. 흩어진 콘텐츠 관리의 어려움

여러가지 노트 툴을 사용하다보니 회사를 다니면서 또는 공부를 하면서 정리하는 글들이 중구난방하게 흩어지게 되었고 이걸 또 다시 블로그로 옮겨야 하는 번거로움이 생겨 블로그 관리를 소홀히 하게 되었다.

2. 마크다운 호환성 문제

기존 노트 툴에서 사용하는 마크다운 문법이 Tstory에서 글을 올릴때 완벽히 호환되지 않아 수정을 해야하는 일들이 자주 발생했었고 이 또한 번거로움이 생기는 일이였다.

특히 다음과 같은 문제들이 있었다:

코드 블록의 syntax highlighting 지원 부족
테이블 렌더링 오류
이미지 경로 처리 문제
수식 표현의 제한

3. Tstory Open API 지원 종료

마지막으로는 최근에 다시 그동안 공부한 자료들을 다시 정리해서 Tstory에 올릴겸 블로그 스킨도 다시 이쁘게 꾸미고 Tstory 공식 Open API를 활용하여 기존 노트 툴들과 연동하는 작업을 진행해보려 하였지만 Open API의 공식 지원이 종료 되어있었고 더이상 Tstory를 사용할 이유가 없어졌다.

블로그 플랫폼 선택 기준

여러 블로그를 참고하여 어떤 방식이 좋을지 고민을 많이 하였고 아래와 같이 기준점을 가지고 Hugo & GitHub Pages로 확정을 하게 되었다.

블로그를 구축하는게 쉬운가?
코드로 관리가 가능한가?
내가 원하는 기능을 추가하는 자유도가 높은가?
GitHub Pages를 사용해서 빌드하고 배포할때 속도가 빠른가?
Obsidian과 같은 노트 툴들과 연동하기 편한가?

Hugo란?

Hugo는 Go 언어로 작성된 빠르고 유연한 정적 사이트 생성기(Static Site Generator)이다.

주요 특징:

빠른 빌드 속도: 수천 개의 페이지도 몇 초 안에 빌드된다
단순한 구조: Markdown으로 콘텐츠를 작성하면 Hugo가 HTML로 변환해준다
제로 의존성: 단일 바이너리로 실행되며 별도의 런타임이나 데이터베이스가 필요없다
풍부한 테마 생태계: 다양한 용도의 테마를 쉽게 적용할 수 있다

GitHub Pages와 함께 사용되는 정적 사이트 생성기 비교

특징	Hugo	Jekyll	Gatsby	Next.js (SSG)	VuePress
언어	Go	Ruby	React (JavaScript)	React (JavaScript)	Vue.js
빌드 속도	⚡ 매우 빠름 (< 1ms/page)	🐢 느림	🚶 보통	🚶 보통	🚶 보통
설치 복잡도	✅ 단일 바이너리	⚠️ Ruby 환경 필요	⚠️ Node.js + 많은 의존성	⚠️ Node.js + 의존성	⚠️ Node.js + 의존성
GitHub Pages 기본 지원	❌ (Actions 필요)	✅ 네이티브 지원	❌ (Actions 필요)	❌ (Actions 필요)	❌ (Actions 필요)
학습 곡선	낮음	낮음	높음	중간-높음	중간
테마/플러그인	풍부	매우 풍부	풍부 (React 생태계)	풍부 (React 생태계)	보통
적합한 용도	블로그, 문서, 포트폴리오	블로그, GitHub 기본	복잡한 웹앱, 블로그	복잡한 웹앱, 하이브리드	기술 문서
빌드 시간 (1000 페이지)	~1초	~2분	~30초	~30초	~20초

Hugo를 선택한 이유:

압도적인 빌드 속도: 콘텐츠가 많아져도 빌드 시간이 거의 증가하지 않는다
간단한 설정: 복잡한 JavaScript 프레임워크 없이 Markdown에 집중할 수 있다
제로 의존성: 단일 실행 파일로 환경 설정 문제가 없다
풍부한 테마: Blowfish 같은 고품질 테마를 쉽게 적용할 수 있다

GitHub Pages 배포

Hugo로 작성한 블로그는 GitHub Actions를 통해 자동으로 빌드되고 배포된다.

배포 워크플로우

main 브랜치에 변경사항을 push한다
GitHub Actions가 자동으로 트리거된다
Hugo가 정적 사이트를 빌드한다
빌드된 파일이 GitHub Pages로 자동 배포된다

장점

자동화된 배포: 코드를 push하면 자동으로 배포가 진행된다
버전 관리: Git을 통해 모든 변경사항을 추적할 수 있다
무료 호스팅: GitHub Pages는 무료로 제공된다
커스텀 도메인: 원하는 도메인을 연결할 수 있다
HTTPS 지원: 기본적으로 HTTPS가 제공된다

Obsidian 연동

Hugo는 마크다운 기반이기 때문에 Obsidian과 같은 노트 툴과 완벽하게 호환된다.

연동 방법

Hugo 블로그의 content/posts 디렉토리를 Obsidian vault로 설정한다
Obsidian에서 글을 작성하고 편집한다
작성이 완료되면 Git을 통해 commit & push한다
GitHub Actions가 자동으로 빌드하고 배포한다

이점

일관된 작성 환경: 모든 노트와 블로그 글을 같은 툴에서 관리한다
완벽한 마크다운 호환: 추가 변환 작업이 필요없다
로컬 우선: 인터넷 없이도 글을 작성할 수 있다
강력한 링크 기능: Obsidian의 백링크와 그래프 뷰를 활용할 수 있다

기본적인 Hugo Terminal 명령어

개발 서버 실행

hugo server

로컬 개발 서버를 시작한다. 기본적으로 http://localhost:1313에서 사이트를 확인할 수 있다.

주요 옵션:

-D 또는 --buildDrafts: 초안(draft) 콘텐츠도 함께 빌드한다
--bind 0.0.0.0: 모든 네트워크 인터페이스에서 접근 가능하도록 설정한다
--port 8080: 기본 포트(1313) 대신 다른 포트를 사용한다
파일 변경 시 자동으로 브라우저가 새로고침된다 (Live Reload)

예시:

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

프로덕션 빌드

hugo --cleanDestinationDir

프로덕션용 정적 사이트를 빌드한다. public/ 디렉토리에 결과물이 생성된다.

주요 기능:

--cleanDestinationDir: 빌드 전에 대상 디렉토리(public/)를 완전히 정리한다
이전 빌드의 불필요한 파일을 제거하여 깨끗한 상태로 빌드를 수행한다
파일명이 변경되거나 삭제된 경우에도 이전 버전의 파일이 남아있지 않도록 보장한다

예시:

hugo --cleanDestinationDir
hugo --cleanDestinationDir --minify # 파일 최소화 옵션 추가

테마 정보

Hugo Blowfish Theme

이 블로그는 Blowfish 테마를 사용하고 있다.

특징:

현대적이고 반응형 디자인을 제공한다
다크 모드를 지원한다
빠른 로딩 속도와 SEO 최적화가 되어있다
다국어를 지원한다
풍부한 커스터마이징 옵션을 제공한다

설정 파일:

config/_default/hugo.toml - 기본 Hugo 설정
config/_default/params.toml - Blowfish 테마 파라미터
config/_default/languages.en.toml - 언어별 설정
config/_default/menus.en.toml - 메뉴 구성

마치며

Tstory에서 Hugo & GitHub Pages로의 마이그레이션은 개발자 친화적인 환경을 위한 선택이었다. 이제는 코드 버전 관리와 동일한 방식으로 블로그를 관리할 수 있게 되었고, Obsidian과의 완벽한 연동으로 노트 작성부터 블로그 포스팅까지 하나의 워크플로우로 통합할 수 있게 되었다.

무엇보다 Hugo의 빠른 빌드 속도와 GitHub Actions의 자동화된 배포는 글 작성에만 집중할 수 있게 해주었고, 더 이상 플랫폼의 제약에 얽매이지 않고 자유롭게 커스터마이징할 수 있게 되었다.

앞으로는 Tstory에 있던 기존 글들을 천천히 마이그레이션하면서 새로운 콘텐츠도 꾸준히 추가해 나갈 예정이다.

참고 자료

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/

Blog on 0AndWild_log

Giscus로 Hugo 블로그에 댓글 기능 추가하기

Giscus란?

주요 특징

Utterances와의 차이점

사전 준비

필요한 것

제약사항

1단계: GitHub Discussions 활성화

1.1 저장소 설정 페이지 이동

1.2 Discussions 활성화

1.3 확인

2단계: Giscus App 설치

2.1 Giscus GitHub App 설치

2.2 권한 확인

3단계: Giscus 설정 생성

3.1 Giscus 웹사이트 접속

3.2 저장소 연결

3.3 페이지 ↔️ Discussion 연결 방식

권장: pathname (경로명)

대안들:

3.4 Discussion 카테고리 선택

권장: Announcements

대안: General

3.5 기능 선택

반응 활성화

메타데이터 보내기

댓글 입력란 위치

느긋한 로딩

3.6 테마 선택

권장: preferred_color_scheme

대안:

3.7 언어 설정

4단계: 생성된 코드 복사

4.1 스크립트 복사

4.2 중요한 값들

5단계: Blowfish 테마에 통합

5.1 디렉토리 생성

5.2 comments.html 파일 생성

5.3 Giscus 코드 삽입

5.4 params.toml 설정

6단계: 로컬 테스트

6.1 Hugo 서버 실행

6.2 브라우저에서 확인

6.3 테스트 댓글 작성

6.4 GitHub Discussions 확인

7단계: 배포

7.1 Git에 커밋

7.2 GitHub에 푸시

7.3 GitHub Actions 확인

7.4 배포된 사이트 확인

고급 설정

다크모드 및 언어 동적 설정 (권장)

완전한 동적 설정

동작 방식 설명

1. 언어 동적 설정

2. 다크모드 동적 설정

3. 언어별 댓글 통합

4. 실시간 테마 변경 감지

테스트 방법

테마 옵션 변경

정적 테마 설정 (간단한 방법)

포스트별 댓글 숨기기

카테고리별 댓글 분리

문제 해결

댓글 위젯이 표시되지 않음

원인 1: Discussions 미활성화

원인 2: Giscus App 미설치

원인 3: 저장소 ID 오류

원인 4: showComments 설정 누락

로그인 버튼만 보이고 댓글 못 씀

원인: GitHub OAuth 승인 필요

댓글이 저장되지 않음

원인: 저장소 권한 문제

다크모드가 동기화 안 됨

해결: JavaScript 동기화 코드 추가

Giscus 관리

댓글 관리

GitHub Discussions에서 관리

스팸 댓글 처리

권장: `pathname` (경로명)

권장: `Announcements`

대안: `General`

권장: `preferred_color_scheme`