[티스토리 꾸미기] Toc-bot을 활용한 동적 목차 만들기

0. SKIN 환경 이해 🧠

내가 사용 중인 apricot skin#3은 최신 스킨 답게 화면이 grid로 작성되어 있다.

전체 화면을 나타내는 wrap이란 클래스는 위와 같이 4등분 되어있다. 이러한 형태를 grid라고 한다. grid-template-areas 속성을 보면, "header header" "aside main" 과 같이 적혀 있는데, 같은 쌍따옴표에 들어가 있는 덩어리끼리 같은 행에 배치된다. "",""끼리는 차례대로 다음 행에 배치됨을 볼 수 있다. 위를 보면 header가 2번 적힌 것을 볼 수 있는데, 이는 행 자체를 셀병합처럼 다 차지하겠다는 뜻이다.

몇 번을 시도 했으나, 위와 같이 grid가 짜여진 상황에서 aside 밑에 다른 목차 용 div를 만들어서 운용하기란 쉽지 않았다. 분명 grid의 aside 자리에 사이드바, 목차 통합 div를 넣는다면 해결될 문제였지만, 대공사가 될 것 같아서, aside 안에 목차를 넣는 것으로 결정했다.

1. import toc-bot CDN 📦

편리의 시대답게 side 목차를 위한 CDN 또한 존재한다.

Tocbot CDN
여기서

<script src="https://cdnjs.cloudflare.com/ajax/libs/tocbot/4.30.0/tocbot.min.js"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tocbot/4.30.0/tocbot.css">

위 CDN의 최신 버전을 가져오면 된다. CSS를 직접 처리할 분은 CSS는 가져오지 않아도 된다.

나는 CSS를 따로 만들거라 script만 추가했다.

2. 적절한 위치에 div 태그 넣기 💾

이제 해당 CDN이 표현될 div를 적절한 위치에 넣어줘야 하는데, 나의 경우 0번에서 확인 했듯이 Grid 형태로 Sidebar 영역이 따로 있어서 그 부분 밑에 넣어주면 되었다. 다른 skin을 활용하는 분들은 f12를 통해 적절한 위치를 확인하고 html 편집을 진행 하시길 바란다.

          <!-- 목차 (content) -->
        <div class="toc-container">
                <ul id="toc">
                        <!-- toc-bot을 이용하여 생성되는 목차 항목이 들어감 -->
                </ul>
        </div>

이제 저 ul 태그의 자식 태그로 h1,h2,h3으로 적힌 마크다운 문장이 동적으로 들어갈 것이다.

3. 동적 목차 완성을 위한 javascript 작성 ✍🏻

toc-bot CDN 공식 홈페이지를 보면,

tocbot.init({
  // Where to render the table of contents.
  tocSelector: '.js-toc',
  // Where to grab the headings to build the table of contents.
  contentSelector: '.js-toc-content',
  // Which headings to grab inside of the contentSelector element.
  headingSelector: 'h1, h2, h3',
  // For headings inside relative or absolute positioned containers within content.
  hasInnerContainers: true,
});

위와 같이 적혀있다. 인수를 하나씩 살펴보면,

• tocSelector: 목차로 쓰이는 요소의 가장 겉부분 태그
• contentSelector: 목차의 내용으로 적힐 본문의 가장 겉부분 tag
• headingSelector: 목차로 특정지을 요소
• hasInnerContainers: heading 태그가 본문 내의 특정 섹션이나 독립된 컨테이너에 들어가 있어도 찾아내서 목차에 집어넣을 것인지를 boolean 값으로 받는다. 기본값은 false이다.

내 경우에는 다음과 같이 될 것이다.

                    tocbot.init({
                            tocSelector: '#toc',
                            contentSelector: '.article-entry',
                            headingSelector: 'h1, h2, h3',
                            hasInnerContainers: true
                    });

사실 이것만 <sript> </script> 태그 사이에 넣어도 목차가 나오긴 나온다. 하지만 목차를 눌렀을 때, 해당 위치로 가는기능과 현재 읽고 있는 섹션의 제목을 목차에서 따로 표시하는 기능은 표현하지 못한다. 만약 해당 기능들을 넣고 싶다면 다음과 같이 업그레이드 하면 된다.

4. 생성되는 기본적인 TOC-BOT 확인 🧐

<!-- 목차 (content) -->        
<div class="toc-container">                
    <ul id="toc">                        
        <!-- toc-bot을 이용하여 생성되는 목차 항목이 들어감 -->                
    </ul>        
</div>

위와 같은 div가 블로그 구동 시 다음과 같이 변한다.

#toc 안에 .toc-list, .toc-list-item .is-active-li,.toc-link node-name--H1 등이 되어있다. 사실 이건 구현을 마친 후라 그렇지, 하늘색 화살표 부분에 .is-active-link라는 클래스도 모든 li 안의 a 태그에 들어간다. 즉 모든 태그가 active-link 취급 받는게 기본 값이라는 것이다.
또한 a 태그가 가르키는 주소가 모두 #으로 처리되어 있어. 해당 목차를 눌러도 원하는 위치에 가지 않는다. 따라서,

• 모든 a 태그에 .is-active-link 지우기
• 모든 a 태그가 각자 가리키는 header의 주소를 href로 가르키기

를 javascript로 구현해야한다. 전체 코드와 그에 대한 주석으로 설명을 대신한다.

5. 동적 효과를 위한 javascript 전체 👨‍💻

<!-- toc-bot 스크립트 추가 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/tocbot/4.30.0/tocbot.min.js" defer></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
            // 1) DOM을 활용하여, 본문과 목차 태그를 클래스를 통해 가져오기
            const articleEntry = document.querySelector(".article-entry");
            const tocContainer = document.querySelector(".toc-container");

            // 2) article-entry가 존재하고, h1, h2, h3가 있는 경우에만 목차를 block으로 보이게 함.
            // tocContainer의 CSS 기본값은 display: none;으로 설정해둔 상태
            if (articleEntry && articleEntry.querySelector("h1, h2, h3")) {
                    tocContainer.style.display = "block";

                    // 3) 모든 헤딩 태그에 고유한 ID를 할당
                    const headings = articleEntry.querySelectorAll('h1, h2, h3');
                    headings.forEach((heading, index) => {
                        if (!heading.id) {
                            heading.id = 'heading-' + index;
                        }
                    });

                    // 4) 목차 생성
                    tocbot.init({
                            tocSelector: '#toc',
                            contentSelector: '.article-entry',
                            headingSelector: 'h1, h2, h3',
                            hasInnerContainers: true
                    });

                    // 5) Intersection Observer를 이용하여 강조 태그 전부 지우고, 위치에 맞게 적절히 추가
                    const tocLinks = document.querySelectorAll('.toc-link');

                    const observer = new IntersectionObserver((entries) => {
                            entries.forEach(entry => {
                                    if (entry.isIntersecting) {
                                            // 5-1) 모든 링크에서 강조 클래스 제거
                                            tocLinks.forEach(link => link.classList.remove('is-active-link'));

                                            // 5-2) 현재 보이는 헤더에 해당하는 링크를 강조
                                            const id = entry.target.getAttribute('id');
                                            const activeLink = document.querySelector(`.toc-link[href="#${id}"]`);
                                            if (activeLink) {
                                                    activeLink.classList.add('is-active-link');
                                            }
                                    }
                            });
                    }, {
                            root: null, // 뷰포트를 기준으로 감시
                            threshold: 0.1 // 헤더가 10% 이상 보일 때 감지
                    });

                    headings.forEach((heading) => {
                            observer.observe(heading);
                    });

                    // 6) 목차 항목 클릭 시 부드럽게 스크롤 이동
                    tocContainer.addEventListener('click', function(event) {
                            if (event.target.classList.contains('toc-link')) {
                                    event.preventDefault();
                                    const targetId = event.target.getAttribute('href').substring(1);
                                    const targetElement = document.getElementById(targetId);
                                    if (targetElement) {
                                            window.scrollTo({
                                                    top: targetElement.offsetTop,
                                                    behavior: 'smooth'
                                            });
                                    }
                            }
                    });
            } else {
                    // 7) article-entry가 없거나 h1, h2, h3가 없으면 목차 숨기기 
                    // 본문글 외의 다른 페이지에서는 쓸데없이 목차가 랜더링 되는 것을 막기 위함.
                    if (tocContainer) {
                            tocContainer.style.display = "none";
                    }
            }
    });
</script>

6. CSS 추가 ➕

나는 내 skin에 맞는 형태로 만들었다. 각자 원하는 CSS를 GPT와 논의해 멋지게 완성하길 바란다.

/* ───────────────────────────────────────────────────────── */
/* 사이드바 내 목차 */
/* ───────────────────────────────────────────────────────── */

.toc-container {
  display: none; /* 기본적으로 숨겨진 상태, script에서 필요 시 표시 */
  width: 100%;
  margin-top: 20px;
  padding: 15px;
  background-color: var(--content-background-color);
  border-radius: var(--s-border-radius);
  box-shadow: 0px 2px 4px 0px var(--shadow-color);
}

.toc-container ul {
  list-style: none;
  padding-left: 0;
  text-align: left;
}

.toc-container li {
  margin-bottom: 8px;
  font-family: "Pretendard", sans-serif;
}

.toc-container a {
  text-decoration: none;
  color: var(--font-color);
  font-weight: 500;
}

.toc-container a:hover {
  text-decoration: underline;
}

.toc-link {
    color: #444;
    text-decoration: none;
    font-weight: 500;
    transition: color 0.3s;
}

.toc-link:hover {
    color: #000;
    text-decoration: underline;
}

.toc-link.is-active-link {    /* 현재 보고 있는 목차를 강조 */
  color: #FF6969; 
  font-weight: bold;
  padding-left: 2px; 
  transition: color 0.3s;
}

7. 결과물 ✅

8. 소회 💭

소모시간 3시간 반 정도 걸린 것 같다. GPT를 활용 했는데, 원하는 요구사항을 한 번에 말하니 오히려 역효과만 났다. 단계 별로 차근차근 묻는 것이 코드 작성에 도움이 되었다. 나의 경우 aside 안에 목차를 넣어서 목차의 css에 position: sticky를 넣지 않았고, aside의 css에 추가했다.