티스토리 목차가 안 나올 때 확인할 5가지

티스토리 자동 목차가 안 보인다면 소제목 태그 → 본문 선택자 → 목차 영역 → JavaScript 로딩 → CSS와 모바일 표시 순서로 확인해 보세요. 목차를 만드는 데 필요한 요소가 빠졌는지, 만들어진 목차가 화면에서 숨겨졌는지를 구분하면 원인을 좁힐 수 있습니다.

안녕하세요, 자바파커입니다. JAVAPARK Dev 스킨에는 본문의 소제목을 모아 목차로 보여 주는 기능이 있습니다. 이번 글에서는 이 스킨의 실제 동작을 기준으로, 자동 목차가 나오지 않을 때 확인할 지점을 정리합니다. 다른 스킨을 사용한다면 본문 클래스명과 목차 생성 조건을 해당 스킨에 맞춰 확인해 주세요.

증상별로 먼저 확인할 곳

보이는 증상	먼저 확인할 곳
특정 글에서만 목차가 안 나옴	소제목 태그와 목차에 포함되는 제목 수
스킨을 바꾼 뒤 모든 글에서 안 나옴	본문 선택자와 목차 HTML 영역
목차 틀은 있는데 목록이 비어 있음	JavaScript 로딩과 실행 오류
PC에서는 보이는데 모바일에서는 안 보임	접힘 상태와 모바일 전용 CSS
우하단 목차 버튼만 안 보임	본문 상단 목차가 화면 안에 있는지

JAVAPARK Dev는 목차에서 제외하는 영역을 뺀 뒤, 대상 소제목이 2개 이상일 때 목차를 만듭니다. 이 숫자는 티스토리 공통 규칙이 아니라 해당 스킨의 구현 조건입니다.

1 소제목이 실제 제목 태그인지 확인하기

글씨를 크게 하거나 굵게 만든 문장은 눈에는 제목처럼 보여도 HTML에서는 일반 문단일 수 있습니다. 자동 목차는 보통 글씨 크기가 아니라 h2, h3 같은 제목 태그를 읽습니다.

<!-- 일반 문단에 굵기만 적용한 경우 -->
<p><strong>설치 방법</strong></p>

<!-- 자동 목차에서 수집할 수 있는 제목 -->
<h2>설치 방법</h2>
<h3>모바일 확인</h3>

티스토리 글쓰기 화면에서 소제목을 선택하고 제목 서식을 적용한 뒤, HTML 모드에서 실제 태그를 확인하세요. JAVAPARK Dev는 h2, h3, h4를 수집하며, 관련 글·태그·댓글 영역의 제목은 제외합니다.

해결 방법: 본문에 필요한 소제목을 제목 서식으로 작성하고, 대상 제목이 2개 이상인지 확인합니다. 분량이 짧은 글이라면 목차를 표시하려고 불필요한 소제목을 늘릴 필요는 없습니다.

2 목차 코드가 실제 본문을 찾는지 확인하기

스킨마다 본문을 감싸는 요소의 이름이 다릅니다. 예전 코드에 .entry-content가 적혀 있다고 해서 새 스킨에서도 같은 구조를 사용하는 것은 아닙니다.

현재 JAVAPARK Dev의 목차 코드는 먼저 #article-view를 찾고, 그 안에서 .entry-content h2, .entry-content h3, .entry-content h4와 일치하는 제목을 수집합니다. 따라서 본문 요소와 제목 선택자가 모두 실제 HTML에 맞아야 합니다.

PC 브라우저에서 공개 글을 연 뒤 개발자 도구의 Elements 탭에서 본문 구조를 확인하세요. Console 탭에서는 다음 코드로 제목 개수를 읽어 볼 수 있습니다. 아래 코드는 페이지를 수정하지 않습니다.

(() => {
  const content = document.querySelector('#article-view');
  const selector = '.entry-content h2, .entry-content h3, .entry-content h4';
  const exclude = '.another_category, .related-articles, .tags, .comments';
  const headings = content
    ? [...content.querySelectorAll(selector)]
        .filter(h => !h.closest(exclude))
    : [];

  console.log({
    bodyFound: Boolean(content),
    headingCount: headings.length,
    tocFound: Boolean(document.querySelector('#toc')),
    tocListFound: Boolean(document.querySelector('#toc .toc-list'))
  });
})();

bodyFound: false라면 본문 ID가 다르거나 글 상세 페이지가 아닌 화면에서 실행한 경우를 먼저 살펴봅니다. bodyFound: true인데 headingCount: 0이면 소제목 태그, 제목 선택자, 제외 영역을 확인하세요. 결과가 1이라면 이 스킨의 목차 생성 조건에 미달합니다.

다른 스킨에서는 #article-view와 selector를 해당 스킨의 구조에 맞게 바꿔야 합니다. MDN의 querySelectorAll 설명처럼, 선택자에 일치하는 요소가 없으면 빈 목록이 반환됩니다.

3 목차 HTML 영역이 함께 들어 있는지 확인하기

제목이 있어도 목록을 넣을 공간이 없으면 목차가 만들어지지 않습니다. JAVAPARK Dev는 id="toc"인 요소를 찾고, 내부의 .toc-list에 목록을 넣습니다.

<!-- 목차 영역의 핵심 구조를 단순화한 예시 -->
<nav id="toc" class="toc" aria-label="본문 목차">
  <div class="toc-header">
    <span>목차</span>
    <button type="button" class="toc-toggle" aria-label="목차 접기 또는 펼치기">
      접기 또는 펼치기
    </button>
  </div>
  <ol class="toc-list"></ol>
</nav>

위 코드는 구조를 이해하기 위한 예시입니다. 실제 적용할 때는 사용하는 버전의 스킨 HTML을 기준으로 복원하세요. 목차 영역을 글마다 본문에 붙여 넣으면 중복 ID가 생길 수 있으므로, 스킨에서 글 상세 페이지에 한 번 출력되는지 확인합니다.

해결 방법: 2번 진단 결과에서 tocFound와 tocListFound를 확인합니다. 없는 요소가 있다면 스킨 HTML에서 해당 영역을 찾아 복원하세요. 스킨을 업데이트할 때는 HTML, CSS, JavaScript가 서로 호환되는 버전인지 함께 확인합니다.

4 JavaScript 파일과 실행 시점을 확인하기

본문과 목차 영역이 모두 있는데 목록이 비어 있다면 JavaScript 파일이 정상적으로 로드되고 실행됐는지 살펴봅니다.

1. 공개 글에서 개발자 도구의 Network 탭을 열고 페이지를 새로고침합니다.
2. 사용하는 스킨의 목차 스크립트 파일을 찾습니다. JAVAPARK Dev에서는 script.js입니다.
3. 404나 요청 차단이 있는지, 응답 내용이 실제 JavaScript인지 확인합니다.
4. Console 탭에 오류가 있다면 목차 코드가 들어 있는 파일과 발생 위치를 확인합니다.

200 응답은 파일을 받았다는 뜻입니다. 목차 함수가 끝까지 실행됐다는 뜻은 아니므로 Console 오류도 함께 봐야 합니다. 별개의 광고 스크립트 오류가 있다고 해서 목차 오류의 원인으로 바로 단정하지는 마세요.

또한 본문 HTML이 만들어지기 전에 목차 코드가 실행되면, 찾으려는 요소가 아직 없을 수 있습니다. 직접 구현하는 경우에는 아래처럼 실행 시점을 나눌 수 있습니다.

// initTOC는 이보다 앞에서 정의한 목차 생성 함수입니다.
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', initTOC);
} else {
  initTOC();
}

이 패턴은 현재 JAVAPARK Dev에도 적용돼 있습니다. 기존 스킨에 같은 초기화 코드를 덧붙이면 이벤트나 목차가 중복될 수 있으므로 먼저 기존 코드를 확인하세요. 본문을 나중에 불러오는 스킨은 본문 삽입 후에 초기화하는 처리도 필요합니다. DOMContentLoaded 동작 설명

5 목차가 접혀 있거나 CSS로 숨겨졌는지 확인하기

개발자 도구에서 .toc-list 안에 목록 항목이 있다면 생성은 된 것입니다. 이때는 CSS와 접힘 상태를 확인합니다.

현재 JAVAPARK Dev는 모바일 너비에서 .mobile-collapsed 클래스를 붙여 목차 목록을 기본으로 접습니다. 우선 목차의 펼치기 버튼을 눌러 보세요. 우하단 플로팅 버튼은 상단 목차가 스크롤로 화면 위쪽을 벗어난 뒤에 나타납니다.

버튼을 눌러도 보이지 않으면 Elements 탭의 Computed 항목에서 목차와 상위 요소를 확인합니다.

• display: none 또는 visibility: hidden이 적용됐는지
• 높이 제한이나 overflow: hidden으로 목록이 잘렸는지
• 다크모드에서 글자색과 배경색이 비슷해졌는지
• 모바일 전용 미디어 쿼리가 기존 스타일을 덮어썼는지

해결 방법: 목록을 숨기는 정확한 규칙을 찾아 수정합니다. .toc-list { display: block !important; }처럼 무조건 노출시키면 정상적인 접기 기능까지 깨질 수 있으므로, 실제 적용된 클래스와 CSS부터 확인하세요.

수정한 뒤 공개 글에서 확인할 항목

스킨 미리보기뿐 아니라 공개 글 주소에서 PC와 모바일을 각각 확인합니다. 오래된 파일이 의심된다면 개발자 도구를 연 상태에서 캐시를 비활성화하고 다시 불러와 보세요.

1. 소제목이 충분한 글에서 목차 목록이 생성되는가?
2. 목차 항목을 누르면 해당 소제목으로 이동하는가?
3. 모바일에서 접기와 펼치기가 동작하는가?
4. 관련 글이나 댓글 제목이 목차에 섞이지 않는가?
5. 스킨의 나머지 메뉴와 화면도 정상적으로 동작하는가?

수정 전에는 사용하는 스킨을 보관하거나 파일을 백업해 두세요. 한 항목씩 바꾸고 같은 글에서 다시 확인하면 어떤 수정이 효과가 있었는지 구분하기 쉽습니다.

자주 묻는 질문

글씨를 크게 했는데도 목차에 안 들어가는 이유는 무엇인가요

크게 보이는 글씨가 실제로는 p나 span일 수 있습니다. HTML 모드에서 사용하는 목차 코드가 수집하는 제목 태그인지 확인하세요.

소제목이 하나면 목차가 나오지 않나요

현재 JAVAPARK Dev는 제외 영역을 뺀 대상 소제목이 2개 이상이어야 목차를 만듭니다. 다른 스킨의 최소 개수는 다를 수 있습니다.

목차를 추가하면 검색 순위가 올라가나요

목차가 있다는 이유만으로 검색 순위가 올라간다고 단정할 수는 없습니다. 긴 글에서 필요한 부분을 찾기 쉽게 만드는 것이 주된 역할입니다. 구글도 이상적인 제목 태그 개수가 정해져 있지는 않다고 설명합니다. 구글 SEO 기본 가이드

함께 읽으면 좋은 글

• JAVAPARK Dev v1.2 목차와 플로팅 네비게이션 소개
• 티스토리 스킨 JAVAPARK Dev v1.6 글 찾기 기능 소개
• 티스토리 203개 글 점검에서 수정한 H1과 모바일 UX