정적 사이트에서 동적 댓글 시스템 만들기: Giscus + GraphQL API

<!-- 이렇게 보입니다 -->
2026년 1월 12일 · 5분 · Isaac · 3 댓글

query($owner: String!, $repo: String!, $categoryId: ID!) {
  repository(owner: $owner, name: $repo) {
    discussions(first: 50, categoryId: $categoryId, orderBy: {field: UPDATED_AT, direction: DESC}) {
      nodes {
        title
        url
        comments(last: 10) {
          totalCount
          nodes {
            author {
              login
              url
              avatarUrl
            }
            body
            bodyText
            createdAt
            url
          }
        }
      }
    }
  }
}

# .env
GITHUB_TOKEN=github_pat_여기에_실제_토큰_붙여넣기

# config.yaml
security:
  funcs:
    getenv:
      - ^HUGO_
      - ^CI$
      - ^GITHUB_TOKEN$

{{- if getenv "GITHUB_TOKEN" -}}
<meta name="github-token" content="{{ getenv "GITHUB_TOKEN" }}">
{{- else if site.Params.githubToken -}}
<meta name="github-token" content="{{ site.Params.githubToken }}">
{{- end -}}

<!-- layouts/partials/extend_head.html -->
{{- partial "github-token.html" . -}}

# .gitignore
# Environment variables (contains secrets)
.env
.env.local
.env.*.local

# .env 파일이 있는 디렉토리에서 실행하세요
hugo server

# 아니면 이렇게 직접 환경 변수 전달
GITHUB_TOKEN=your_token_here hugo server

git commit --allow-empty -m "Trigger rebuild for environment variables"
git push

const GITHUB_TOKEN = document.querySelector('meta[name="github-token"]')?.content || '';

async function fetchCommentCounts() {
  const query = `
    query($owner: String!, $repo: String!, $categoryId: ID!) {
      repository(owner: $owner, name: $repo) {
        discussions(first: 50, categoryId: $categoryId) {
          nodes {
            title
            comments {
              totalCount
            }
          }
        }
      }
    }
  `;

  const headers = {
    'Content-Type': 'application/json',
  };

  if (GITHUB_TOKEN) {
    headers['Authorization'] = `Bearer ${GITHUB_TOKEN}`;
  }

  const response = await fetch('https://api.github.com/graphql', {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({
      query,
      variables: {
        owner: 'codeslog',
        repo: 'codeslog-comments',
        categoryId: 'DIC_kwDOP13p-c4Cv1Rv'
      }
    })
  });

  const result = await response.json();

  // 댓글 수를 giscus_term으로 매핑
  const counts = {};
  result.data.repository.discussions.nodes.forEach(discussion => {
    counts[discussion.title] = discussion.comments.totalCount;
  });

  return counts;
}

const CACHE_KEY = 'codeslog_comment_counts';
const CACHE_DURATION = 1000 * 60 * 5; // 5분

function getCachedData() {
  try {
    const cached = localStorage.getItem(CACHE_KEY);
    if (!cached) return null;

    const data = JSON.parse(cached);
    const now = Date.now();

    if (now - data.timestamp < CACHE_DURATION) {
      return data.counts;
    }
  } catch (e) {
    console.warn('Failed to read cache:', e);
  }
  return null;
}

function setCachedData(counts) {
  try {
    localStorage.setItem(CACHE_KEY, JSON.stringify({
      timestamp: Date.now(),
      counts: counts
    }));
  } catch (e) {
    console.warn('Failed to save cache:', e);
  }
}

async function init() {
  // 캐시가 있으면 먼저 보여줘요
  const cached = getCachedData();
  if (cached) {
    updateCommentCounts(cached);

    // 백그라운드에서 새 데이터 가져오기
    fetchCommentCounts().then(counts => {
      setCachedData(counts);
      updateCommentCounts(counts);
    }).catch(error => {
      console.error('Background update failed:', error);
    });

    return;
  }

  // 캐시가 없으면 새로 가져와요
  try {
    const counts = await fetchCommentCounts();
    setCachedData(counts);
    updateCommentCounts(counts);
  } catch (error) {
    console.error('Failed to fetch:', error);
  }
}

{{- with ($scratch.Get "meta") }}
{{- delimit . " · " | safeHTML -}}
{{- end -}}

{{- if (.Param "giscus_term") -}}
<span class='comment-count-wrapper'
      data-giscus-term='{{ .Param "giscus_term" }}'
      data-lang='{{ .Lang }}'
      style='display:none;'>
</span>
{{- end -}}

function updateCommentCounts(counts) {
  const elements = document.querySelectorAll('.comment-count-wrapper');

  elements.forEach(element => {
    const term = element.getAttribute('data-giscus-term');
    const lang = element.getAttribute('data-lang') || 'ko';
    const count = counts[term];

    if (count !== undefined && count > 0) {
      const commentLabel = lang === 'ko' ? '댓글' : 'comments';
      const commentLabelSR = lang === 'ko' ? '댓글 수' : 'comment count';

      // separator와 함께 출력
      element.innerHTML = `&nbsp;·&nbsp;<span><span class='sr-only'>${commentLabelSR}: </span><span class='comment-count' aria-live='polite'>${count}</span> ${commentLabel}</span>`;
      element.style.display = '';
    }
  });
}

{{- if and (.Site.Params.comments) (ne .Params.comments false) (.Params.giscus_term) -}}
<div id="comments" class="giscus-container">
    <script src="https://giscus.app/client.js" ...>
    </script>
</div>
{{- end -}}

// recent-comments.js에서
const postUrl = `${langPrefix}/posts/${slug}/#comments`;

/* 댓글 카드 스타일 */
.recent-comment-item {
  border: 1px solid var(--border);
  border-radius: 8px;
  overflow: hidden;
  transition: all 0.2s ease;
}

.recent-comment-item:hover {
  border-color: var(--primary);
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

/* 링크 명도 대비 개선 */
.recent-comment-link {
  color: var(--primary);  /* 더 진한 색상 */
  font-weight: 600;  /* 더 두꺼운 글씨 */
  text-decoration: none;
}

.recent-comment-link:hover {
  color: var(--tertiary);
  text-decoration: underline;  /* 호버 시 밑줄 */
}

<!-- 로딩 상태 -->
<div class="recent-comments-loading"
     aria-live="polite"
     aria-busy="true">
  댓글을 불러오는 중...
</div>

<!-- 댓글 목록 -->
<ul class="recent-comments-list" role="list">
  <!-- 댓글 항목들 -->
</ul>

<!-- 오류 상태 -->
<div class="recent-comments-error"
     role="alert"
     style="display: none;">
  댓글을 불러오는 데 실패했습니다.
</div>

<span>
  <span class='sr-only'>댓글 수: </span>
  <span class='comment-count' aria-live='polite'>3</span>
  댓글
</span>

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

.recent-comment-link:focus {
  outline: 2px solid var(--tertiary);
  outline-offset: 2px;
  border-radius: 2px;
}

<a href="/posts/slug/#comments"
   aria-label="게시글로 이동">
  게시글 보기 →
</a>

// 캐시 히트: 0ms (즉시!)
// 백그라운드 업데이트: ~300ms (사용자는 안 기다려요)

<script src="/js/comment-counts.js" defer></script>
<script src="/js/recent-comments.js" defer></script>
<script src="/js/all-comments.js" defer></script>

// 각 포스트마다 개별 API 호출
posts.forEach(post => {
  fetch(`/api/comments/${post.id}`);
});

// 단일 요청으로 모든 데이터 가져오기
const allDiscussions = await fetchAllDiscussions();
const countMap = buildCountMap(allDiscussions);

// 댓글이 없으면 DOM 조작하지 않습니다
if (count !== undefined && count > 0) {
  element.innerHTML = `...`;
  element.style.display = '';
}

Error: access denied: "GITHUB_TOKEN" is not whitelisted in policy "security.funcs.getenv"

# config.yaml
security:
  funcs:
    getenv:
      - ^GITHUB_TOKEN$

[Comment Counts] Found 0 comment count elements

git commit --allow-empty -m "Trigger rebuild"
git push

{
  "message": "API rate limit exceeded"
}

// 이렇게 구현할 수 있을 거예요
const eventSource = new EventSource('/api/comments/stream');
eventSource.onmessage = (event) => {
  const newComment = JSON.parse(event.data);
  updateUI(newComment);
};

function searchComments(query) {
  return allComments.filter(comment =>
    comment.bodyText.toLowerCase().includes(query.toLowerCase())
  );
}

comments(last: 100) {
  totalCount
  nodes {
    replies(last: 100) {
      totalCount
    }
  }
}