JAVAPARK Dev v1.2 스킨 — 목차(TOC) 자동 생성과 플로팅 네비게이션

☕ 안녕하세요, 자바파커입니다!

지난번 스킨 v1.0 포스팅에서 개발자 감성의 티스토리 스킨을 공유해 드렸는데요, 그 이후로 직접 블로그를 운영하면서 느낀 게 하나 있습니다.

글이 길어지면 "지금 어디쯤 읽고 있지?" 하는 순간이 옵니다.
위로 올라가서 다른 섹션을 찾으려면 스크롤 지옥이 시작되죠.

그래서 JAVAPARK Dev 스킨 v1.2에서는 목차(TOC) 자동 생성과 플로팅 네비게이션을 추가했습니다.

티스토리 스킨 v1.2 주요 변경사항

결론부터 말씀드리면, 이번 업데이트의 핵심은 "긴 글을 편하게 읽게 만드는 것" 입니다.

티스토리 목차 자동 생성 기능 (인라인 TOC)

포스팅에 h2, h3, h4 헤딩이 2개 이상 있으면, 글 상단에 목차가 자동으로 생성됩니다.

별도의 플러그인이나 수동 작성 불필요
JavaScript가 .entry-content 내 헤딩을 파싱해서 목록을 만듬
접기/펼치기 토글 지원
현재 읽고 있는 섹션이 하이라이트 됨

모바일에서는 기본 접힌 상태로 시작해서 화면 공간을 절약합니다.

플로팅 목차 버튼으로 어디서든 네비게이션

스크롤을 내려 인라인 목차가 화면 밖으로 나가면, 우하단에 원형 버튼(FAB) 이 나타납니다.

기능	설명
FAB 버튼	목차 아이콘 + 읽기 진행률 원형 표시
패널 열기	버튼 클릭 → 목차 패널이 나타남
패널 닫기	X 버튼 / ESC 키 / 바깥 클릭 / 항목 클릭
활성 섹션	현재 읽는 위치에 해당하는 항목 하이라이트

모바일 목차 — Bottom Sheet 방식

모바일에서는 같은 FAB 버튼을 누르면 하단 시트(Bottom Sheet) 형태로 목차가 올라옵니다.

드래그 핸들(상단 pill 바)로 직관적 UX
아래로 스와이프하면 닫힘
배경 딤 오버레이 → 포커스 집중
배경 스크롤 자동 잠금
노치 기기 safe-area 대응
터치하기 충분한 크기의 항목 패딩

기타 개선사항

GNB 현재 메뉴 하이라이트 — 현재 페이지와 일치하는 카테고리에 active 표시
View More 더보기 — AJAX 방식으로 다음 페이지 포스트를 이어서 로드
ESC 키 핸들러 — 검색, 메뉴, 목차 패널을 ESC로 일괄 닫기
댓글 URL 자동 링크 — 댓글에 포함된 URL을 자동으로 클릭 가능한 링크로 변환

Claude Code로 티스토리 스킨 목차 구현하기

이번에도 코드 작성은 Claude Code가 담당했습니다.

작업 흐름을 간단히 정리하면 이렇습니다.

1. "목차 기능이 있었으면 합니다" → 기본 구조 설계 + 구현
2. "카테고리의 다른 글은 나올 필요가 없어요" → 제외 필터 추가
3. "플로팅되어 따라다녔으면" → FAB + 패널 방식으로 전환
4. "모바일에서 확인하기 힘드네요" → Bottom Sheet + 터치 UX 개선

한 번에 완성된 게 아니라, 실제로 써보면서 피드백하고 개선하는 과정을 거쳤습니다. AI에게 한 번에 완벽한 결과물을 기대하기보다, 대화하면서 방향을 잡아가는 것이 훨씬 좋은 결과를 만듭니다.

티스토리 목차 기능 기술 구조

관심 있는 분들을 위해 구현 구조를 간략히 설명합니다.

파일 구성

파일	역할	변경 사항
`skin.html`	HTML 템플릿	TOC 컨테이너(`<nav id="toc">`) 추가, 댓글 링크 스크립트 추가
`style.css`	스타일시트	인라인 TOC, FAB, 플로팅 패널, Bottom Sheet, 반응형 스타일 추가
`images/script.js`	JavaScript	TOC 생성, 스크롤 감지, FAB/패널 로직, GNB 하이라이트, View More

TOC 생성 로직

// 1. entry-content 내 h2, h3, h4를 수집
// 2. 불필요한 영역(관련글, 태그, 댓글) 내 헤딩은 제외
var EXCLUDE = '.another_category, .related-articles, .tags, .comments';
var headings = Array.prototype.filter.call(allHeadings, function (h) {
  return !h.closest(EXCLUDE);
});

// 3. 각 헤딩에 id 부여 → 목차 링크의 앵커로 사용
// 4. 인라인 목차 + 플로팅 패널 두 곳에 동일한 목록 생성

스크롤 성능 최적화

requestAnimationFrame으로 스크롤 이벤트를 throttle 처리합니다. 매 프레임마다 최대 한 번만 계산하므로, 무거운 스크롤 리스너 문제가 없습니다.

window.addEventListener('scroll', function () {
  if (!ticking) {
    requestAnimationFrame(function () {
      updateActiveHeading(tocItems, list, floatEl);
      updateFabVisibility(toc, fab);
      updateProgress(progressCircle, getCircumference());
      ticking = false;
    });
    ticking = true;
  }
});

모바일 Bottom Sheet CSS 구현

CSS transform: translateY(100%)로 화면 아래에 숨겨두고, .show 클래스가 붙으면 translateY(0)으로 올라옵니다. cubic-bezier(0.32, 0.72, 0, 1)로 iOS 네이티브 같은 부드러운 스프링 느낌을 줍니다.

JAVAPARK Dev 스킨 다운로드 (v1.2)

이 블로그에 적용된 JAVAPARK Dev 스킨을 공개합니다. 자유롭게 다운로드해서 사용하세요.

JAVAPARK Dev v1.2.zip

804.8 kB

파일	설명
skin.html	HTML 구조 (TOC 컨테이너 + 댓글 링크 포함)
style.css	전체 CSS (~3,000줄)
images/script.js	JavaScript (TOC, 메뉴, 슬라이더, View More)

3개 파일 모두 교체해야 v1.2의 모든 기능이 동작합니다.

적용 방법

티스토리 관리 > 꾸미기 > 스킨 편집 클릭
html 편집 버튼 클릭
HTML 탭에 skin.html 내용을 붙여넣기
CSS 탭에 style.css 내용을 붙여넣기
파일업로드 탭에서 images/script.js를 업로드
적용 클릭

v1.0에서 업그레이드하는 경우

CSS와 HTML을 모두 교체하고, images/script.js 파일을 새로 업로드하면 됩니다. :root에서 커스터마이징한 색상 변수가 있다면 새 CSS에도 동일하게 적용해 주세요.

버전 히스토리

버전	날짜	주요 변경
v1.0	2025-03	최초 공개 — CSS 전면 재작성, 디자인 토큰, 코드 블록 스타일링
v1.2	2026-03	목차 자동 생성, 플로팅 네비게이션, 모바일 Bottom Sheet, GNB 하이라이트, View More, 댓글 URL 자동 링크, JavaScript 추가

자주 묻는 질문 (FAQ)

목차가 안 나타나는데요?

목차는 포스팅 본문에 h2, h3, h4 헤딩이 2개 이상 있을 때만 자동 생성됩니다. 헤딩 없이 본문만 있는 짧은 글에서는 의도적으로 표시하지 않습니다.

목차에 "카테고리의 다른 글"이 포함되는데요?

v1.2에서는 .another_category, .related-articles, .tags, .comments 내부의 헤딩을 자동으로 제외합니다. 혹시 다른 영역의 헤딩도 제외하고 싶다면 script.js의 EXCLUDE 변수에 셀렉터를 추가하면 됩니다.

플로팅 버튼이 안 보여요

플로팅 버튼은 인라인 목차가 스크롤로 화면 밖으로 나간 후에만 표시됩니다. 글 상단에서는 인라인 목차가 보이므로 중복 표시하지 않습니다.

이번 업데이트가 긴 글을 쓰고 읽는 분들께 도움이 되었으면 합니다.

여러분의 블로그에도 목차 기능이 있나요? 있다면 어떤 방식으로 구현하셨는지 댓글로 알려주세요!

참고 자료

티스토리 스킨 가이드 — 티스토리 공식 스킨 구조 및 치환자 문서
Intersection Observer API (MDN) — 스크롤 감지 대안 기법
requestAnimationFrame (MDN) — 스크롤 성능 최적화
CSS env() (MDN) — safe-area-inset 노치 대응
스킨 v1.0 포스팅 — 이전 버전 소개

저작자표시 비영리 변경금지 (새창열림)

'블로그 운영' 카테고리의 다른 글

블로그 대표이미지를 코드로 만드는 법 — HTML + Playwright PNG 변환 (0)	2026.03.28
티스토리 블로그 구글 SEO 최적화 — 검색 노출을 위한 실전 가이드 (0)	2026.03.28
티스토리 포스팅 자동화 방법 — API 폐지 이후 남은 선택지 정리 (0)	2026.03.28
티스토리 스킨 커스터마이징 — Claude Code로 개발자 테마 만들기 (0)	2026.03.28

AI JAVAPARK - AI & Dev

JAVAPARK Dev v1.2 스킨 — 목차(TOC) 자동 생성과 플로팅 네비게이션

티스토리 스킨 v1.2 주요 변경사항

티스토리 목차 자동 생성 기능 (인라인 TOC)

플로팅 목차 버튼으로 어디서든 네비게이션

모바일 목차 — Bottom Sheet 방식

기타 개선사항

Claude Code로 티스토리 스킨 목차 구현하기

티스토리 목차 기능 기술 구조

파일 구성

TOC 생성 로직

스크롤 성능 최적화

모바일 Bottom Sheet CSS 구현

JAVAPARK Dev 스킨 다운로드 (v1.2)

적용 방법

v1.0에서 업그레이드하는 경우

버전 히스토리

자주 묻는 질문 (FAQ)

목차가 안 나타나는데요?

목차에 "카테고리의 다른 글"이 포함되는데요?

플로팅 버튼이 안 보여요

참고 자료

'블로그 운영' 카테고리의 다른 글

티스토리툴바

JAVAPARK Dev v1.2 스킨 — 목차(TOC) 자동 생성과 플로팅 네비게이션

티스토리 스킨 v1.2 주요 변경사항

티스토리 목차 자동 생성 기능 (인라인 TOC)

플로팅 목차 버튼으로 어디서든 네비게이션

모바일 목차 — Bottom Sheet 방식

기타 개선사항

Claude Code로 티스토리 스킨 목차 구현하기

티스토리 목차 기능 기술 구조

파일 구성

TOC 생성 로직

스크롤 성능 최적화

모바일 Bottom Sheet CSS 구현

JAVAPARK Dev 스킨 다운로드 (v1.2)

적용 방법

v1.0에서 업그레이드하는 경우

버전 히스토리

자주 묻는 질문 (FAQ)

목차가 안 나타나는데요?

목차에 "카테고리의 다른 글"이 포함되는데요?

플로팅 버튼이 안 보여요

참고 자료

'블로그 운영' 카테고리의 다른 글

'블로그 운영' Related Articles

티스토리툴바