Zola의 핵심 설정 파일: config.toml 이해하기

Zola는 단일 바이너리로 동작하는 고성능 정적 웹사이트 생성기로, 모든 기능이 내장되어 있습니다. 그 중심에는 구성 파일인 config.toml이 있으며, 이 파일을 통해 사이트의 전반적인 동작 방식을 제어할 수 있습니다. 본 문서에서는 이 설정 파일의 주요 항목들을 심층적으로 분석하고, 실제 프로젝트에 적용할 수 있는 예제를 함께 제시합니다.

설정 파일 구조 개요

config.toml은 TOML 형식으로 작성되며, 각 기능별로 명명된 블록으로 구성됩니다. 기본적으로 대부분의 기능은 비활성화 상태이며, 필요 시 해당 섹션에서 활성화해야 합니다.

주요 섹션은 다음과 같습니다:

• 루트 설정 (기본 정보)
• [markdown]: 마크다운 렌더링 옵션
• [link_checker]: 링크 유효성 검사
• [slugify]: URL 슬러그 생성 규칙
• [search]: 검색 인덱스 설정
• [languages]: 다국어 지원
• [extra]: 사용자 정의 데이터

단, base_url는 반드시 지정해야 하는 필수 항목입니다.

기본 사이트 설정

# 필수 항목: 웹사이트의 공개 주소
base_url = "https://myblog.com"

# 사이트 이름 및 설명 (피드 생성에 사용됨)
title = "내 개인 블로그"
description = "Zola로 만든 정적 블로그"

# 기본 언어 설정
default_language = "ko"

빌드 및 출력 설정

# 출력 디렉터리 변경 (기본값: public)
output_dir = "build"

# 출력 폴더 내 점 파일 유지 여부
preserve_dotfiles_in_output = false

# Sass 파일 컴파일 활성화
compile_sass = true

# HTML 최소화 (압축)
minify_html = true

콘텐츠 처리 옵션

# 처리 대상에서 제외할 파일 패턴
ignored_content = [
    "*.log",
    "**/temp/",
    "vendor/**"
]

# 정적 파일 무시 목록
ignored_static = [
    "*.bak",
    ".DS_Store"
]

# 저자 정보
author = "김철수 <kim@example.com>"

마크다운 렌더링 세부 설정

[markdown]
# 이모티콘 표시 여부
render_emoji = true

# 외부 링크 스타일
external_links_class = "ext-link"
external_links_target_blank = true
external_links_no_follow = true

# 스마트 타이핑 (따옴표, 마침표 등 자동 변환)
smart_punctuation = true

# 정의 목록 지원
definition_list = true

# 이미지 지연 로딩 및 비동기 디코딩
lazy_async_image = true

# GitHub 스타일 알림 블록
github_alerts = true

# 제목에 앵커 링크 삽입 위치
insert_anchor_links = "right"

구문 강조 설정

[markdown.highlighting]
# 언어가 없을 때 오류 발생 여부
error_on_missing_language = true

# 스타일 출력 방식: "inline" 또는 "class"
style = "class"

# 테마 지정 (단일)
theme = "dracula"

# 다크 모드/라이트 모드 테마 설정
light_theme = "github-light"
dark_theme = "github-dark"

# 커스텀 언어/테마 파일 추가
extra_grammars = ["syntaxes/custom.lang.json"]
extra_themes = ["themes/dark-mode.json"]

링크 유효성 검사 설정

[link_checker]
# 검사 건너뛸 접두사
skip_prefixes = [
    "http://localhost:8080/",
    "https://127.0.0.1/"
]

# 앵커 링크 검사 생략
skip_anchor_prefixes = [
    "https://developer.mozilla.org/",
    "https://docs.rs/"
]

# 내부 링크 경고 수준
internal_level = "warn"

# 외부 링크 경고 수준
external_level = "error"

URL 슬러그 생성 전략

[slugify]
# 경로 슬러그화: "on", "safe", "off"
paths = "on"

# 카테고리/태그 슬러그화
taxonomies = "on"

# 앵커 슬러그화
anchors = "on"

# 날짜 부분 유지 여부
paths_keep_dates = false

설명:

• on: ASCII 문자만 허용, 특수문자 제거
• safe: 운영체제 제약 사항만 제거
• off: 원본 문자 그대로 사용 (권장하지 않음)

검색 기능 구성

[search]
include_title = true
include_description = true
include_date = false
include_path = false
include_content = true
truncate_content_length = 250
index_format = "elasticlunr_javascript"

분류 시스템 설정

taxonomies = [
    {name = "tags", feed = true},
    {name = "categories", paginate_by = 12},
    {name = "authors"}
]

# 분류 경로 기본값
taxonomy_root = "articles"

실제 프로젝트 적용 예제

base_url = "https://techjournal.example.com"
title = "기술 일기장"
description = "Zola 기반의 개발자 블로그"
default_language = "ko"
compile_sass = true
minify_html = true
generate_feeds = true
feed_filenames = ["rss.xml", "atom.xml"]
feed_limit = 15
build_search_index = true

taxonomies = [
    {name = "tags", feed = true},
    {name = "categories", paginate_by = 10}
]

[markdown]
render_emoji = true
smart_punctuation = true
github_alerts = true
insert_anchor_links = "right"
lazy_async_image = true

[markdown.highlighting]
theme = "monokai"
error_on_missing_language = true

[search]
include_title = true
include_description = true
include_content = true
truncate_content_length = 300

[link_checker]
external_level = "warn"
skip_prefixes = ["http://localhost:1313/"]

[extra]
author = {name = "개발자 김", email = "dev@korea.com"}
social = {
    github = "https://github.com/devkim",
    linkedin = "https://linkedin.com/in/devkim"
}

다국어 지원 구성

default_language = "ko"

[languages]
[languages.en]
title = "My Tech Blog"
description = "A static blog powered by Zola"
taxonomies = [
    {name = "authors"},
    {name = "tags"}
]

[languages.ja]
title = "技術ブログ"
description = "Zolaで構築された静的ブログ"

테마 선택 및 적용

# 기본 테마 지정
theme = "anpu"

# 또는 커스텀 테마 사용 가능
# theme = "custom-theme"

최적화 및 보안 설정 팁

환경별 설정 관리

zola build --config config.production.toml
zola serve --config config.development.toml

성능 최적화

minify_html = true
hard_link_static = true  # 같은 파일 시스템 내에서 하드링크 사용

보안 강화

[markdown]
external_links_target_blank = true
external_links_no_follow = true

문제 해결 가이드

• 설정이 반영되지 않는 경우 → 파일 경로 확인 (project-root/config.toml) → TOML 문법 검증 (https://www.tomalint.com/) → 섹션 이름 오류 확인 (예: [markdown] vs [markdown.highlighting]) → 개발 서버 재시작

• 불필요한 파일 처리 방지

ignored_content = ["**/.git/**", "**/node_modules/**"]
ignored_static = ["*.tmp", "*.log"]

결론

Zola의 config.toml은 유연하면서도 강력한 설정 시스템을 제공합니다. 본 문서를 통해 각 항목의 역할과 실제 적용 방법을 이해했다면, 이제 자신만의 정적 사이트를 효과적으로 구성할 수 있을 것입니다. 다양한 기능을 조합하여 블로그, 포트폴리오, 문서 사이트 등을 손쉽게 구현할 수 있습니다.

공식 문서 참조:

이제 당신의 웹 경험을 시작해보세요.