Hierarchical Category on Joonlog

Hugo Stack 계층형 카테고리 리팩토링

Mon, 27 Apr 2026 09:00:00 +0900

계층형 카테고리 커스텀 이후 발견한 버그 및 불필요한 코드 정리

이전 포스트에서 구현한 계층형 카테고리 시스템에서 3가지 문제를 발견

포스트 categories frontmatter의 오타로 인해 카테고리가 잘못 생성되고 있었음
generate-categories.go에서 Go의 slugify()와 Hugo의 urlize 동작 불일치로 인한 잠재적 404 위험
테마 사이드바 위젯 오버라이드 파일이 테마 기본값과 완전히 동일한데도 계속 유지되어, 테마 자동 업데이트 내용이 반영 안 되는 문제

1. 포스트 카테고리 오타 수정

frontmatter의 categories 배열에 오타가 있으면 카테고리 페이지가 잘못된 이름으로 생성됨
발견된 오타 5건 수정

파일	변경
`2025-11-04-AnsiblePlaybookDockerInstall`	`"Ansilbe"` → `"Ansible"`
`2025-11-05-AnsiblePlaybookcmdlogrotateopenfilesar`	`"Ansilbe"` → `"Ansible"`
`2026-02-04-MiniPCPromoxInstall`	`"Promox"` → `"Proxmox"`
`2026-02-23-PromoxNetworkVMSettings`	`"Promox"` → `"Proxmox"`
`2025-09-16-troubleshootinghaproxyrestartfault`	`"LoadBalancer"` → `"Load Balancer"`

2. `generate-categories.go` 개선

2.1 ioutil 제거

io/ioutil 패키지는 Go 1.16부터 deprecated
os.ReadFile / os.WriteFile으로 직접 대체

1
2
3
4
5
6
7
8


// 변경 전
import "io/ioutil"
content, err := ioutil.ReadFile(path)
ioutil.WriteFile(path, data, 0644)

// 변경 후
content, err := os.ReadFile(path)
os.WriteFile(path, data, 0644)

2.2 url 필드 추가

문제: Go의 slugify() 결과와 Hugo의 urlize 함수 결과가 불일치하는 경우 발생 가능
- 예: "Load Balancer" → slugify() → "load-balancer" vs Hugo urlize → "load-balancer" (일치하는 경우도 있지만, 특수문자·한글 혼용 시 불일치 가능)
- 레이아웃 템플릿에서 urlize로 생성한 링크와 실제 생성된 페이지 URL이 달라지면 404
해결: 생성되는 _index.md와 .md 파일에 url: 필드를 명시적으로 추가
- Hugo가 url: 필드를 최우선으로 사용하므로 slugify 결과와 완전히 동일해짐

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// Primary _index.md
primarySlug := slugify(primary)
primaryContent := fmt.Sprintf(`---
title: "%s"
description: "%s 카테고리의 모든 포스트"
primary_category: "%s"
layout: "category-primary"
url: "/categories/%s/"
---
`, primary, primary, primary, primarySlug)

// Secondary .md
secondarySlug := slugify(secondary)
secondaryContent := fmt.Sprintf(`---
title: "%s"
description: "%s > %s 카테고리의 포스트"
primary_category: "%s"
secondary_category: "%s"
layout: "category-secondary"
url: "/categories/%s/%s/"
---
`, secondary, primary, secondary, primary, secondary, primarySlug, secondarySlug)

생성 결과 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


content/categories/linux/_index.md
---
title: "Linux"
url: "/categories/linux/"
...
---

content/categories/linux/load-balancer.md
---
title: "Load Balancer"
url: "/categories/linux/load-balancer/"
...
---

3. 사이드바 위젯 오버라이드 삭제

layouts/partials/widget/categories.html
테마 Stack v3의 기본 위젯 파일을 오버라이드하고 있었음
내용 비교 결과 테마 기본값과 완전히 동일
- 유지할 이유가 없는 상태
매일 실행되는 테마 자동 업데이트 워크플로우가 있는데, 이 파일이 존재하면 테마에서 해당 위젯이 변경되어도 반영이 안 됨
- 불필요한 오버라이드 파일은 삭제하는 것이 테마 독립성 유지에 적합
해당 파일 삭제

Hugo Stack 테마에서 계층형 카테고리 커스텀하기

Wed, 12 Nov 2025 09:00:00 +0900

기존 Hugo Stack 테마에 계층적 카테고리 시스템을 커스텀

개요

기존 카테고리

기존 카테고리는 정확하게 태그와 동일한 역할을 했었음
- Hugo Taxonomy가 자동으로 /categories/linux, /categories/middleware 페이지 생성
  - 각 카테고리를 독립적인 태그처럼 평면적으로면 취급함
  - 각 포스트들에 [”Linux”, “Milldeware”]로 설정이 되어있더라도 Linux, Milldeware 두개의 카테고리가 포스팅에 부여되는 식으로만 동작
이전 사용하던 Jekyll Chirpy 테마처럼 계층적 카테고리를 구현하고 싶었음

커스텀 카테고리

메인 카테고리와 서브 카테고리의 2단계 계층 구조
자동 카테고리 페이지 생성 코드로 /categories/, /categories/메인/, /categories/메인/서브/ 3가지 페이지 생성
- /categories
  - 전체 카테고리 트리 페이지
    - 모든 포스트 스캔 → 메인/서브 카테고리 추출 → 트리 구조로 표시
  - layouts/categories/list.html
- /categories/메인/
  - 메인 카테고리 아래의 서브 카테고리 목록 페이지
    - categories[0] == "메인"인 서브 카테고리들만 표시
  - category-primary.html
- /categories/메인/서브/
  - 메인+서브 카테고리 조건을 만족하는 포스트 목록 페이지
    - categories[0] == "메인" AND categories[1] == "서브”인 포스트만 표시
  - category-secondary.html

1. 카테고리 페이지 자동 생성 스크립트

scripts/generate-categories.go
Hugo 빌드 전에 실행되어야 하는 전처리 스크립트
GitHub Actions에서 go run scripts/generate-categories.go 명령으로 실행

코드 구조 및 역할

1.1 기본 구조체 정의

각 포스트에서 추출한 카테고리 정보를 저장할 구조체

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


package main

import (
 "fmt"
 "os"
 "path/filepath"
 "regexp"
 "strings"
)

type CategoryInfo struct {
 Primary string
 Secondary string
}

1.2 main 함수 - 디렉토리 초기화

content/categories 디렉토리를 매번 새로 생성
- 기존 것 삭제 후 재생성
  - 포스트가 삭제되면 해당 카테고리 페이지도 자동으로 삭제되어야 하기 때문
1 2 3 4 5 6

func main() { contentDir := "content/post" categoriesDir := "content/categories" os.RemoveAll(categoriesDir) os.MkdirAll(categoriesDir, 0755)

1.3 포스트 스캔 및 카테고리 수집

content/post 디렉토리의 모든 마크다운 파일 스캔
각 파일에서 categories: ["메인", "서브"] 형태로 정의된 카테고리 추출

categoryMap 구조: map[메인]map[서브]bool

예: {"Linux": {"Middleware": true, "Shell": true}}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


 categoryMap := make(map[string]map[string]bool)

 filepath.Walk(contentDir, func(path string, info os.FileInfo, err error) error {
 if err != nil || info.IsDir() || !strings.HasSuffix(path, ".md") {
 return nil
 }

 content, err := os.ReadFile(path)
 if err != nil {
 return nil
 }

 cats := extractCategories(string(content))
 if len(cats) >= 2 {
 primary := cats[0]
 secondary := cats[1]

 if categoryMap[primary] == nil {
 categoryMap[primary] = make(map[string]bool)
 }
 categoryMap[primary][secondary] = true
 }
 return nil
 })

extractCategories 함수

정규식으로 front matter에서 categories: [...] 부분 찾기
쌍따옴표 제거하고 쉼표로 분리

예: ["Linux", "Middleware"] → []string{"Linux", "Middleware"}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


func extractCategories(content string) []string {
 re := regexp.MustCompile(`categories:\\s*\\[([^\\]]+)\\]`)
 matches := re.FindStringSubmatch(content)
 if len(matches) < 2 {
 return nil
 }

 categoriesStr := matches[1]
 categoriesStr = strings.ReplaceAll(categoriesStr, `"`, "")
 parts := strings.Split(categoriesStr, ",")

 var result []string
 for _, part := range parts {
 trimmed := strings.TrimSpace(part)
 if trimmed != "" {
 result = append(result, trimmed)
 }
 }
 return result
}

1.4 메인 카테고리 페이지 생성

메인 카테고리마다 content/page/categories/메인/_index.md 생성
layout: "category-primary" → Hugo가 layouts/_default/category-primary.html 템플릿 사용하도록 설정

primary_category 파라미터로 필터링에 사용할 카테고리 이름 전달

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


 for primary, secondaries := range categoryMap {
 primaryDir := filepath.Join(categoriesDir, strings.ToLower(primary))
 os.MkdirAll(primaryDir, 0755)

 primaryIndexPath := filepath.Join(primaryDir, "_index.md")
 primaryContent := fmt.Sprintf(`---
title: "%s"
layout: "category-primary"
primary_category: "%s"
---
`, primary, primary)
 os.WriteFile(primaryIndexPath, []byte(primaryContent), 0644)

1.5 서브 카테고리 페이지 생성

서브 카테고리마다 content/page/categories/메인/서브.md 생성
layout: "category-secondary" → layouts/_default/category-secondary.html 사용하도록 설정

두 개의 파라미터로 AND 조건 필터링 가능

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


 for secondary := range secondaries {
 secondaryPath := filepath.Join(primaryDir, strings.ToLower(secondary)+".md")
 secondaryContent := fmt.Sprintf(`---
title: "%s"
layout: "category-secondary"
primary_category: "%s"
secondary_category: "%s"
---
`, secondary, primary, secondary)
 os.WriteFile(secondaryPath, []byte(secondaryContent), 0644)
 }
 }

생성 결과 예시

1
2
3
4
5
6
7
8


content/page/categories/
├── linux/
│ ├── _index.md (primary_category: "Linux")
│ ├── middleware.md (primary: "Linux", secondary: "Middleware")
│ └── shell.md (primary: "Linux", secondary: "Shell")
└── scm/
 ├── _index.md (primary_category: "SCM")
 └── kubernetes.md (primary: "SCM", secondary: "Kubernetes")

2. Categories 페이지 템플릿

layouts/categories/list.html
Hugo의 템플릿 우선순위: layouts/categories/list.html > themes/.../layouts/categories/list.html
/categories/ URL은 Hugo가 자동으로 categories taxonomy 페이지로 인식
이 위치에 파일을 두면 테마의 기본 템플릿을 override

템플릿 구조 및 역할

2.1 계층 구조 빌드

테마의 baseof.html에서 {{ block "main" . }}를 이 내용으로 대체
모든 포스트를 순회하며 계층 구조 빌드
$hierarchy 구조: {"Linux": ["Middleware", "Shell"], "SCM": ["Kubernetes"]}
.Site.RegularPages: Hugo의 모든 일반 페이지
.Params.categories: 각 포스트의 front matter에서 categories 배열
index $cats 0: 배열의 첫 번째 요소 (메인 카테고리)

merge: Go template의 딕셔너리 병합 함수

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


{{ define "main" }}

{{ $hierarchy := dict }}

{{ range .Site.RegularPages }}
 {{ $cats := .Params.categories }}
 {{ if and $cats (ge (len $cats) 2) }}
 {{ $main := index $cats 0 }}
 {{ $sub := index $cats 1 }}

 {{ if not (index $hierarchy $main) }}
 {{ $hierarchy = merge $hierarchy (dict $main (slice)) }}
 {{ end }}

 {{ $subs := index $hierarchy $main }}
 {{ $subs = $subs | append $sub }}
 {{ $hierarchy = merge $hierarchy (dict $main $subs) }}
 {{ end }}
{{ end }}

2.2 메인 카테고리별 포스트 수 계산

uniq: 중복 제거
- 같은 서브 카테고리가 여러 포스트에 있을 수 있음

$totalPosts: 해당 메인 카테고리에 속한 전체 포스트 수 계산

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{{ range $mainCat, $subCats := $hierarchy }}
 {{ $subCats = uniq $subCats | sort }}

 {{ $totalPosts := 0 }}
 {{ range $.Site.RegularPages }}
 {{ $cats := .Params.categories }}
 {{ if and $cats (ge (len $cats) 1) }}
 {{ if eq (index $cats 0) $mainCat }}
 {{ $totalPosts = add $totalPosts 1 }}
 {{ end }}
 {{ end }}
 {{ end }}

2.3 토글 UI

<details>: 토글
open 속성: 기본적으로 펼쳐진 상태
urlize: URL 안전 문자열로 변환
- “Linux Kernel” → “linux-kernel”

/categories/linux/ → scripts/generate-categories.go가 생성한 _index.md 페이지로 이동

1
2
3
4
5
6
7
8


 <details class="category-group" open>
 <summary class="main-cat">
 <span class="main-cat-title">
 <span class="icon">📁</span>
 <a href="{{ printf "/categories/%s/" ($mainCat | urlize) }}">{{ $mainCat }}</a>
 </span>
 <span class="post-count-badge">{{ $totalPosts }}</span>
 </summary>

2.4 서브 카테고리 목록

각 서브 카테고리의 포스트 개수 계산
AND 조건: categories[0] == mainCat AND categories[1] == subCat

/categories/linux/middleware/ → generate-categories.go가 생성한 middleware.md 페이지로 이동

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


 <div class="sub-cats">
 {{ range $subCat := $subCats }}
 {{ $count := 0 }}
 {{ range $.Site.RegularPages }}
 {{ $cats := .Params.categories }}
 {{ if and $cats (ge (len $cats) 2) }}
 {{ if and (eq (index $cats 0) $mainCat) (eq (index $cats 1) $subCat) }}
 {{ $count = add $count 1 }}
 {{ end }}
 {{ end }}
 {{ end }}

 <a href="{{ printf "/categories/%s/%s/" ($mainCat | urlize) ($subCat | urlize) }}" class="sub-cat-link">
 <span class="sub-cat-name">{{ $subCat }}</span>
 <span class="count">({{ $count }})</span>
 </a>
 {{ end }}
 </div>
 </details>
{{ end }}

2.5 스타일링

인라인 CSS: 이 페이지에만 적용되는 스타일

var(--accent-color): 테마에서 정의한 CSS 변수 사용 (다크 모드 대응)

1
2
3
4
5
6
7
8
9


<style>
.page-header {
 margin-bottom: 2rem;
 padding-bottom: 1rem;
 border-bottom: 2px solid var(--accent-color);
}
/* ... 나머지 CSS ... */
</style>
{{ end }}

3. 메인 카테고리 페이지 템플릿

파일 위치: layouts/_default/category-primary.html
generate-categories.go가 생성한 _index.md에서 layout: "category-primary" 지정
Hugo는 layouts/_default/ 디렉토리에서 커스텀 레이아웃을 찾음
파일명이 category-primary.html이므로 layout: "category-primary"와 매칭

템플릿 구조 및 역할

3.1 포스트 필터링

.Params.primary_category: generate-categories.go가 front matter에 추가한 파라미터
필터링 조건: categories[0] == $primaryCat

$posts: 필터링된 포스트 목록 (slice)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{{ $primaryCat := .Params.primary_category }}

{{ $posts := slice }}
{{ range .Site.RegularPages }}
 {{ $cats := .Params.categories }}
 {{ if and $cats (ge (len $cats) 1) }}
 {{ if eq (index $cats 0) $primaryCat }}
 {{ $posts = $posts | append . }}
 {{ end }}
 {{ end }}
{{ end }}

3.2 서브 카테고리 추출

필터링된 포스트들에서 서브 카테고리 목록 추출
in: Go template의 배열 포함 여부 확인 함수

알파벳 순으로 정렬

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{{ $subCategories := slice }}
{{ range $posts }}
 {{ $cats := .Params.categories }}
 {{ if ge (len $cats) 2 }}
 {{ $sub := index $cats 1 }}
 {{ if not (in $subCategories $sub) }}
 {{ $subCategories = $subCategories | append $sub }}
 {{ end }}
 {{ end }}
{{ end }}
{{ $subCategories = $subCategories | uniq | sort }}

3.3 서브 카테고리별 그룹핑

서브 카테고리별로 그룹핑하여 표시

각 그룹의 포스트 개수 배지로 표시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{{ range $subCat := $subCategories }}
 {{ $postCount := 0 }}
 {{ range $posts }}
 {{ $cats := .Params.categories }}
 {{ if and (ge (len $cats) 2) (eq (index $cats 1) $subCat) }}
 {{ $postCount = add $postCount 1 }}
 {{ end }}
 {{ end }}

 <details class="sub-category-group" open>
 <summary class="sub-category-title">
 <span class="title-text">{{ $subCat }}</span>
 <span class="post-count-badge">{{ $postCount }}</span>
 </summary>

3.4 포스트 목록 렌더링

각 서브 카테고리 내의 포스트 목록 표시
.RelPermalink: 포스트의 상대 URL
first 3: 태그가 많을 경우 처음 3개만 표시

{{ with }}: 값이 존재할 때만 실행

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


 <div class="post-list">
 {{ range $posts }}
 {{ $cats := .Params.categories }}
 {{ if and (ge (len $cats) 2) (eq (index $cats 1) $subCat) }}
 <article class="post-item">
 <a href="{{ .RelPermalink }}" class="post-link">
 <h3 class="post-title">{{ .Title }}</h3>
 <div class="post-meta">
 <time>{{ .Date.Format "2006-01-02" }}</time>
 {{ with .Params.tags }}
 <span class="tags">
 {{ range first 3 . }}
 <span class="tag">{{ . }}</span>
 {{ end }}
 </span>
 {{ end }}
 </div>
 </a>
 </article>
 {{ end }}
 {{ end }}
 </div>
 </details>
{{ end }}

4. 서브 카테고리 페이지 템플릿

layouts/_default/category-secondary.html
generate-categories.go가 생성한 middleware.md에서 layout: "category-secondary" 지정
layouts/_default/category-secondary.html과 매칭

템플릿 구조 및 역할

Breadcrumb 네비게이션: Linux › Middleware

메인 카테고리 클릭 시 메인 카테고리 페이지로 이동

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<header class="page-header">
 <div class="breadcrumb">
 <a href="{{ printf "/categories/%s/" (.Params.primary_category | urlize) }}">
 {{ .Params.primary_category }}
 </a>
 <span class="separator">›</span>
 <span class="current">{{ .Title }}</span>
 </div>
 <h1>{{ .Title }}</h1>
</header>

4.2 AND 조건 필터링

AND 조건 필터링: categories[0] == primary AND categories[1] == secondary

두 파라미터 모두 generate-categories.go가 front matter에 추가

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{{ $primaryCat := .Params.primary_category }}
{{ $secondaryCat := .Params.secondary_category }}

{{ $posts := slice }}
{{ range .Site.RegularPages }}
 {{ $cats := .Params.categories }}
 {{ if and $cats (ge (len $cats) 2) }}
 {{ if and (eq (index $cats 0) $primaryCat) (eq (index $cats 1) $secondaryCat) }}
 {{ $posts = $posts | append . }}
 {{ end }}
 {{ end }}
{{ end }}

4.3 포스트 목록

필터링된 포스트 목록만 표시

서브 카테고리 그룹핑 없이 플랫한 리스트

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<div class="post-count">
 총 {{ len $posts }}개의 포스트
</div>

<section class="category-posts">
 <div class="post-list">
 {{ range $posts }}
 <article class="post-item">
 <a href="{{ .RelPermalink }}" class="post-link">
 <h3 class="post-title">{{ .Title }}</h3>
 <div class="post-meta">
 <time>{{ .Date.Format "2006-01-02" }}</time>
 {{ with .Params.tags }}
 <span class="tags">
 {{ range first 3 . }}
 <span class="tag">{{ . }}</span>
 {{ end }}
 </span>
 {{ end }}
 </div>
 </a>
 </article>
 {{ end }}
 </div>
</section>

5. GitHub Actions 워크플로우 수정

.github/workflows/deploy.yml
추가한 부분
1. generate-categories.go 실행 → content/page/categories/ 디렉토리 생성
2. Hugo 빌드 → 생성된 카테고리 페이지들을 포함하여 정적 사이트 생성
1 2 3 4 5

- name: Generate category pages run: go run scripts/generate-categories.go - name: Build run: hugo --minify --gc

6. 메뉴 설정

config/_default/menu.toml
- identifier: Hugo가 이 메뉴 항목을 식별하는 고유 ID
- name: 사용자에게 표시될 메뉴 이름
- url: 클릭 시 이동할 경로
- weight: 메뉴 정렬 순서 (낮을수록 위에 표시)
- icon: 테마의 assets/icons/categories.svg 아이콘 사용
1 2 3 4 5 6 7

[[main]] identifier = "categories" name = "Categories" url = "/categories/" weight = 2 [main.params] icon = "categories"

Archives weight 조정

content/page/archives/index.md

1
2
3


menu:
 main:
 weight: 3 # 기존 2에서 3으로 변경

구현 화면

메뉴
/categories 페이지
/categories/메인 페이지
/categories/메인/서브 페이지

Hierarchical Category on Joonlog

Hugo Stack 계층형 카테고리 리팩토링

1. 포스트 카테고리 오타 수정

2. generate-categories.go 개선

2.1 ioutil 제거

2.2 url 필드 추가

생성 결과 예시

3. 사이드바 위젯 오버라이드 삭제

Hugo Stack 테마에서 계층형 카테고리 커스텀하기

개요

기존 카테고리

커스텀 카테고리

1. 카테고리 페이지 자동 생성 스크립트

코드 구조 및 역할

1.1 기본 구조체 정의

1.2 main 함수 - 디렉토리 초기화

1.3 포스트 스캔 및 카테고리 수집

1.4 메인 카테고리 페이지 생성

1.5 서브 카테고리 페이지 생성

생성 결과 예시

2. Categories 페이지 템플릿

템플릿 구조 및 역할

2.1 계층 구조 빌드

2.2 메인 카테고리별 포스트 수 계산

2.3 토글 UI

2.4 서브 카테고리 목록

2.5 스타일링

3. 메인 카테고리 페이지 템플릿

템플릿 구조 및 역할

3.1 포스트 필터링

3.2 서브 카테고리 추출

3.3 서브 카테고리별 그룹핑

3.4 포스트 목록 렌더링

4. 서브 카테고리 페이지 템플릿

템플릿 구조 및 역할

4.1 Breadcrumb 네비게이션

4.2 AND 조건 필터링

4.3 포스트 목록

5. GitHub Actions 워크플로우 수정

6. 메뉴 설정

구현 화면

2. `generate-categories.go` 개선