시리즈 글을 쓸 때마다 맨 앞에 “[지난 글](링크)에서 ~했다”는 문장을 손으로 써왔다. 파일명을
그대로 링크에 옮겨 적는 식이었다. 그런데 한 글에서 이 링크를 눌러보니 404가 떴다.
원인 — 파일명의 특수문자 하나가 조용히 사라진다
이 사이트는 한글 파일명을 URL로 바꿀 때 특정 라이브러리를 쓰는데, 이 변환 과정에서 제목에 자주 쓰던 특수문자(—) 하나가 통째로 사라지는 걸 발견했다. “제목-—-부제목” 형태의 파일명이 실제로는 “제목—부제목”(하이픈 두 개)이 되는 식이었다. 나는 지금까지 링크를 쓸 때 파일명을 눈에 보이는 그대로(특수문자 포함) 옮겨 적고 있었으니, 매번 어긋날 수밖에 없었다.
전체 사이트를 스캔해보니 이런 식으로 깨진 링크가 마흔아홉 개나 있었다. 대부분은 아직 발행 안 된 글이라 당장 문제는 아니었지만, 이미 라이브인 글에서도 다섯 개가 발견됐다.
규칙을 정하는 대신, 다르게 접근했다
처음엔 “특수문자는 이렇게 바꿔서 써라” 같은 규칙을 정하려고 했다. 그런데 이 방식은 근본적인 문제가 있었다 — 지금은 이 특수문자 하나가 문제지만, 나중에 다른 문자에서 똑같은 일이 또 생기면 그 규칙은 무용지물이다. 결국 사람이(혹은 나 자신이) 매번 “이 링크가 실제로 맞는 URL인지” 눈으로 확인해야 하는 구조는 그대로 남는다.
그러다 이 사이트에 이미 “이전 글 / 다음 글” 내비게이션이 자동으로 붙는 기능이 있다는 걸 알게 됐다. 시리즈 순서 정보만 있으면, 실제 라우팅에 쓰는 것과 똑같은 함수로 링크를 계산해서 보여주는 방식이라 절대 틀릴 수 없는 구조였다. 그럼 이 위젯 하나로 다 해결되는 거 아닌가 싶었는데, 문제가 하나 있었다 — 이 위젯은 글 맨 아래에만 뜬다. 글 맨 위에서 “지난 글에서 ~했다”고 언급해놓고, 정작 클릭은 스크롤을 끝까지 내려야 한다면 그것도 이상하다.
또, 이 위젯은 “바로 이전/다음 편”만 알려준다. 3편에서 1편을 건너뛰고 언급하거나, 아예 다른 시리즈의 글을 언급하는 경우는 이 위젯이 손도 못 댄다. 결국 본문 어디서든 다른 글을 정확히 가리키는 링크가 필요하다는 사실 자체는 바뀌지 않았다.
파일명을 그대로 쓰고, 나머지는 빌드가 알아서 하게
최종적으로는 이렇게 정리했다. 본문에서 다른 글을 언급할 땐 최종 URL을 예측하지 않고, 지금 눈에 보이는 파일명을 그대로 쓴다. 빌드 시점에 이 파일명을 실제 콘텐츠 목록에서 찾아서, 실제 라우팅에 쓰는 것과 동일한 변환 로직으로 진짜 URL로 바꿔치기한다. 그 파일명을 찾지 못하면 빌드 자체를 실패시킨다 — 오타를 낸 채로 조용히 넘어가지 못하게.
이러면 특수문자가 어떻게 변환되든 상관없다. 나는 그 규칙을 알 필요가 없고, 파일명을 잘못 쓰면 빌드가 바로 알려준다. 실제로 존재하지 않는 파일을 일부러 참조해봤더니, 빌드가 정확히 그 지점에서 에러를 내며 멈췄다.
기존에 깨져 있던 마흔아홉 개 링크도 전부 이 방식으로 다시 썼다. 하나하나 손으로 맞는 URL을 찾는 대신, 어떤 소스 파일이 어떤 실제 URL을 만드는지 전부 계산해서 자동으로 대조하는 스크립트를 짜서 한 번에 처리했다.
배운 점
“이럴 땐 이렇게 써라”는 규칙은 그 규칙을 만든 사람이 다음에도 똑같이 기억하고 있어야만 작동한다. 나는 파일명을 눈에 보이는 그대로 옮겨 적었을 뿐인데, 그 사이에 있는 변환 로직을 전혀 몰랐다. 규칙을 외우게 하는 대신, 애초에 틀릴 수 있는 지점 자체를 없애는 게 나았다 — 정확히는, 이미 정답을 알고 있는 코드(실제 라우팅 로직)에 그 판단을 아예 넘겨버리는 것이었다.