Ghost 블로그 자동 목차 코드: 플러그인 없이 가독성 높이기

💡 기술 가이드 안내: 본 글은 Ghost 블로그의 코드 인젝션(Code Injection) 기능을 활용하는 기술 튜토리얼입니다. 적용 전 사용 중인 테마의 구조를 확인해야 할 수 있으며, 다른 스크립트와 충돌이 발생할 가능성이 있습니다. 적용 후에는 반드시 정상 작동 여부를 확인하시기 바랍니다.

긴 호흡의 기술 포스팅이나 상세한 정보 글은 독자가 원하는 내용을 찾기 전에 쉽게 이탈하는 경향이 있습니다. 스크롤의 압박을 느끼는 독자는 뒤로가기 버튼을 누르기 쉽고, 이는 블로그의 이탈률을 높이는 주요 원인이 됩니다.

이 문제를 해결하는 가장 효과적인 방법은 글 상단에 자동 생성 목차(Table of Contents, TOC) 를 제공하는 것입니다. 목차는 독자에게 글의 전체 구조를 한눈에 보여주고, 원하는 섹션으로 즉시 이동할 수 있게 하여 사용자 경험(UX)을 획기적으로 개선합니다.

이 글에서는 별도의 플러그인 설치 없이, Ghost 블로그의 코드 인젝션 기능과 간단한 자바스크립트 코드만으로 세련된 자동 목차를 구현하는 방법을 단계별로 안내합니다.

1. 왜 Ghost 블로그에 자동 목차가 필요한가요?

자동 목차는 단순한 편의 기능을 넘어 블로그의 성과에 직접적인 영향을 미칩니다.

• 이탈률 감소: 독자가 글의 전체 구성을 파악하고 원하는 정보에 빠르게 접근할 수 있어 이탈 가능성이 줄어듭니다.
• 체류 시간 증가: 흥미로운 소제목을 발견하고 해당 부분으로 바로 이동하며 글을 더 오래 읽게 됩니다.
• SEO 개선: 구글 등 검색엔진은 잘 구조화된 콘텐츠를 선호합니다. 목차는 검색엔진이 글의 구조를 이해하는 데 도움을 주며, 검색 결과에 'Jump to' 링크가 표시될 확률을 높입니다.
• 전문성 향상: 잘 정리된 목차는 블로그의 전문성과 신뢰도를 높여주는 시각적 장치입니다.

수동으로 목차 링크를 만드는 것은 글을 수정할 때마다 번거로운 작업이 되지만, 자동화 스크립트를 사용하면 이러한 모든 이점을 손쉽게 얻을 수 있습니다.

2. 자동 목차(TOC) 구현을 위한 2가지 필수 확인 사항

코드를 적용하기 전, 두 가지 핵심 개념을 이해해야 합니다.

1. 코드 인젝션(Code Injection) 기능: Ghost 관리자 메뉴(Settings > Code Injection)에서 제공하는 기능입니다. 블로그 테마 파일을 직접 수정하지 않고도 사이트 전체의 헤더(Header)나 푸터(Footer)에 HTML, CSS, JavaScript 코드를 안전하게 추가할 수 있습니다.
2. HTML 본문 선택자(.gh-content): 스크립트가 목차를 생성하기 위해 글의 본문 영역을 찾는 기준점입니다. Ghost의 기본 테마(Casper 등)는 본문을 .gh-content라는 CSS 클래스로 감싸고 있습니다. 만약 커스텀 유료/무료 테마를 사용 중이라면 이 클래스명이 .post-content, .single-content 등으로 다를 수 있으므로, 반드시 확인 후 코드의 해당 부분을 수정해야 합니다.

💡 Tip: 내 테마의 본문 선택자(Selector) 찾는 법내 블로그의 아무 글이나 접속합니다.본문 영역에 마우스 오른쪽 버튼을 클릭하고 '검사(Inspect)'를 선택하여 개발자 도구를 엽니다.개발자 도구의 Elements 탭에서 본문 전체를 감싸고 있는 태그(보통 <article> 또는 <div>)를 찾습니다.해당 태그의 class="클래스명" 부분을 확인합니다. 예를 들어 class="post-full-content" 라면, .post-full-content가 바로 당신의 본문 선택자입니다.

3. Ghost 블로그 자동 목차 코드 적용 방법 (단계별 가이드)

이제 실제 코드를 적용해 보겠습니다. 아래 단계를 차근차근 따라오세요.

3.1. 1단계: Code Injection 메뉴 접근

Ghost 관리자 페이지에 로그인한 후, 왼쪽 메뉴에서 톱니바퀴 모양의 Settings 아이콘을 클릭합니다. 그다음 Code Injection 메뉴로 이동합니다.

3.2. 2단계: Site Footer에 코드 붙여넣기

Code Injection 페이지에는 Site Header와 Site Footer 두 개의 입력창이 있습니다. 스크립트는 페이지 로딩 속도에 영향을 덜 주도록 Site Footer 영역에 삽입하는 것이 좋습니다.

아래 코드를 전체 복사하여 Site Footer 입력창에 붙여넣고, 오른쪽 상단의 Save 버튼을 누릅니다.

<script>
document.addEventListener('DOMContentLoaded', function() {
  // 1. 본문 영역 선택 (테마에 따라 '.post-content' 등으로 변경 필요)
  const content = document.querySelector('.gh-content');
  if (!content) return;

  // 2. 목차를 생성할 헤딩 태그(h2, h3) 추출
  const headings = content.querySelectorAll('h2, h3');
  if (headings.length < 3) return; // 제목이 3개 미만이면 목차를 생성하지 않음

  let tocHTML = '<nav class="toc"><h3>📋 목차</h3><ul>';

  headings.forEach(function(heading) {
    // 3. 제목 텍스트 기반으로 Anchor ID 생성 (한글 지원)
    const id = heading.textContent
      .trim()
      .toLowerCase()
      .replace(/[^\w\s가-힣-]/g, '') // 특수문자 제거
      .replace(/\s+/g, '-');         // 공백을 하이픈으로 변경
    
    heading.id = id;
    
    // 4. H3 태그일 경우 들여쓰기 스타일 적용
    const indent = heading.tagName === 'H3' ? ' style="margin-left:20px"' : '';
    tocHTML += `<li${indent}><a href="#${id}">${heading.textContent}</a></li>`;
  });

  tocHTML += '</ul></nav><hr>';

  // 5. 첫 번째 H2 태그 바로 앞에 목차 삽입
  const firstH2 = content.querySelector('h2');
  if (firstH2) {
    firstH2.insertAdjacentHTML('beforebegin', tocHTML);
  } else {
    content.insertAdjacentHTML('afterbegin', tocHTML);
  }
});
</script>

<style>
/* 6. 목차 디자인 설정 */
.toc {
  background: #f8f9fa;
  border: 1px solid #e1e4e8;
  border-radius: 8px;
  padding: 20px;
  margin-bottom: 30px;
  font-size: 0.95rem;
}
.toc h3 {
  margin-top: 0;
  font-size: 1.1rem;
}
.toc ul {
  list-style: none;
  padding-left: 0;
  margin: 0;
}
.toc li {
  margin: 8px 0;
}
.toc a {
  text-decoration: none;
  color: #0366d6;
  transition: color 0.2s;
}
.toc a:hover {
  text-decoration: underline;
  color: #0056b3;
}
</style>

3.3. 3단계: 코드 핵심 원리 분석

위 코드가 어떻게 작동하는지 이해하면 필요시 직접 수정할 수 있습니다.

기능	코드 설명
한글 ID 생성	replace(/[^\w\s가-힣-]/g, '') 구문이 한글 제목의 특수문자를 제거하고 공백을 하이픈(-)으로 바꿔, 깨끗한 URL 앵커(#)를 만듭니다.
계층 구조 시각화	H3 태그로 생성된 목차 항목에는 왼쪽 여백(margin-left: 20px)을 주어 H2 항목보다 한 단계 들어간 것처럼 보이게 합니다.
지능적인 삽입 위치	글 최상단이 아닌, 첫 번째 H2 태그 바로 위에 목차를 삽입합니다. 이를 통해 글의 서론(Introduction) 다음에 목차가 자연스럽게 위치하게 됩니다.
최소 조건 설정	h2, h3 태그가 3개 미만인 짧은 글에는 목차가 불필요하다고 판단하여 자동으로 생성하지 않습니다.

🎨 간단한 코드 커스터마이징

제공된 코드는 약간의 수정만으로 디자인을 쉽게 바꿀 수 있습니다.

• 목차 제목 변경: <h3>📋 목차</h3> 부분의 '목차'를 'Contents', 'Index' 등으로 변경할 수 있습니다.
• 배경색 변경: <style> 태그 안의 .toc 부분에서 background: #f8f9fa;의 색상 코드를 원하는 색으로 바꾸세요.
• 링크 색상 변경: .toc a 부분의 color: #0366d6; 값을 변경하여 블로그 테마와 어울리는 색으로 맞출 수 있습니다.

4. 심화: 목차 기능 업그레이드 아이디어

기본 기능에 만족하지 못한다면, 아래 아이디어를 통해 목차를 더욱 강력하게 만들 수 있습니다.

• 스크롤 추적 기능: Intersection Observer API를 사용하면, 사용자가 스크롤할 때 현재 읽고 있는 부분에 해당하는 목차 항목을 하이라이트하여 시각적인 피드백을 줄 수 있습니다.
• 사이드바 고정 목차: CSS의 position: sticky 속성을 활용하면, 스크롤을 내려도 목차가 화면 한쪽에 계속 따라다니는 'Sticky TOC'를 구현하여 접근성을 높일 수 있습니다.

5. 적용 전 반드시 확인할 주의사항

코드를 적용한 후에는 반드시 아래 사항을 점검하여 예기치 않은 문제를 방지하세요.

• 스크립트 충돌 확인: 다른 자바스크립트 라이브러리(예: 댓글 플러그인, 광고 스크립트)와 충돌이 발생할 수 있습니다. 블로그 글에 접속한 뒤 키보드의 F12 키를 눌러 개발자 도구를 열고, Console 탭에 빨간색 에러 메시지가 없는지 확인하세요.
• 모바일 가독성 점검: PC에서는 멋지게 보이던 목차가 모바일 화면에서는 깨지거나 너무 많은 공간을 차지할 수 있습니다. 스마트폰으로 직접 접속하여 margin, padding, font-size 등의 CSS 값을 미세 조정하세요.
• 테마 업데이트 영향: 코드 인젝션은 테마 업데이트 시에도 유지되지만, 만약 테마 개발자가 본문 선택자(.gh-content)의 클래스명을 변경하면 목차가 보이지 않게 될 수 있습니다. 이 경우 코드의 선택자 부분만 수정하면 됩니다.

6. 자주 묻는 질문 (FAQ)

Q1: 이 방법을 사용하려면 별도의 플러그인을 설치해야 하나요?
A1: 아니요, 이 방법은 Ghost의 내장 기능인 'Code Injection'을 사용하므로 별도의 플러그인 설치가 전혀 필요 없습니다.

Q2: 제 커스텀 테마에서는 목차가 보이지 않습니다. 어떻게 해야 하나요?
A2: 사용 중인 테마의 본문 영역 CSS 클래스명이 .gh-content가 아닐 가능성이 높습니다. 위에 안내된 '내 테마의 본문 선택자 찾는 법'을 참고하여 실제 클래스명을 확인하고, 스크립트의 document.querySelector('.gh-content') 부분을 해당 클래스명으로 수정해야 합니다.

Q3: 글에 소제목이 몇 개 이상 있어야 목차가 생성되나요?
A3: 제공된 스크립트는 H2, H3 태그가 합쳐서 3개 이상일 때만 목차를 생성하도록 설정되어 있습니다. 이 기준은 코드의 if (headings.length < 3) return; 부분의 숫자를 변경하여 조절할 수 있습니다.

---