설정

모든 사이트 설정은 프로젝트 루트의 config.toml에 있습니다.

최상위 키에 오타가 있으면 조용히 무시하지 않고 경고합니다. [markdonw]나 titel = "…" 같은 오타는 아무 안내 없이 기능을 꺼버리기 때문입니다. 실제 키와 비슷하면 다음처럼 후보를 함께 알려줍니다.

Unknown key 'markdonw' in config.toml — hwaro does not read it. Did you mean 'markdown'?

이 검사는 최상위 키만 대상으로 하며, 섹션 안에 중첩된 키는 각 섹션의 로더가 검증합니다.

사이트 설정

title = "My Site"
description = "Site description for SEO"
base_url = "https://example.com"

환경 변수

config.toml에서 환경 변수를 참조할 수 있습니다. 값은 TOML 파싱 전에 치환됩니다.

base_url = "${SITE_URL}"
title = "$SITE_TITLE"
description = "${SITE_DESC:-My awesome site}"

기본값 없이 누락된 변수는 그대로 남고 빌드 경고가 발생합니다. 템플릿에서의 사용법은 환경 변수를 참고합니다.

빌드 옵션

[build]
output_dir = "public"
drafts = false
parallel = true
cache = false
hooks.pre = ["npm install", "npx tsc"]
hooks.post = ["npm run minify"]

오류 처리와 활용 사례는 빌드 훅을 참고합니다.

마크다운

[markdown]
safe = false
lazy_loading = true
emoji = true
footnotes = true
task_lists = true
definition_lists = true
mermaid = false
math = false
math_engine = "katex"

문법 상세와 예시는 마크다운 확장을 참고합니다.

퍼머링크

콘텐츠 디렉터리 경로를 다른 URL 경로로 다시 씁니다. 링크를 깨뜨리지 않고 사이트 구조를 바꿀 때 유용합니다.

[permalinks]
"old/posts" = "posts"
"2023/drafts" = "archive/2023"

규칙은 선언 순서대로 평가되고, 페이지의 디렉터리와 (정확히 또는 상위 접두사로) 처음 일치하는 원본이 선택됩니다 — 그 페이지에 대해 이후 규칙은 아예 확인하지 않습니다. 구체적인 접두사를 넓은 접두사보다 먼저 선언합니다("posts/tech"를 "posts"보다 앞에). 그러지 않으면 넓은 규칙이 구체적인 규칙을 가립니다. 토큰 패턴에도 똑같이 적용되며, 특히 "" catch-all 규칙은 다른 모든 규칙 뒤에, 맨 마지막에 둡니다.

토큰 패턴

:token 세그먼트가 들어간 대상은 Hugo 스타일 패턴으로, 디렉터리를 다시 매핑하는 대신 URL 전체를 새로 만듭니다:

[permalinks]
"posts" = "/:year/:month/:day/:slug/"

content/posts/hello.md의 날짜가 2026-03-05라면 페이지는 /2026/03/05/hello/에 게시됩니다.

참고:

• 토큰은 경로 세그먼트 전체여야 하며, 알 수 없는 토큰은 설정 로드를 실패시킵니다.
• 패턴은 리프 페이지에만 적용됩니다. 섹션 _index와 번들 index 페이지는 패턴 규칙을 건너뜁니다(디렉터리 URL을 유지하거나, 뒤에 오는 일반 재매핑 규칙을 따릅니다).
• date가 없는 페이지가 :year/:month/:day를 쓰는 패턴에 걸리면 빌드가 실패합니다 — 날짜를 넣거나, 프론트 매터에 명시적 path를 설정하거나, 날짜 토큰을 뺍니다. 게시되지 않는 페이지는 예외입니다: 초안(--drafts 없이), 만료/미래 날짜 페이지, 헤드리스 render: false 페이지는 빌드를 막지 않습니다.
• 프론트 매터의 명시적 path는 어떤 퍼머링크 규칙보다 항상 우선합니다.
• 원본 키가 비어 있으면("" 또는 "/") 패턴 규칙이 모든 페이지의 catch-all이 됩니다 — 처음 일치하는 규칙이 이기는 순서 규칙상 뒤의 규칙을 전부 가리므로 반드시 마지막에 선언합니다.
• 기본 언어가 아닌 언어에서는 /lang/ 접두사가 먼저 옵니다: /ko/2026/03/05/hello/.

링크

빌드 중 해석되지 않는 @/path.md 내부 링크를 어떻게 처리할지 제어합니다.

[links]
broken_internal = "error"

@/ 링크 문법과 strict 모드의 --cache 주의 사항은 페이지를 참고합니다.

택소노미

[[taxonomies]]
name = "tags"
feed = true
paginate_by = 10

[[taxonomies]]
name = "categories"
feed = true

항목 피드는 sort_by와 무관하게 항상 최신순을 유지합니다. 전체 정렬 규칙은 택소노미를 참고합니다.

메뉴

이름을 붙인 내비게이션 메뉴로, 템플릿에서 site.menus / get_menu()로 렌더링합니다.

[[menus.main]]
name = "Posts"
url = "/posts/"
weight = 1

[[menus.main]]
name = "About"
url = "/about/"
weight = 2

페이지/섹션은 이 파일을 건드리지 않고도 자기 프론트 매터(menus = ["main"])로 메뉴에 참여할 수 있습니다. 메뉴 테이블이 없는 [languages.<code>] 블록은 이 전역 메뉴를 상속하고, [[languages.<code>.menus.<name>]]을 선언하면 그 언어에서는 전역 메뉴를 대체합니다. 전체 레퍼런스(계층 구조, 언어별 동작, active_path 스타일링)는 메뉴를 참고합니다.

정적 파일

static/ 아래의 모든 것은 디렉터리 구조를 유지한 채 사이트 루트로 그대로 복사됩니다 — static/css/app.css는 /css/app.css로 서빙됩니다. 숨김 항목도 포함되므로 static/.well-known/security.txt는 /.well-known/security.txt로 게시됩니다. 기본적으로 Hwaro는 흔한 OS·에디터·VCS 잔여 파일을 걸러내 프로덕션에 실려 가지 않게 합니다.

[static]
use_default_excludes = true              # 내장 잔여 파일 필터 (기본값)
exclude = ["*.bak", "drafts/**"]         # 추가로 건너뛸 패턴

내장 차단 목록은 잔여 파일만 제거합니다 — .well-known/, .domains 같은 정상적인 점(dot) 경로는 절대 걸러지지 않고 항상 게시되며, 콜드 빌드와 --cache/증분 빌드에서 동일하게 동작합니다. 내장 필터링을 완전히 끄려면 use_default_excludes = false로 설정합니다.

개발 서버

hwaro serve에만 적용되는 옵션입니다 — hwaro build 출력에는 영향을 주지 않습니다.

[serve]
fast = true                          # 항상 빠른 개발 모드로 서빙

[serve.headers]
X-Frame-Options = "SAMEORIGIN"
Cache-Control = "no-store"

대응하는 CLI 플래그는 CLI의 serve 명령을 참고합니다.

기능 설정 레퍼런스

기능마다 전체 설정을 다루는 별도 문서가 있습니다. 아래는 config.toml의 모든 섹션을 정리한 빠른 레퍼런스입니다.

플러그인

[plugins]
processors = ["markdown"]

전체 예시

핵심 섹션을 모두 담은 완전한 config.toml입니다. 복사해서 필요에 맞게 고치면 됩니다.

title = "My Blog"
description = "A blog about programming"
base_url = "https://myblog.com"
default_language = "en"

[build]
output_dir = "public"
drafts = false
parallel = true
cache = false
hooks.pre = ["npm ci"]
hooks.post = ["npm run optimize"]

[markdown]
safe = false
lazy_loading = true
emoji = false
footnotes = true
task_lists = true

[permalinks]
"old/posts" = "posts"
"posts" = "/:year/:month/:day/:slug/"

[plugins]
processors = ["markdown"]

[[taxonomies]]
name = "tags"
feed = true

[[taxonomies]]
name = "categories"

[[menus.main]]
name = "Posts"
url = "/posts/"

# 기능 섹션 — 위 기능 설정 레퍼런스 참고
# [feeds], [sitemap], [robots], [og], [search], [highlight],
# [pagination], [auto_includes], [assets], [sass], [image_processing],
# [series], [related], [llms], [pwa], [amp], [deployment], etc.

함께 보기

• CLI — 설정을 오버라이드하는 명령줄 옵션
• 환경별 설정 — 환경별 오버라이드 (config.production.toml)