<div id="readability-page-1" class="page"><div>

                <a href="https://daeho.ro/tag/notion/">Notion</a>
            
                <p>Giscus는 GitHub의 리포지토리에 존재하는 Discussion 기능을 통해서 웹사이트의 코멘트를 관리할 수 있게 도와주는 위젯으로, Notion 블로그에 이를 추가하는 방법에 대해서 알아본다.</p>

            <div>
                <p><a href="/author/daeho/">
                                <img src="https://www.gravatar.com/avatar/beeffd01d83b25e78b0450875fc3a2c4?s=250&amp;r=x&amp;d=mp" alt="Daeho Ro">
                            </a>
                </p>
                <div>
                    
                    <p><time datetime="2025-02-22">2025년 02월 22일</time>
                            <span><span>—</span> 6 min read</span>
                    </p>
                </div>
            </div>

                <figure>
        <img sizes="(max-width: 1200px) 100vw, 1120px" src="https://images.unsplash.com/photo-1519337265831-281ec6cc8514?crop=entropy&amp;cs=tinysrgb&amp;fit=max&amp;fm=jpg&amp;ixid=M3wxMTc3M3wwfDF8c2VhcmNofDV8fGJsb2d8ZW58MHx8fHwxNzczNDc4NzYwfDA&amp;ixlib=rb-4.1.0&amp;q=80&amp;w=1200" alt="Notion 블로그에 Giscus 추가하기">
            <figcaption><span>Photo by </span><a href="https://unsplash.com/@heyquilia?utm_source=ghost&amp;utm_medium=referral&amp;utm_campaign=api-credit"><span>Kenny Eliason</span></a><span> / </span><a href="https://unsplash.com/?utm_source=ghost&amp;utm_medium=referral&amp;utm_campaign=api-credit"><span>Unsplash</span></a></figcaption>
    </figure>

        </div><section>
            <h2 id="%EA%B0%9C%EC%9A%94">개요</h2><p><code>Giscus</code>는 GitHub의 리포지토리에 존재하는 Discussion 기능을 통해서 웹사이트의 코멘트를 관리할 수 있게 도와주는 위젯이다.</p><figure><a href="https://giscus.app/ko?ref=daeho.ro"><div><p>giscus</p><p>A comments widget built on GitHub Discussions.</p><p><img src="https://daeho.ro/content/images/icon/apple-touch-icon.png" alt=""><span>giscus</span></p></div><p><img src="https://daeho.ro/content/images/thumbnail/giscus" alt="" onerror="this.style.display = 'none'"></p></a></figure><p>일반적으로 데이터베이스를 별도로 두지 않고 코멘트를 관리하기 위해서 자체 제작된 블로그에서 주로 사용된다. 노션을 이용한 블로그의 경우에는 노션 문서 내부의 자체 댓글 기능을 사용할 수도 있지만, 외부 사용자를 정확하게 매핑할 수 없기 때문에 <code>Giscus</code>를 쓰는게 관리 측면에서는 좀 더 깔끔한 것 같다.</p><h2 id="%EC%84%A4%EC%A0%95">설정</h2><p><code>Giscus</code>를 설정하기 전에 먼저 GitHub에서 여러 설정을 진행해야 한다.</p><h2 id="%EC%95%B1-%EC%B6%94%EA%B0%80">앱 추가</h2><p>다음 링크를 통해서 <code>Giscus</code> 앱을 추가하도록 하자. 설정 과정에서 리포지토리 액세스를 추가해야 하는데, 가급적이면 선별적으로 노션 블로그에 대해서만 권한을 추가하는 것이 안전하다.</p><ul><li><a href="https://github.com/apps/giscus?ref=daeho.ro">https://github.com/apps/giscus</a></li></ul><figure><img src="https://daeho.ro/content/images/2026/03/image-52.png" alt="" loading="lazy" width="2000" height="2150" sizes="(min-width: 720px) 720px"></figure><h2 id="discussion-%ED%99%9C%EC%84%B1%ED%99%94">Discussion 활성화</h2><p>댓글 기능이 리포지토리의 Discussion을 통해서 제공되기 때문에, 리포지토리 설정에서 Discussion을 활성화 해야한다.</p><figure><img src="https://daeho.ro/content/images/2026/03/image-53.png" alt="" loading="lazy" width="2000" height="1893" sizes="(min-width: 720px) 720px"><figcaption><span>Repository &gt; Settings</span></figcaption></figure><p>그러면 Discussion 메뉴가 활성화되는데, 이제 여기에 들어가서 댓글 타입을 생성해주도록 하자.</p><figure><img src="https://daeho.ro/content/images/2026/03/image-54.png" alt="" loading="lazy" width="2000" height="877" sizes="(min-width: 720px) 720px"><figcaption><span>Discussion &gt; Categories</span></figcaption></figure><figure><img src="https://daeho.ro/content/images/2026/03/image-55.png" alt="" loading="lazy" width="2000" height="1901" sizes="(min-width: 720px) 720px"><figcaption><span>Create category</span></figcaption></figure><p>GitHub의 설정은 이렇게 마무리되었다.</p><h2 id="giscus-%EC%84%A4%EC%A0%95">Giscus 설정</h2><p>다시 Giscus 홈페이지로 돌아가서 차례대로 필요한 항목들을 입력해보자.</p><figure><img src="https://daeho.ro/content/images/2026/03/image-56.png" alt="" loading="lazy" width="2000" height="1073" sizes="(min-width: 720px) 720px"><figcaption><span>Repository</span></figcaption></figure><figure><img src="https://daeho.ro/content/images/2026/03/image-57.png" alt="" loading="lazy" width="2000" height="1426" sizes="(min-width: 720px) 720px"><figcaption><span>Connection</span></figcaption></figure><figure><img src="https://daeho.ro/content/images/2026/03/image-58.png" alt="" loading="lazy" width="2000" height="734" sizes="(min-width: 720px) 720px"><figcaption><span>Category</span></figcaption></figure><p>그 외의 설정은 편한대로 작성한다. 왜냐하면, 하단에서 자동 제공해주는 스크립트를 사용하진 않기 때문이다. 다만, 제공된 몇몇 값들을 따로 잘 적어둔다.</p><pre><code>&lt;script src="&lt;https://giscus.app/client.js&gt;"
        data-repo="daeho-ro/notion-blog"
        data-repo-id="R_kgDOMk39yQ"
        data-category="Comments"
        data-category-id="DIC_kwDOMk39yc4ChwCQ"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="light_tritanopia"
        data-lang="ko"
        crossorigin="anonymous"
        async&gt;
&lt;/script&gt;
</code></pre><h2 id="%EC%BD%94%EB%93%9C-%EC%88%98%EC%A0%95">코드 수정</h2><p>이제 설정된 <code>Giscus</code>의 코드를 반영하기 위해서 블로그 소스를 수정해야 한다. 다음 커밋을 참고하여 필요한 위치들을 수정한다. 애초에 블로그 템플릿 포크 자체를 여기서 하는것도 나쁘진 않을지도…?</p><figure><a href="https://github.com/daeho-ro/notion-blog/commit/2e281769674f3c6943b83602c0dac2886ac124e3?ref=daeho.ro"><div><p>feature: add giscus · daeho-ro/notion-blog@2e28176</p><p>Notion Blog. Contribute to daeho-ro/notion-blog development by creating an account on GitHub.</p><p><img src="https://daeho.ro/content/images/icon/pinned-octocat-093da3e6fa40-3.svg" alt=""><span>GitHub</span><span>daeho-ro</span></p></div><p><img src="https://daeho.ro/content/images/thumbnail/2e281769674f3c6943b83602c0dac2886ac124e3" alt="" onerror="this.style.display = 'none'"></p></a></figure><p>잘 보면 주의해야 할 코드가 몇 군데 보인다.</p><ol><li>Comment.tsx<ul><li>설정 기본값들이 하드코딩 되어있다.</li><li>수정해도 되지만, 옵션을 제공하는 곳에서 필요한 옵션으로 오버라이드 하는 것이 더 안전하다.</li></ul></li><li>giscus.json<ul><li>외부에서 코멘트를 달 수 없도록 허용할 도메인을 명시해야 하므로 반드시 수정해야 한다.</li></ul></li><li>site.config.ts<ul><li><code>Giscus</code> 설정값을 제공하고 있다.</li><li>위에서 얻어온 스크립트와 옵션을 매칭하여 적절한 값으로 모두 변경한다.</li><li>설정값에 키가 없는 옵션을 변경하고자 한다면 직접 입력하면 된다.<ul><li>예를 들어, <code>data-input-position="bottom"</code> 코드에 대응하는 옵션 <code>inputPosition</code> 키는 따로 설정하지 않았는데, 필요하면 해당 키를 입력하고 값에 <code>'bottom'</code> 을 입력해주면 된다.</li></ul></li></ul></li><li>package.json<ul><li><code>@giscus/react</code> 컴포넌트를 설치했는데, <code>pnpm</code>을 이용해야 한다.</li><li>컴포넌트를 설치하지 않고 변경사항만 따라가면, 로컬에서는 동작을 확인할 수 없지만 배포시엔 정상 동작할 것이다.</li></ul></li></ol><p>특이사항으로, <code>Giscus</code> 컴포넌트를 확장하여 테마를 2개 입력하도록 되어있다. 설정 페이지에서 Light, Dark 테마 2개를 골라서 각각 입력하면 된다.</p><h2 id="%EB%A7%88%EB%AC%B4%EB%A6%AC">마무리</h2><p>모든 설정이 완료되었고, 배포가 진행되고 나면 블로그에서 코멘트 블럭을 확인할 수 있다.</p><figure><img src="https://daeho.ro/content/images/2026/03/image-59.png" alt="" loading="lazy" width="2000" height="1237" sizes="(min-width: 720px) 720px"><figcaption><span>Comment block</span></figcaption></figure><p>코멘트를 남기면, 해당 글의 경로에 해당하는 값을 제목으로 가지는 Discussion이 생성된다. 그리고 코멘트는 해당 Discussion 내부에 남게 되는데, 같은 API를 사용하기 때문에 대댓글을 남기고 싶다면 블로그에서 직접 남기거나 Discussion 내부에서 답변을 제공하면 동일하게 동작한다.</p><figure><img src="https://daeho.ro/content/images/2026/03/image-60.png" alt="" loading="lazy" width="2000" height="599" sizes="(min-width: 720px) 720px"><figcaption><span>Discussion</span></figcaption></figure><figure><img src="https://daeho.ro/content/images/2026/03/image-61.png" alt="" loading="lazy" width="2000" height="676" sizes="(min-width: 720px) 720px"><figcaption><span>댓글로 작성하면 with giscus 표시가 남는다.</span></figcaption></figure><h2 id="%EC%A3%BC%EC%9D%98%EC%82%AC%ED%95%AD">주의사항</h2><p>노션 블로그는 별도로 Slug를 입력하지 않으면 글의 제목을 이용하여 경로를 생성하게 된다. 이 때, 글의 제목이 한글이라면 경로도 한글로 생성되는데, url 처리를 진행하고 나면 한글이 아니라 복잡한 코드만 남게 된다. 그러면 Discussion에서도 코드로만 된 제목이 남게 되기 때문에, 나중에 어떤 글에 의해서 생성된 Discussion인지 알기가 매우 어렵게 된다.</p><p>그러므로 노션 블로그를 작성하면서 한글 제목을 사용한다면 반드시 별도의 Slug 프로퍼티를 제공하여 영문으로 된 경로를 제공해야 문제 없이 <code>Giscus</code> 댓글 기능을 이용할 수 있다.</p>
        </section></div>

Lamanus' Archive

개요
Giscus는 GitHub의 리포지토리에 존재하는 Discussion 기능을 통해서 웹사이트의 코멘트를 관리할 수 있게 도와주는 위젯이다.
일반적으로 데이터베이스를 별도로 두지 않고 코멘트를 관리하기 위해서 자체 제작된 블로그에서 주로 사용된다. 노션을 이용한 블로그의 경우에는 노션 문서 내부의 자체 댓글 기능을 사용할 수도 있지만, 외부 사용자를 정확하게 매핑할 수 없기 때문에 Giscus를 쓰는게 관리 측면에서는 좀 더 깔끔한 것 같다.
설정
Giscus를 설정하기 전에 먼저 GitHub에서 여러 설정을 진행해야 한다.
앱 추가
다음 링크를 통해서 Giscus 앱을 추가하도록 하자. 설정 과정에서 리포지토리 액세스를 추가해야 하는데, 가급적이면 선별적으로 노션 블로그에 대해서만 권한을 추가하는 것이 안전하다.
https://github.com/apps/giscus
Discussion 활성화
댓글 기능이 리포지토리의 Discussion을 통해서 제공되기 때문에, 리포지토리 설정에서 Discussion을 활성화 해야한다.
그러면 Discussion 메뉴가 활성화되는데, 이제 여기에 들어가서 댓글 타입을 생성해주도록 하자.
GitHub의 설정은 이렇게 마무리되었다.
Giscus 설정
다시 Giscus 홈페이지로 돌아가서 차례대로 필요한 항목들을 입력해보자.
그 외의 설정은 편한대로 작성한다. 왜냐하면, 하단에서 자동 제공해주는 스크립트를 사용하진 않기 때문이다. 다만, 제공된 몇몇 값들을 따로 잘 적어둔다.
<script src="<https://giscus.app/client.js>"
        data-repo="daeho-ro/notion-blog"
        data-repo-id="R_kgDOMk39yQ"
        data-category="Comments"
        data-category-id="DIC_kwDOMk39yc4ChwCQ"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="light_tritanopia"
        data-lang="ko"
        crossorigin="anonymous"
        async>
</script>
코드 수정
이제 설정된 Giscus의 코드를 반영하기 위해서 블로그 소스를 수정해야 한다. 다음 커밋을 참고하여 필요한 위치들을 수정한다. 애초에 블로그 템플릿 포크 자체를 여기서 하는것도 나쁘진 않을지도…?
잘 보면 주의해야 할 코드가 몇 군데 보인다.
Comment.tsx
설정 기본값들이 하드코딩 되어있다.
수정해도 되지만, 옵션을 제공하는 곳에서 필요한 옵션으로 오버라이드 하는 것이 더 안전하다.
giscus.json
외부에서 코멘트를 달 수 없도록 허용할 도메인을 명시해야 하므로 반드시 수정해야 한다.
site.config.ts
Giscus 설정값을 제공하고 있다.
위에서 얻어온 스크립트와 옵션을 매칭하여 적절한 값으로 모두 변경한다.
설정값에 키가 없는 옵션을 변경하고자 한다면 직접 입력하면 된다.
예를 들어, data-input-position="bottom" 코드에 대응하는 옵션 inputPosition 키는 따로 설정하지 않았는데, 필요하면 해당 키를 입력하고 값에 'bottom' 을 입력해주면 된다.
package.json
@giscus/react 컴포넌트를 설치했는데, pnpm을 이용해야 한다.
컴포넌트를 설치하지 않고 변경사항만 따라가면, 로컬에서는 동작을 확인할 수 없지만 배포시엔 정상 동작할 것이다.
특이사항으로, Giscus 컴포넌트를 확장하여 테마를 2개 입력하도록 되어있다. 설정 페이지에서 Light, Dark 테마 2개를 골라서 각각 입력하면 된다.
마무리
모든 설정이 완료되었고, 배포가 진행되고 나면 블로그에서 코멘트 블럭을 확인할 수 있다.
코멘트를 남기면, 해당 글의 경로에 해당하는 값을 제목으로 가지는 Discussion이 생성된다. 그리고 코멘트는 해당 Discussion 내부에 남게 되는데, 같은 API를 사용하기 때문에 대댓글을 남기고 싶다면 블로그에서 직접 남기거나 Discussion 내부에서 답변을 제공하면 동일하게 동작한다.
주의사항
노션 블로그는 별도로 Slug를 입력하지 않으면 글의 제목을 이용하여 경로를 생성하게 된다. 이 때, 글의 제목이 한글이라면 경로도 한글로 생성되는데, url 처리를 진행하고 나면 한글이 아니라 복잡한 코드만 남게 된다. 그러면 Discussion에서도 코드로만 된 제목이 남게 되기 때문에, 나중에 어떤 글에 의해서 생성된 Discussion인지 알기가 매우 어렵게 된다.
그러므로 노션 블로그를 작성하면서 한글 제목을 사용한다면 반드시 별도의 Slug 프로퍼티를 제공하여 영문으로 된 경로를 제공해야 문제 없이 Giscus 댓글 기능을 이용할 수 있다.