최근 블로그 테마를 변경하면서 예상치 못한 문제를 마주했다. 본문 최상단의 대표 이미지가 자꾸 반복되거나 강제로 확대되어 화면을 꽉 채우는 현상 때문에 가독성이 심각하게 떨어졌다. 이 보기 싫은 문제를 해결하기 위해 이전에 쓰던 IT Story 테마의 깔끔한 목차 기능을 새로운 테마로 이식하기로 마음먹었다.

하지만 이식하려는 새로운 jp- 계열 테마에는 결정적인 제약이 있었다. 기존 IT Story 테마의 목차 기능은 jQuery와 jquery.toc.js 플러그인에 무겁게 의존하고 있었는데, 새로 바꾼 테마에는 jQuery가 아예 내장되어 있지 않았다. 목차 하나 쓰자고 무거운 라이브러리를 추가하는 것은 비효율적이라고 판단해 가벼운 바닐라 JS 목차 생성 방법을 직접 구현하기로 결심했다.

무거운 제이쿼리를 걷어내고 바닐라 JS를 선택한 이유

웹사이트 성능 최적화가 중요해진 요즘, 제이쿼리 의존성을 줄이는 것은 성능 향상의 핵심 요소다. 기존의 jquery.toc.js는 편리하지만 브라우저 리소스를 불필요하게 소모한다는 단점이 있었다. 순수 자바스크립트로 코드를 재작성하면 용량이 획기적으로 줄어들고 로딩 속도가 빨라진다.

내가 선택한 jp- 계열 테마의 가벼운 특성을 그대로 유지하기 위해서도 외부 라이브러리 없는 독립적인 코드가 필요했다. 가벼운 바닐라 JS 목차 생성 스크립트는 블로그의 첫 로딩 속도를 유지하면서도 내가 원하는 세부적인 제어 기능을 완벽하게 지원해 준다.

헤딩 태그를 분석하여 한글 슬러그와 고유 ID 부여하기

목차(table of contents)를 자동으로 생성하려면 먼저 포스트 본문 내에 위치한 제목 태그들을 정확히 찾아내야 한다. 새로운 테마의 구조를 분석해 보니 본문 영역은 `.jp-post-body` 클래스로 감싸져 있었다. 이 영역 안에서 h2, h3, h4 태그를 차례대로 스캔하도록 탐색 범위를 좁혔다.

가장 까다로웠던 작업은 각 제목 태그에 고유한 ID를 부여하여 목차 링크와 매칭하는 과정이었다. 영문만 지원하는 단순한 슬러그 대신 한글 슬러그 생성이 완벽하게 동작하도록 정규식을 활용해 한글과 영문, 숫자가 포함된 고유 ID를 정제해 나갔다. 혹시 발생할 수 있는 동일한 제목의 중복 ID 문제를 방지하기 위해 중복 카운터를 더해 방어 코드도 철저히 심어두었다.

부드러운 스크롤 이동과 헤더 오프셋 정밀 조절하기

목차 아이템을 생성한 후에는 이를 클릭했을 때 본문 해당 위치로 매끄럽게 이동하도록 만들어야 한다. CSS의 기본 스크롤 동작 대신 자바스크립트의 smooth scroll 방식을 활용해 사용자 경험을 극대화했다. 목차 목록을 `ul`과 `li` 태그 조합으로 빌드하여 본문 상단에 동적으로 렌더링되도록 코드를 짰다.

하지만 여기서 치명적인 문제가 발생했다. 테마 상단에 고정된 스티키 헤더(Sticky Header)가 목차 링크를 타고 이동한 실제 본문 제목을 가려버리는 현상이었다. 이를 해결하기 위해 각 제목 엘리먼트에 `scroll-margin-top` 속성을 동적으로 계산하여 오프셋 값을 제공함으로써, 헤더에 가려지지 않고 깔끔하게 멈추도록 조정했다.

조건부 노출과 테마 맞춤형 디자인 완성하기

모든 글에 제목 태그가 풍부하게 들어가는 것은 아니기 때문에, 짧은 글이나 헤딩이 없는 글에서는 목차 영역이 비어 있게 된다. 이런 군더더기를 방지하기 위해 본문을 스캔한 뒤 h2, h3, h4 태그가 하나도 존재하지 않을 경우 목차 레이아웃 전체를 자동으로 숨기도록 설계했다. 불필요한 영역이 화면을 차지하지 않으니 블로그 디자인이 한결 정돈되었다.

마지막으로 jp- 계열 테마 고유의 컨셉 색상을 추출하여 목차의 테두리와 포인트 컬러에 고스란히 이식했다. 이렇게 구현된 바닐라 JS 목차 생성 스크립트는 기존의 무거웠던 제이쿼리 기반 목차보다 가벼우면서도 테마의 일부분인 것처럼 조화롭게 녹아들었다. 플러그인 없이 순수한 코드로 문제를 해결했을 때의 쾌감은 역시 대단하다.