블로그 글이 길어질수록 독자는 원하는 정보를 찾기 어려워집니다. 이때 글의 구조를 한눈에 보여주는 TOC(Table of Contents, 목차) 는 매우 유용한 기능입니다. 독자는 목차를 통해 전체 내용을 빠르게 파악하고 원하는 섹션으로 즉시 이동할 수 있어 사용자 경험을 크게 향상시킬 수 있습니다.
Blowfish 테마는 강력한 TOC 기능을 내장하고 있어, 간단한 설정만으로 블로그 글에 목차를 추가할 수 있습니다. 이 글에서는 Blowfish 테마의 기본 TOC 설정부터 사용자의 스크롤에 반응하는 동적 TOC 기능까지 설정하는 방법을 알아보겠습니다.
전체 블로그에 TOC 기본 설정하기#
가장 먼저, 블로그 전체에 TOC를 기본적으로 활성화하는 방법입니다. Hugo 프로젝트의 config/_default 디렉터리에 있는 params.toml 파일을 수정합니다.
[params.article] 섹션에 다음 설정을 추가하거나 수정합니다. 만약 해당 섹션이 없다면 새로 만들어주면 됩니다.
# config/_default/params.toml
[article]
# true로 설정하면 모든 글에 기본적으로 목차가 표시됩니다.
showTableOfContents = true
이 설정 하나만으로 모든 게시물에 목차가 자동으로 생성됩니다.
TOC 상세 설정 (표시할 제목 레벨 조정)#
Blowfish 테마에서는 목차에 표시될 마크다운 제목(heading)의 레벨을 지정할 수 있습니다. 예를 들어, <h2>(##) 부터 <h4>(####) 까지의 제목만 목차에 포함하고 싶을 수 있습니다.
markup.toml 파일의 [tableOfContents] 섹션에서 이를 제어할 수 있습니다.
# config/_default/markup.toml
[tableOfContents]
# 목차 생성을 시작할 제목 레벨 (기본값: 2)
# 2는 <h2>(##)를 의미합니다.
startLevel = 2
# 목차 생성을 마칠 제목 레벨 (기본값: 3)
# 3은 <h3>(###)를 의미합니다.
endLevel = 3
# 목록 항목을 순서 있는 리스트(1., 2., ...)로 표시할지 여부 (기본값: false)
ordered = false
startLevel: 목차에 포함할 가장 상위 제목 레벨입니다.<h2>는 2,<h3>는 3으로 설정합니다.endLevel: 목차에 포함할 가장 하위 제목 레벨입니다.<h4>까지 포함하려면 4로 설정합니다.
이 설정을 통해 너무 상세하거나 불필요한 제목은 목차에서 제외하여 더 깔끔한 TOC를 구성할 수 있습니다.
동적 TOC 기능 활성화하기 (smartTOC)#
Blowfish 테마는 사용자의 스크롤 위치에 따라 현재 읽고 있는 부분의 목차를 하이라이트 해주는 스마트 TOC 기능을 제공합니다. 이는 독자에게 현재 위치를 시각적으로 알려주어 긴 글을 읽을 때 매우 유용합니다.
params.toml 파일의 smartTOC 항목을 확인합니다.
# config/_default/params.toml
# 스마트 TOC 기능 활성화
smartTOC = true
하위 목차 자동 숨기기#
smartTOC를 사용할 때, 글의 구조가 복잡하고 하위 목차가 많으면 TOC 자체가 너무 길어질 수 있습니다. 이때 smartTOCHideUnfocusedChildren 옵션을 사용하면 현재 보고 있는 섹션의 하위 목차만 펼쳐지고, 나머지 비활성 섹션의 하위 목차는 자동으로 접히게 됩니다.
params.toml 파일에 다음과 같이 설정을 추가합니다.
# config/_default/params.toml
smartTOC = true
# 현재 위치가 아닌 다른 섹션의 하위 목차를 숨깁니다.
smartTOCHideUnfocusedChildren = true
이 기능을 사용하면 매우 긴 글에서도 목차를 간결하고 집중도 있게 유지할 수 있습니다.
특정 글에서만 TOC 설정 변경하기 (Front Matter 활용)#
전체 기본 설정을 따르지 않고, 특정 게시물에 대해서만 목차를 표시하거나 숨기고 싶을 때가 있습니다. 이 경우, 해당 마크다운 파일(.md)의 Front Matter 영역에서 개별적으로 제어할 수 있습니다.
Front Matter는 마크다운 문서 최상단에 --- 또는 +++로 둘러싸인 메타데이터 영역을 말합니다.
특정 글에서만 TOC 보이기#
hugo.toml에서 showTableOfContents = false로 설정했더라도, 특정 글에서만 목차를 표시하고 싶다면 해당 글의 Front Matter에 다음을 추가합니다.
---
title: "특정 글 제목"
date: 2025-06-29
showTableOfContents: true
---
여기에 글 내용이 들어갑니다...
특정 글에서만 TOC 숨기기#
반대로 hugo.toml에서 showTableOfContents = true로 설정했지만, 짧은 공지사항과 같이 목차가 필요 없는 글에서는 개별적으로 숨길 수 있습니다.
---
title: "공지사항"
date: 2025-06-29
showTableOfContents: false
---
간단한 공지 내용입니다...
이처럼 Front Matter 설정은 params.toml의 전역 설정보다 우선 적용되므로, 글의 성격에 따라 유연하게 목차를 관리할 수 있습니다.
※ 참조: TOC가 표시되지 않는 경우#
설정을 완료했는데도 목차가 보이지 않는다면 다음을 확인해 보세요.
- 게시물에 마크다운 제목이 있나요? 목차는
##,###와 같은 마크다운 제목 태그를 기반으로 생성됩니다. 본문에markup.toml파일에서[tableOfContents]에 설정된 레벨 범위(startLevel~endLevel)에 해당하는 제목이 하나도 없다면 TOC는 표시되지 않습니다.
간단한 설정으로 블로그의 가독성과 사용자 편의성을 크게 높일 수 있습니다. 지금 바로 여러분의 Hugo Blowfish 블로그에 동적 TOC 기능을 적용해 보세요.