정적 블로그에 댓글 시스템 도입하기 (Giscus 편)

공부하게 된 계기

Next.js로 직접 만든 블로그에 댓글을 붙이려는데, 백엔드/DB를 새로 만들고 싶진 않았다. 선택지를 좁혀보면 보통 셋 중 하나다.

Disqus — 가장 유명하지만 광고/트래킹 + 800KB 넘는 번들로 LCP가 나빠진다.
Utterances — GitHub Issues 기반. 가볍지만 리액션이 없고 운영 추적이 불편.
Giscus — GitHub Discussions 기반. 무료, 광고 없음, 다크모드 자동, 리액션/이모지 지원.

이번 편은 Giscus를 고른 뒤 코드를 짜기 전에 GitHub 쪽에서 끝내야 하는 사전 설정을 정리한다. 이 단계만 끝내면 다음 편에서 컴포넌트 한 개로 댓글이 동작하게 만들 수 있다.

💡

대상 리포는 댓글이 저장될 리포다. 블로그 코드와 같은 리포여도 되고, 댓글 전용 리포를 따로 파도 된다. 이 글에서는 seongyeon1/seongyeon1.github.io를 예시로 사용한다.

사전 체크리스트

작업을 시작하기 전에 다음 두 가지가 만족돼야 한다.

리포가 public — Giscus는 public 리포에서만 동작한다.
본인이 리포 admin — Discussions 활성화와 앱 설치 권한이 필요하다.

1단계 — Discussions 활성화

리포 페이지 → 우상단 Settings
좌측 사이드바 General (기본 선택)
아래로 스크롤 → Features 섹션
Discussions 체크박스 → Set up discussions 클릭
안내 페이지가 뜨면 그대로 Start discussion (welcome 글이 자동 생성된다)

GitHub 리포 Settings → General → Features 섹션, Discussions 체크박스가 강조됨 — Settings → General → Features 맨 아래쯤에 Discussions 체크박스가 있다. 체크하면 Set up discussions 버튼이 나온다.

리포 상단 탭에 Discussions가 추가되면 성공이다.

✅

welcome 글은 그냥 두거나, 처음 인사말로 본인 페이지 가이드를 적어둬도 된다. 나중에 카테고리 정리할 때 General로 자동 분류된다.

2단계 — Announcement 타입 카테고리 준비

여기가 가장 자주 빼먹는 단계다. Discussions를 댓글 저장소로 쓰려면 Announcement 타입 카테고리가 필요하다.

Announcement 타입의 카테고리는 maintainer만 새 토론을 만들 수 있다. 즉 일반 사용자는 새 토론(=새 글)을 못 만들지만, Giscus가 페이지마다 자동으로 생성한 토론에 댓글은 달 수 있다. 이래야 댓글 저장소가 무한 생성된 빈 토론으로 어지럽혀지지 않는다.

GitHub은 Discussions를 켜면 Announcements라는 Announcement 타입 카테고리를 기본 제공한다. 그래서 두 가지 선택지가 있다.

A. 기본 Announcements 그대로 쓰기 (간단, 추천) 별도 작업 없이 바로 다음 단계로 넘어가면 된다. 이 글에서도 이 방식을 사용한다.

B. 댓글 전용 카테고리 따로 만들기 운영상 댓글과 공지를 분리하고 싶을 때.

리포 → Discussions 탭
좌측 사이드바 카테고리 목록 옆 ✏️ (Edit) 또는 우측 Categories 링크
New category 클릭
입력값:
- Category name: Comments (또는 원하는 이름)
- Description: Blog post comments
- Discussion Format: Announcement 선택 ← 중요
- 아이콘: 💬 추천
Create

3단계 — Giscus GitHub App 설치

브라우저로 github.com/apps/giscus 접속
Install 클릭
계정/조직 선택
Only select repositories 선택 → 댓글을 저장할 리포 체크
Install

⚠️

All repositories를 고르지 말 것. 다른 리포에까지 권한이 열린다. Only select repositories로 댓글용 리포 하나만 허용하는 게 안전하다.

giscus GitHub App 설치 화면, Only select repositories 선택 후 댓글용 리포 하나만 추가한 상태 — Repository access에서 Only select repositories → Select repositories로 댓글 저장용 리포 하나만 추가하고 Save. 권한은 metadata 읽기 + discussions 읽기/쓰기뿐이다.

4단계 — 설정값 받아오기

이제 컴포넌트에 박을 두 개의 ID를 받아올 차례다. 그런데 왜 이 단계가 따로 필요할까?

1) giscus 클라이언트는 사람이 읽는 이름이 아니라 node ID로 동작한다. 우리가 아는 seongyeon1/seongyeon1.github.io나 Announcements 같은 문자열은 GitHub UI용 라벨이고, giscus가 런타임에 GitHub GraphQL API를 호출할 때 실제로 쓰는 건 R_kgDO..., DIC_kwDO... 형태의 불투명한 node ID다. 이 ID는 추측하거나 손으로 만들 수 없고, GitHub에 조회해야만 나온다. giscus.app이 그 조회를 대신 해주는 도구다.

2) node ID는 이름이 바뀌어도 안 변한다. 리포 이름이나 카테고리 이름을 나중에 바꿔도 ID는 그대로라서, ID로 박아두면 이름 변경에 댓글이 끊기지 않는다. 반대로 말하면 — 이름만 보고 박으면 안 되는 이유이기도 하다.

3) 1~3단계가 제대로 됐는지 한 곳에서 검증된다. 소유자/리포명을 입력하면 giscus.app이 그 자리에서 ① 리포가 public인지 ② giscus 앱이 설치됐는지 ③ Discussions가 켜져 있는지를 확인해 초록 체크 3개로 보여준다. 하나라도 빨간색이면 앞 단계 중 뭔가 빠진 것이니, ID를 받기 전에 여기서 먼저 걸러진다.

정리하면 이 단계는 "앞의 세 단계를 한 번에 점검 + 컴포넌트에 박을 불투명 ID 2개 수령" 을 동시에 하는 관문이다.

giscus.app 접속 → 우상단에서 한국어 전환
저장소 입력란에 소유자/리포명 형식으로 입력 (예: seongyeon1/seongyeon1.github.io)
아래에 초록 체크 3개가 떠야 한다:
- ✅ 저장소가 존재하고 public
- ✅ giscus 앱이 설치됨
- ✅ Discussions 활성화됨
페이지 ↔️ Discussions 연결 → pathname 선택 (URL 경로별로 토론 1개)
Discussion 카테고리 → Announcements 선택 (또는 직접 만든 Announcement 타입 카테고리)
페이지 하단 <script> 블록에서 두 값을 메모

giscus.app이 생성해주는 스크립트

<script src="https://giscus.app/client.js"
        data-repo="seongyeon1/seongyeon1.github.io"
        data-repo-id="R_kgDOSX5tLA"
        data-category="Announcements"
        data-category-id="DIC_kwDOSX5tLM4C8sKD"
        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>

이 두 값(data-repo-id, data-category-id)은 공개돼도 괜찮은 값이다. 환경변수로 숨길 필요 없이 컴포넌트에 그대로 박아도 된다.

매핑 전략 비교

data-mapping은 어떤 값을 토론 키로 쓸지 결정한다.

값	동작	추천 상황
`pathname`	URL 경로별 1 토론	블로그 (추천) — slug가 그대로 키
`url`	전체 URL	도메인이 자주 바뀌면 안 좋음
`title`	페이지 `<title>`	제목 바꾸면 댓글 끊김
`og:title`	OG 메타 제목	동상
`specific`	직접 지정	경로가 안 정해진 동적 페이지

pathname을 선택하면 /blog/2026-05-10-... 같은 slug 기반 키가 생긴다. 나중에 슬러그를 바꾸면 댓글이 새 토론으로 분리되니 주의.

다음 편 예고

이 시리즈는 "블로그 만들기"다. 댓글까지 붙였으니 다음은 검색 노출 차례 — 구글에 내 블로그(GitHub Pages)가 검색되도록 등록하는 작업이다.

배포만 한다고 구글이 알아서 잘 긁어가는 건 아니다. 사이트맵을 알려주고, 소유권을 증명하고, 색인 상태를 들여다보려면 Google Search Console 등록이 필요하다.

다음 편에서는:

Search Console 속성 추가 — URL 접두어 vs 도메인 방식 차이와, GitHub Pages 커스텀 도메인에 맞는 선택
소유권 확인 — HTML 파일 업로드 / <meta> 태그 / DNS TXT 중 정적 블로그에 가장 깔끔한 방법
sitemap.xml 제출 (Next.js app/sitemap.ts로 자동 생성한 것을 그대로)
robots.txt에 사이트맵 위치 명시해서 크롤러에게 한 번 더 알려주기
URL 검사 도구로 색인 요청하고 "Google에 등록됨"으로 바뀌는지 확인
며칠 뒤 site:내도메인 검색으로 실제 노출 확인

까지 다룬다. 한 번 등록해두면 그다음부터는 글만 올리면 알아서 색인된다.

Comments