티스토리 블로그에 자동 목차(TOC) 추가하기

개인적으로 호흡이 긴 글을 읽을 때는 목차부터 확인하는 편이다. 목차를 보면 글 전체 흐름을 빠르게 파악할 수 있고, 필요한 부분만 골라서 읽을 수 있기 때문이다. 블로그 글도 마찬가지로 내용이 길어질수록 목차가 있으면 글 읽기가 한결 수월해진다.

 

목차는 영어로 TOC(Table of Contents)라고 부르는데, 노션(Notion) 사용자라면 /toc 명령어로 목차를 손쉽게 삽입해 본 경험이 있을 것이다. 그만큼 익숙하고 유용한 기능이다.

노션의 목차 삽입 명령어

 

아쉽게도 티스토리(Tistory)는 목차 기능을 제공하지 않는다. 다만 티스토리 본문은 어느 정도 시맨틱 마크업(의미/역할에 맞는 HTML 구조)을 따르고 있어서 기본모드 에디터 기준 제목1~제목3은 <h2>~<h4>, 본문은 <p> 같은 태그로 구성되어 있다. 이런 구조 덕분에 자바스크립트(JavaScript)를 활용한다면 티스토리에도 목차 기능을 추가할 수 있다.

 

원래는 개인적으로 사용하려고 만들었지만, 스크립트 한 줄만 추가하면 대부분의 티스토리 스킨에 적용할 수 있어서 소개해 보려고 한다. 데스크톱은 노션과 비슷한 레일형 디자인을, 모바일은 버튼을 누르면 팝업이 열리는 방식을 적용했다.

데스크톱 목차

모바일(1280px 미만 화면) 목차

 

 

설치 방법

---

티스토리 관리자 > 스킨 편집 > HTML 편집 화면에서 </body> 태그 바로 위에 아래 스크립트를 삽입한다.

<script defer src="https://cdn.jsdelivr.net/gh/romantech/tistory-plugins@latest/dist/toc/index.min.js"></script>

 

TOC 플러그인은 기본적으로 h2~h4 제목 태그를 대상으로 목차를 생성한다. 제목이 두 개 미만이라면 목차를 표시하지 않는다. 필요하다면 아래 옵션을 조정해서 원하는 제목 레벨을 직접 지정할 수 있다. ⚠️ 옵션 코드는 스크립트 코드보다 위에 위치해야 한다.

<!-- TOC 플러그인 옵션 -->
<script>
  window.RPPlugins = {
    toc: {
      levels: [2, 3, 4, 5], // 목차에 포함할 제목 레벨 (기본값 2, 3, 4)
      headerOffset: 64, // 화면 상단 부터 제목까지의 여백 (기본값 84)
    },
  };
</script>

<!-- TOC 플러그인 스크립트 -->
<script defer src="https://cdn.jsdelivr.net/gh/romantech/tistory-plugins@latest/dist/toc/index.min.js"></script>

 

플러그인은 다음과 같은 순서로 본문 영역을 탐색한다. 정말 특이한 스킨이 아니라면 아래 셀렉터만으로 무리 없이 찾을 수 있다.

셀렉터	변형 셀렉터
.contents-style	.contents_style
.entry-content	.entry_content
.area-view	.area_view
.post-content	.post_content
.article-view	.article_view
#article
.article-cont	.article_cont

 

스킨 구조가 달라서 본문을 찾지 못하는 경우 셀렉터를 직접 지정할 수 있다.

<script>
  window.RPPlugins = {
    articleSelectors: [".my-article", "#main-content"],
  };
</script>

<script defer src="https://cdn.jsdelivr.net/gh/romantech/tistory-plugins@latest/dist/toc/index.min.js"></script>

 

 

주요 기능

---

색상 모드 자동 전환

데스크톱 TOC는 현재 적용된 블로그 스킨에 맞춰 라이트/다크 모드가 자동으로 전환된다.

왼쪽 라이트 모드, 오른쪽 다크 모드

 

데스크톱 (1280px 이상)

넓은 화면에선 우측에 레일형 목차가 표시된다. 본문에 집중할 수 있도록 평소에는 막대만 보이고, 마우스를 올리면 제목이 함께 나타난다. 현재 읽고 있는 섹션의 레일 막대는 밝게 하이라이트되며, 제목 레벨이 낮아질수록(h2 → h4) 막대 길이가 점점 짧아진다.

 

목차 제목은 기본적으로 한 줄로 표시된다. 긴 제목은 마우스를 올렸을 때 왼쪽 툴팁으로 전체 제목을 보여준다.

 

TOC에서 제목을 클릭하면, 해당 섹션까지 이어지는 레일 막대와 제목이 순차적으로 강조된다.

 

목차 상단이나 하단에 걸쳐 일부만 보이는 제목을 클릭하면, 해당 제목이 잘 보이도록 자동으로 스크롤된다. 제목 수가 많아 목차 패널에 스크롤이 생긴 상황에서 은근히 유용하다. 

 

모바일 (1280px 미만)

💡 아래로 스크롤해서 본문 영역을 벗어나면 목차가 자동으로 사라진다.

 

1280px 미만의 좁은 화면에선 레일형 대신 팝업형 목차를 표시한다. 우측 하단 𑁔 버튼을 누르면 목차 팝업이 나타나고, 제목을 클릭하면 해당 위치로 스크롤되면서 팝업이 자동으로 닫힌다. 모바일 목차는 제목 레벨에 따라 들여쓰기가 적용되어 있어 계층 구조를 쉽게 파악할 수 있다.

 

TOC 버튼은 본문 영역 안에서 위아래로 드래그할 수 있다. 버튼 위쪽에 공간이 부족하면 목차 팝업은 아래 방향으로 열린다.

 

 

기타 플러그인

---

앵커 링크 외에도 인라인 코드, LaTeX(KaTeX) 렌더링 등 스크립트 한 줄만 추가하면 바로 적용할 수 있는 다른 플러그인도 함께 만들었다. 전체 코드와 더 자세한 설명은 GitHub 저장소에서 확인할 수 있다.

 

플러그인	설명
inline-code	벡틱(`)으로 감싼 인라인 텍스트를 <code>로 변환
katex	텍스트 내 수학 수식을 KaTeX로 렌더링
copy-code	코드 블록 우측 상단에 복사 버튼 추가
focus-guard	사이드바 토글 과정에서 발생하는 aria-hidden 포커스 경고 완화
heading-anchor	본문 제목에 앵커 링크를 추가하고 해시 이동 위치 보정