[🛠] GitHub Pages 블로그 각주를 팝업으로 바꾸기

✨ GPT-5.5의 요약 　

Kramdown 기본 각주가 본문에서 맨 아래 참고 자료로 이동하던 불편함을 줄이기 위해, 기존 각주 구조는 유지하면서 본문 각주 링크를 [1] 형태의 팝업 UI로 바꾼 기록.

각주를 제대로 쓰기 시작하니 바로 불편함이 보였다.

블로그 글에서 외부 기사나 자료를 다룰 때는 이제 본문 옆에 Kramdown footnote를 붙인다. 특히 투표용지 부족이라는 초유의 사건, 분노, 극단주의자의 폐해 같은 글은 사실관계가 많아서 각주가 꽤 많았다.

그런데 막상 읽어보니 흐름이 별로였다.

본문에서 각주 번호를 누르면 팝업이 뜨는 게 아니라, 페이지 맨 아래 참고 자료 영역으로 내려갔다. 기본 동작으로는 맞다. Kramdown이 원래 그렇게 각주를 만든다. 하지만 긴 글에서는 읽던 위치를 잃기 쉽다.

각주 번호 모양도 애매했다.

1 2 3 4처럼 작은 숫자만 붙어 있으면 누르기 어렵다. 특히 모바일에서는 더 그렇다. 본문 중간에 떠 있는 작은 숫자를 정확히 누르는 일은 생각보다 신경 쓰인다.

그래서 이번에는 각주 시스템을 조금 바꿨다.

본문에서는 [1], [2], [3]처럼 보이고, 누르면 맨 아래로 이동하지 않고 작은 팝업이 뜨게 만들었다.

Kramdown 구조는 건드리지 않았다

처음부터 Markdown 문법이나 footnote 생성 방식을 바꾸고 싶지는 않았다.

지금 글들은 이런 식으로 쓴다.

본문 문장.[^source]

[^source]: 자료 설명과 링크

이 방식은 계속 유지하는 게 맞다.

글을 쓰는 입장에서는 Markdown 표준에 가까운 문법을 쓰고, Jekyll이 빌드할 때 Kramdown이 각주 HTML을 만든다. 하단 참고 자료 영역도 그대로 남는다. 이 구조까지 갈아엎으면 기존 글 전체와 번역 글까지 건드려야 한다.

기준은 단순했다.

글 작성 방식은 그대로 둔다.
Kramdown이 만든 하단 각주도 그대로 둔다.
본문 각주 링크의 표시와 클릭 동작만 바꾼다.

즉, 원본 데이터와 fallback은 유지하고, 읽는 경험만 개선하는 쪽이다.

각주 번호를 [1]처럼 보이게 했다

먼저 CSS를 바꿨다.

Kramdown은 본문 각주 링크에 a.footnote 클래스를 붙인다. 이 링크를 작은 inline-flex 버튼처럼 만들고, ::before, ::after로 대괄호를 붙였다.

결과적으로 본문에서는 숫자 하나가 아니라 이런 모양으로 보인다.

[1] [2] [3]

손가락으로 누를 영역도 조금 넓혔다.

크게 튀는 버튼이면 본문 리듬이 깨진다. 그렇다고 예전처럼 작은 숫자만 두면 클릭하기 어렵다. 그래서 테두리와 배경을 아주 얇게 넣고, 글자 크기는 본문보다 작게 유지했다.

밝은 모드와 어두운 모드가 둘 다 있으므로 색은 하드코딩하지 않고 기존 Sass 변수에 맞췄다.

$primary-color
$background-color
$border-color
$text-color

이 블로그는 이미 customOverride.scss를 밝은 스킨과 어두운 스킨 뒤에서 공통으로 불러온다. 그래서 테마 원본 파일을 직접 고치지 않고 _sass/custom/customOverride.scss에 각주 스타일을 추가했다.

클릭하면 팝업을 만든다

다음은 JavaScript다.

기존에는 모든 #hash 링크에 SmoothScroll이 걸려 있었다. 각주 링크도 결국 #fn:...으로 가는 내부 링크라서, 누르면 페이지 아래쪽으로 부드럽게 이동했다.

이번에는 본문 안의 각주 링크만 먼저 가로챘다.

대상은 이렇다.

.page__content a.footnote[href^="#fn"]

클릭하면 원래 해시 이동을 막고, 하단 각주 목록에 이미 렌더링된 내용을 찾아서 복제한다. 하단 각주 안에는 본문으로 돌아가는 reversefootnote 링크가 들어 있는데, 팝업 안에서는 필요 없으니 제거했다.

흐름은 이렇다.

본문 각주 클릭
-> href에서 target id 읽기
-> 하단 footnote li를 찾기
-> 내용을 clone
-> reversefootnote 제거
-> 팝업에 삽입
-> 각주 링크 근처에 위치 계산

해시를 바꾸지 않기 때문에 URL도 지저분해지지 않는다. 페이지 맨 아래로 내려가지도 않는다.

닫는 방법은 세 가지로 했다.

같은 각주 다시 클릭
팝업 밖 클릭
Esc 또는 닫기 버튼

키보드 사용을 위해 aria-haspopup="dialog"와 aria-expanded도 붙였다. 팝업 자체에는 role="dialog"를 넣었다. 이게 완벽한 접근성 컴포넌트라고 말할 정도는 아니지만, 최소한 그냥 떠 있는 div보다는 낫다.

모바일에서 화면 밖으로 나가지 않게 했다

각주 팝업은 위치 계산이 중요했다.

본문 링크 바로 아래에 띄우면 자연스럽지만, 화면 오른쪽 끝이나 모바일 폭에서는 쉽게 삐져나간다.

그래서 위치를 잡을 때 viewport 안쪽 margin을 강제로 둔다.

왼쪽은 최소 12px
오른쪽도 최소 12px
아래 공간이 부족하면 위쪽으로 띄우기
그래도 부족하면 viewport 안쪽으로 clamp

팝업 폭도 고정 폭이 아니라 이렇게 잡았다.

width: min(30rem, calc(100vw - 1.5rem));

데스크톱에서는 너무 넓어지지 않고, 모바일에서는 화면보다 커지지 않는다.

긴 각주를 대비해 max-height와 overflow: auto도 넣었다. 외부 기사 제목이 길거나 링크가 붙어도 팝업이 화면을 다 덮지 않게 하려는 의도다.

압축 파일도 같이 갱신했다

이 블로그는 assets/js/_main.js가 소스이고, 실제 배포에서는 assets/js/main.min.js를 읽는다.

그래서 JS를 고친 뒤에는 Rake 태스크로 압축 파일과 source map을 다시 만들었다.

bundle exec rake js

이걸 빼먹으면 로컬 소스만 좋아지고 실제 사이트에서는 예전 JS가 계속 나갈 수 있다. 그래서 소스 파일과 배포 파일을 같이 봐야 한다.

각주 팝업 동작과 모바일 위치를 확인했다

명령은 이렇게 돌렸다.

node --check assets/js/_main.js
bundle exec rake js
bundle exec jekyll build

그리고 각주가 많은 실제 글을 로컬 정적 서버로 열어 확인했다.

브라우저에서는 이 기준을 봤다.

각주 링크가 [1] 형태로 보이는가
클릭 후 URL hash가 바뀌지 않는가
맨 아래 참고 자료 영역으로 이동하지 않는가
팝업이 뜨는가
팝업 안에 하단 각주 내용이 들어오는가
모바일 폭에서도 팝업이 화면 안에 들어오는가

데스크톱에서는 하단 각주 위치가 문서 아래쪽에 있었지만, 각주 클릭 후 스크롤은 본문 근처에 머물렀다. 모바일 폭에서도 팝업은 화면 안에 들어왔다.

각주 링크를 본문 안 팝업으로 읽게 만들었다

특히 사실관계가 많은 글에서는 각주가 장식이 아니다. 독자가 “이 말 어디서 나온 거지?” 싶을 때 바로 확인할 수 있어야 한다. 그런데 확인하러 갔다가 글 맨 아래로 떨어지고, 다시 본문으로 돌아와야 한다면 각주는 금방 귀찮은 물건이 된다.

이제는 본문을 읽다가 [1]을 누르면 바로 확인하고 닫을 수 있다.

하단 참고 자료도 그대로 남아 있다. 글 끝에서 자료를 한 번에 훑고 싶은 사람은 여전히 맨 아래를 보면 된다.

Markdown 작성 방식과 Jekyll/Kramdown 기본 구조는 그대로 두고, 본문을 읽는 도중 맨 아래 참고 자료로 튀는 이동만 줄였다.