Hugo PaperMod 테마에서 **TOC(Table of Contents)**를 설정하면서 삽질을 좀 해서.. 관련된 내용을 글로 적어봅니다.

이글에서는 특히 우측 사이드바에 따라다니는 목차를 만드는 방법과, 개발 블로그에 최적화된 TOC 설정을 중점적으로 다룹니다.

TOC가 뭔가요?

TOC는 Table of Contents의 줄임말로, 긴 문서에서 각 섹션의 제목들을 목차 형태로 보여주는 기능입니다.

블로그를 운영하다 보면 긴 튜토리얼이나 기술 문서를 작성할 때가 많은데, 이런 경우 독자들이 원하는 부분을 쉽게 찾을 수 있도록 도와주는 필수 기능입니다.

사실 이뻐보여서 이 글 누르신 분 꽤 많은거 압니다

PaperMod 테마에는 이 기능이 내장되어 있어서 별도의 플러그인이나 복잡한 설정 없이도 바로 사용할 수 있다는 장점이 있습니다.

TOC의 핵심 장점들

1. 사용자 경험(UX) 향상

독자들이 긴 포스트에서 원하는 정보를 빠르게 찾을 수 있습니다. 특히 이 블로그처럼 개발 같은 주제, 기술을 다루는 튜토리얼이나 가이드 포스트에서 중요한 역할을 합니다.

2. 문서 구조의 시각화

포스트의 전체적인 구조를 한눈에 파악할 수 있어서, 독자들이 어떤 내용이 포함되어 있는지 미리 알 수 있게 해주는 역할도 합니다.

3. 스크롤 효율성

페이지를 끝까지 스크롤하지 않고도 원하는 섹션으로 바로 이동할 수 있습니다.

PaperMod TOC 설정하기

기본 설정 (hugo.toml)

먼저 hugo.toml 파일에서 전역 설정을 해줘야 합니다.:

[params]
  # TOC 기본 설정
  ShowToc = true      # TOC 표시 여부
  TocOpen = true      # 기본적으로 TOC 열기
  TocSidebar = true   # 우측 사이드바에 고정 (중요!)

  # 추가 TOC 옵션들
  ShowReadingTime = true
  ShowShareButtons = true
  ShowPostNavLinks = true

개별 포스트에서 TOC 설정

각 포스트마다 개별적으로 TOC 설정을 할 수도 있습니다:

+++
title = "포스트 제목"
ShowToc = true
TocOpen = true
TocSidebar = true
+++

TOC가 제대로 작동하는 조건들

TOC가 예쁘게 표시되려면 만족해야할 조건들이 있습니다.

1. 충분한 헤딩 구조

당연하지만 최소 2개 이상의 헤딩이 있어야 TOC가 의미있게 작동합니다. 헤딩이 하나뿐이면 TOC가 표시되지 않을 수 있기도 하고, 사실 그런 글에는 TOC같은 목차가 필요가없죠.

2. 적절한 포스트 길이

마찬가지로 너무 짧은 포스트에서는 TOC가 표시되지 않을 수 있습니다. 보통 500자 이상의 긴 포스트에서 효과적입니다.

3. 올바른 헤딩 순서

헤딩은 순서대로 사용해야 합니다. H1 → H2 → H3 → H4 처럼 그냥 순서를 오름차순으로 사용하면 됩니다. 마크다운을 쓰는 컨텐츠라면 # ## ### 이런 식으로 헤딩 마크를 하나씩 늘려가면 되서 간편하죠.

마크다운 헤딩 사용법

헤딩 레벨별 설명

H1 (#) - 메인 제목

# 메인 제목
  • 포스트당 하나만 사용하는 것이 좋습니다.
  • 보통 포스트 제목과 동일하게 설정하는 편입니다

H2 (##) - 주요 섹션

## 주요 섹션 제목
  • 포스트의 주요 내용을 구분할 때 사용합니다.

H3 (###) - 서브 섹션

### 서브 섹션 제목
  • H2 아래에 세부 내용을 나눌 때 사용합니다.
  • 코드 예제나 단계별 설명에 자주 사용합니다.

H4 (####) - 세부 항목

#### 세부 항목 제목
  • H3 아래에 더 세분화할 때 사용합니다.
  • 너무 깊은 레벨은 TOC에서 복잡해 보일 수 있습니다.

개발 블로그에 최적화된 TOC 구조

튜토리얼 포스트 구조 예시

개발 튜토리얼을 작성할 때는 이런 구조로 헤딩을 사용하면 좋습니다:

# React Hooks 완벽 가이드

## 개요
### React Hooks란?
### 왜 Hooks를 사용할까?

## 기본 Hooks
### useState
#### 기본 사용법
#### 복잡한 상태 관리
### useEffect
#### 컴포넌트 마운트/언마운트
#### 의존성 배열 활용

## 커스텀 Hooks
### useCounter 만들기
### useLocalStorage 만들기

## 실전 예제
### Todo 앱 만들기
#### 컴포넌트 구조
#### 상태 관리
#### 이벤트 핸들링

## 주의사항과 팁
### 성능 최적화
### 일반적인 실수들

기술 리뷰 포스트 구조

기술이나 라이브러리를 리뷰할 때는 이런 구조가 좋은 편입니다.:

# Next.js 14 새로운 기능들

## 소개
### Next.js 14의 주요 변경사항
### 마이그레이션 가이드

## 새로운 기능들
### App Router 개선사항
### Server Components
### Streaming SSR

## 성능 개선
### 번들 크기 최적화
### 로딩 성능 향상

## 개발자 경험
### 개발 서버 개선
### 디버깅 도구

## 결론
### 장단점 분석
### 사용 권장사항

TOC 커스터마이징 팁

1. 헤딩 제목 최적화

TOC에서 보일 제목은 항상 명확하고 간결하게:

## 좋은 예시
### useState Hook 사용법
### useEffect로 사이드 이펙트 관리

## 피해야 할 예시
### 이건 너무 긴 제목이라서 TOC에서 보기 어려워요
### 이것도 마찬가지로 너무 길어요

2. 적절한 깊이 유지

너무 깊은 헤딩 구조도 NG 입니다:

# 메인 제목
## 섹션 1
### 서브 섹션 1.1
#### 세부 항목 1.1.1  # 이 정도까지만
##### 너무 깊은 레벨  # 피하기

3. 일관된 네이밍 컨벤션

포스트 전체에서 일관된 스타일의 헤드 네이밍이 사용자가 TOC를 보기 더 좋게 만들어줍니다.:

## 설치 및 설정
## 기본 사용법
## 고급 기능
## 문제 해결
## 결론

실제 TOC 동작 확인하기

이 포스트에서 TOC가 어떻게 작동하는지 확인해보세요

사이드바에 목차가 표시되고, 각 항목을 클릭하면 해당 섹션으로 바로 이동할 수 있습니다. 스크롤할 때도 현재 보고 있는 섹션이 하이라이트되는 것을 확인할 수 있습니다.

TOC 관련 문제 해결

TOC가 표시되지 않는 경우

  1. 헤딩이 충분하지 않은 경우

    • 최소 2개 이상의 헤딩이 있는지 확인
    • H1, H2, H3 등 다양한 레벨을 사용

  2. 설정이 잘못된 경우

    • hugo.toml에서 ShowToc = true 확인
    • 개별 포스트에서 ShowToc = true 확인

  3. 포스트가 너무 짧은 경우

    • 충분히 긴 포스트에서만 TOC가 표시됩니다.

TOC가 제대로 작동하지 않는 경우

  1. 헤딩 순서 문제

    • H1 → H2 → H3 순서로 사용했는지 확인
    • 건너뛰지 않고 순서대로 사용했는지 확인

  2. 특수문자 문제

    • 헤딩에 특수문자가 많으면 링크가 깨질 수 있기 때문에 가능하면 영문과 한글만 사용

TOC 베스트 프랙티스

1. 일관성 유지

모든 포스트에서 비슷한 헤딩 구조를 사용하면 보는 사람이 쉽게 콘텐츠를 탐색할 수 있습니다.

2. 명확한 제목

헤딩 제목만 봐도 내용을 알 수 있어야, 어느 헤드로 이동해야하는지 파악이 가능합니다.

3. 적절한 깊이

너무 깊지도, 너무 얕지도 않은 적절한 깊이를 유지해야 합니다. 보통 3-4레벨 정도가 적당하고, 특히 너무 깊어지면 TOC UI가 이상하게 보일 수 있습니다.

마무리

TOC 기능은 저처럼 기능 블로그를 운영하는 사람에겐 정말 유용한 기능입니다. 특히 긴 튜토리얼이나 기술 문서를 작성할 때 독자들의 경험을 좋게 만들어줍니다.

적절한 헤딩 구조와 설정만 잘 해주면, 별도의 플러그인이나 복잡한 설정 없이도 훌륭한 목차 기능을 사용할 수 있습니다.