ghost-giscus-plugin 미리보기
이 페이지의 댓글은 기본값에 따라 이 플러그인이 본문 바로 뒤에 놓은 것입니다. 왼쪽 패널에서 위치와 여백, 그리고 구독자용 댓글 영역의 유무를 바꾸면 실제 댓글이 그에 맞게 움직입니다.
들어가며
giscus는 페이지에 giscus 클래스를 가진 요소가 있으면 그 안에 댓글을 마운트합니다. 이 플러그인은 그 요소를 원하는 위치에 만들어 주기만 합니다. 댓글의 실제 동작과 저장소는 여전히 giscus와 GitHub Discussions가 담당하므로, 무엇도 새로 구현하지 않습니다.
설치 방법
Ghost라면 설정의 코드 인젝션 사이트 푸터에 아래 두 스크립트를 넣습니다. 첫 번째가 이 플러그인, 두 번째가 공식 giscus 태그입니다.
<script src="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-giscus-plugin@1/giscus-mount.min.js"
data-target=".gh-content"
data-place="after"
data-class="gh-comments gh-canvas"
data-padding-bottom="48"></script>
<script src="https://giscus.app/client.js"
data-repo="[YOUR REPO]"
data-repo-id="[REPO ID]"
data-category="[CATEGORY]"
data-category-id="[CATEGORY ID]"
data-mapping="pathname"
data-theme="preferred_color_scheme"
crossorigin="anonymous"
async></script>순서가 중요합니다
이 플러그인 스크립트는 반드시 giscus 스크립트보다 먼저 나와야 합니다. giscus는 실행되는 순간에 giscus 요소가 있는지 보고 위치를 확정하기 때문에, 우리 스크립트가 먼저 그 자리를 만들어 두어야 합니다. 순서가 뒤바뀌면 댓글이 스크립트 태그 자리에 붙어 버립니다.
옵션 설정
동작은 모두 스크립트 태그의 옵션으로 설정합니다. 어느 요소를 기준으로 할지(data-target), 그 요소를 기준으로 어디에 붙일지(data-place: replace, append, prepend, before, after 다섯 가지), 마운트 래퍼에 얹을 클래스(data-class, 공백으로 구분해 여러 개를 줄 수 있으며 테마 스타일을 그대로 물려받습니다), 그리고 네 방향 여백(data-padding-top, data-padding-right, data-padding-bottom, data-padding-left, 단위는 px)입니다. 기준 요소를 찾지 못하면 페이지 가드가 giscus 스크립트를 제거해 엉뚱한 곳에 댓글이 붙는 것을 막습니다. 이 동작이 싫다면 data-guard="false"로 끕니다.
data-target=".gh-content"
data-place="after"
data-class="gh-comments gh-canvas"
data-padding-bottom="48"위치 잡기
자주 쓰는 형태는 두 가지입니다. 하나는 본문 바로 뒤에 두는 것이고, 다른 하나는 이미 있는 댓글 블럭을 그대로 대체하는 것입니다. 두 방식을 아래에서 차례로 살펴봅니다.
본문 뒤에 두기
권장 기본값은 data-target=".gh-content" data-place="after" data-class="gh-comments gh-canvas" data-padding-bottom="48" 입니다. 본문(.gh-content) 바로 뒤에 마운트 지점을 만들고, 테마의 gh-comments gh-canvas 클래스를 물려받아 자연스러운 여백과 폭으로 보여 줍니다. 이 방식이 가장 안전한 이유는 본문은 어떤 페이지에서도 항상 존재하기 때문입니다. 구독자 전용으로 감춰지곤 하는 댓글 영역과 달리, 대상이 사라질 걱정 없이 어디서나 동일하게 동작합니다.
<script src="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-giscus-plugin@1/giscus-mount.min.js"
data-target=".gh-content"
data-place="after"
data-class="gh-comments gh-canvas"
data-padding-bottom="48"></script>기존 댓글 블럭 대체하기
테마에 이미 댓글 블럭이 있다면 data-target=".gh-comments" data-place="replace"로 그 자리를 재사용합니다. 테마 파일을 건드리지 않고 code injection만으로 <div class="gh-comments gh-canvas giscus"></div>를 그대로 재현하는 셈이라, 테마가 잡아 둔 위치와 스타일을 손쉽게 물려받습니다. 다만 Ghost의 기본 댓글은 구독자 전용이어서, 그 기능을 끈 사이트에서는 .gh-comments 요소 자체가 없을 수 있습니다. 그럴 때는 위의 본문 뒤에 두기 기본값을 쓰세요.
<script src="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-giscus-plugin@1/giscus-mount.min.js"
data-target=".gh-comments"
data-place="replace"></script>giscus 설정
저장소 연결과 카테고리, repo-id 같은 값은 giscus 공식 사이트에서 발급받습니다. 아래에서 저장소를 입력하면 붙여넣을 giscus 태그를 그대로 만들어 줍니다.
자주 묻는 질문
댓글이 스크립트 자리에 엉뚱하게 붙어요.
이 플러그인 스크립트가 giscus 스크립트보다 뒤에 있는 경우입니다. 순서를 바꿔 이 플러그인을 먼저 두세요.
특정 페이지에만 댓글을 넣고 싶어요.
기준 요소가 그 페이지에만 있으면 됩니다. 선택자가 매칭되지 않으면 아무 것도 하지 않으므로, 포스트에만 있는 요소를 data-target으로 지정하면 자연스럽게 포스트에만 붙습니다.
테마의 댓글 여백을 그대로 쓰고 싶어요.
테마 스타일시트에 규칙이 있으면 data-class로 그 클래스를 얹어 물려받고, 없으면 data-padding-bottom으로 값을 직접 넣습니다.
마치며
공식 giscus는 그대로 두면서 위치만 우리가 잡아 주는 얇은 도구입니다. 코드 한 줄과 순서만 지키면 어느 사이트에서도 동일하게 동작합니다.