지난 글에서 /standalone
페이지를 만들고 nav를 재편했다. 그 뒤로도 이 시리즈 페이지 작업은 며칠
더 이어졌다 — 배포 실패 하나, 새 기능 두 개, 그리고 진짜 버그 두 개.
3편을 발행하자마자 빌드가 죽었다 — CannotFetchFontFile
3편을 push하고 몇 분 뒤, Cloudflare 빌드 로그가 실패로 떴다. 로그를
끝까지 읽어보니 astro check는 0 errors로 통과했고, 콘텐츠 빌드까지도
다 끝났는데, 그다음 “Copying fonts” 단계에서 Google Fonts CDN
(fonts.gstatic.com)에서 폰트 파일 하나를 못 받아왔다는
CannotFetchFontFile 에러였다.
이번 세션 안에서 폰트 설정(fontProviders.google())을 건드린 적이 없어서,
git log로 그 설정이 언제 마지막으로 바뀌었는지 확인했다 — 오래전 커밋
이었다. 즉 내가 방금 올린 코드와는 무관한, 그 순간 Cloudflare 빌드
서버가 Google 서버에 접속하지 못한 순수 네트워크 문제였다. 코드에
고칠 게 없어서 재배포를 요청해서 정상적으로 배포됐다.
독립글 읽다가 시리즈로 새면 못 돌아온다는 지적
3편 배포를 확인받고 나서, 실사용 피드백이 하나 왔다 — 독립글을 읽다가
날짜순 “다음 글”을 누르면 시리즈 글로 넘어가는데, 그 시리즈 글의
네비게이션은 그 시리즈 안에서만 경계 지어져 있어서 “다음 독립글”로
돌아갈 방법이 없다는 거였다. 코드를 다시 열어보니 정확히 그랬다 —
isSeriesNav가 true가 되는 순간 이전/다음이 전체 발행글이 아니라 같은
시리즈 안의 이전/다음 편으로 완전히 바뀌는데, 그 전환 자체가 무통보였다.
“이전 글/다음 글”이 “이전 편/다음 편”으로 라벨만 조용히 바뀔 뿐이었다.
세션에 이미 있던 “뒤로” 버튼(목록 페이지를 방문할 때마다
sessionStorage에 그 URL을 저장해두는 기존 메커니즘)이 안전망 역할은
하고 있다는 걸 먼저 확인했다. 그래도 근본적인 개선 방향을 놓고 몇
가지를 논의했다 — 시리즈 끝에서 다른 시리즈로 무한히 연결하는 안,
독립글끼리만 연결하는 안, 지금 그대로 두는 안. 시리즈 끝을 다른
시리즈로 잇는 건 “시리즈는 완결된 이야기 단위”라는 이 블로그의 기존
구조와 안 맞아서 접었다.
화살표 대신 목차로 — SeriesBadge, SeriesToc
논의 중에 다른 각도가 하나 나왔다 — 지금까지는 “이전/다음이 정확히 뭘 가리키게 할까”만 얘기하고 있었는데, 진짜 문제는 독자가 “지금 시리즈 글을 읽고 있다”는 것 자체를 인지할 방법이 없다는 데 있었다. 그래서 시리즈 글에 두 가지를 추가하기로 했다 — 제목 근처에 “{시리즈명} · M/N편” 배지 하나, 그리고 하단의 이전/다음 편 박스를 그 시리즈 전체 목차로 통째로 교체하는 것.
배지를 상단에 둘지 하단에 둘지도 잠깐 얘기가 나왔다. 결론은 목차는
하단(글을 다 읽고 “다음엔 뭘 볼까” 결정하는 바로 그 시점), 배지는
상단(읽기 시작하기 전에 맥락을 알려주는 용도)으로 나눴다. 둘 다
series/seriesTitle/seriesOrder frontmatter만으로 빌드 시점에
계산되게 만들어서, 본문은 전혀 손댈 필요가 없었다.
VPS라 브라우저로 직접 확인할 수 없어서, 실제로 만들고 나서는 프로덕션
빌드를 돌려 그 결과물 HTML을 grep으로 까봤다 — 시리즈 1편·중간편·
마지막편·독립글 각각에서 배지와 목차가 정확히 뜨는지, aria-current가
지금 편만 정확히 가리키는지 하나씩 확인하고 나서야 커밋했다.
독립글도 스코프를 좁히다가, 방향이 뒤집힌 버그를 잡았다
배지·목차를 만들고 나니 자연스러운 다음 질문이 나왔다 — 독립글의
이전/다음도 똑같이 스코프를 좁혀서, 독립글끼리만 순환하게 만들면
어떨까. /standalone 페이지를 만들 때 이미 있던 getStandalonePosts
유틸을 재사용하면 되는 작업이라 비용도 낮았다.
고치고 나서 실제 빌드 결과물을 다시 열어봤는데, 이상한 게 보였다. “링크가 깨질 줄 알고…” 글(8/22)의 “이전 글”이 그보다 하루 늦게 쓴 글(8/23)을 가리키고, “다음 글”이 오히려 일주일 전 글(8/15)을 가리키고 있었다. 방향이 통째로 뒤집혀 있었다.
이 시리즈의 원본 코드(sortedPosts[index + 1]이 prev, `sortedPosts[index
- 1]
이 next)를getStandalonePosts버전으로 옮겨 적으면서, 인덱스 부호를 반대로 썼던 것이었다. 공교롭게도 이건 이 블로그가 예전에 [한 번 이미 겪었던 것과 정확히 같은 종류의 버그](다음-글을-눌렀더니-어제-쓴-글이-나왔다.md)였다 — AstroPaper 원본 테마에도 있던 그 방향 버그를, 이번엔 내가 새로 짠 코드에서 재현한 셈이다.astro check`는 타입만 보니 이런 논리 오류는 못 잡는다는 것도 다시 확인했다 — 실제 빌드 결과물을 열어보지 않았다면 그대로 커밋했을 거다. 방향을 바로잡고 나서야 커밋했다.
MCP 시리즈 설명이 1편에 멈춰 있었다 — firstPostDescription
이 작업들이 다 배포되고 나서, MCP 시리즈 페이지를 확인하다가 또 다른
문제가 보였다 — 5편까지 늘어난 시리즈인데, 페이지 설명(meta
description이자 화면에 보이는 인트로 문장)은 여전히 1편 소개(“ponytail
하나뿐이었다”)만 보여주고 있었다. 코드를 열어보니 원인이 바로 나왔다
— firstPostDescription = seriesPosts[0]?.data.description. 시리즈가
몇 편으로 늘어나든 이 값은 절대 안 바뀌는 구조였다.
첫 번째로 든 생각은 “1편 대신 최신편 기준으로 바꾸면 되지 않나”였다. 그런데 이 제안 자체가 다시 지적받았다 — 최신편으로 바꿔도 “어느 한 시점에 고정된 특정 편의 얘기”라는 근본 문제는 똑같다는 거였다. 고정점을 1편에서 최신편으로 옮기는 것뿐이지, “시리즈 전체가 뭘 다루는가”를 설명하는 게 아니었다.
시리즈 전체를 위한 필드를 새로 만들다 — seriesDescription
여기서 몇 가지 대안이 오갔다. 모든 편에 시리즈 설명을 반복해서
적자는 안은 seriesTitle처럼 매 편에 복붙해야 해서 나중에 하나만
고치고 나머지를 깜빡할 위험이 있었다. 편이 늘 때마다 이전 편들
내용을 이어붙이자는 안도 나왔는데, 이건 검색엔진이 실제로 보여주는
길이(150~160자 정도)를 편수가 늘수록 넘어서고, 이어붙인 텍스트는
“1편은 이거, 2편은 이거”를 나열한 것이지 시리즈 전체를 요약한 게
아니라는 문제가 있었다.
결국 정리된 방향은 이거였다 — seriesDescription이라는 새 필드를
스키마에 추가하고, 딱 1편에만 명시적으로 써넣는다. 편이 늘어난다고
자동으로 바뀌지 않고, 시리즈의 실제 성격이 바뀔 때만(자주 있는 일은
아니다) 수동으로 다시 쓴다. 필드가 없는 시리즈는 기존 일반 문구로
안전하게 폴백하게 만들어서, 한 번에 전부 다 채워야 하는 것도 아니게
했다.
MCP 시리즈부터 실제 설명을 채워 넣었는데, 그러고 나서 아직 발행 안 한 시리즈까지 포함해 이 블로그의 시리즈 전체(19개)에 똑같이 채워 넣기로 했다. 채우고 나니 마지막으로 하나가 더 보였다 — 이제 모든 시리즈에 진짜 설명이 있는데, 그 앞에 “All the articles in the series ‘X’.”라는 일반 문구가 여전히 붙어서 페이지 제목을 문장으로 한 번 더 반복하고 있었다. 이것도 걷어내서, 설명이 있으면 그 내용만 보이게 정리했다.
배운 점
이번엔 서로 다른 층위에서 같은 패턴이 두 번 나왔다. 하나는 “1편 고정”을 “최신편 고정”으로 바꾸려던 순간 — 고정점을 옮기는 것과 진짜 문제를 고치는 것은 다른 일이었다. 다른 하나는 독립글 네비게이션을 스코프만 좁히면 끝일 줄 알았는데, 실제로 빌드해서 열어보지 않았다면 방향이 뒤집힌 채로 나갔을 거였다는 것 — 이 블로그가 예전에 이미 한 번 겪었던 것과 똑같은 버그를, 이번엔 내가 새로 만든 코드에서 다시 만들었다. 타입 체크가 통과한다는 것과 논리가 맞다는 것은 다른 질문이었고, 그 차이는 결국 실제 결과물을 눈으로 확인해야만 드러났다.