GitHub Blog 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에서 SEO 설정(Google Searche Console)

Tue, 23 Dec 2025 09:00:00 +0900

SEO

SEO는 Search Engine Optimization, 즉 검색 엔진 최적화로 구글이나 네이버 같은 검색 엔진에서 내 블로그가 더 잘 노출되도록 하는 작업이다.

블로그를 운영하더라도, 검색에 노출되지 않으면 방문자가 내 블로그 도메인을 직접 입력해야만 접근 가능하다. 사실상 필수 설정.

GitHub Pages + Hugo 환경 SEO 설정

Sitemap 자동 생성
- Hugo는 별도 플러그인 없이 sitemap.xml 파일을 자동으로 생성
- 블로그 글 전체를 포함한 sitemap이 빌드 시 자동 생성됨
- 배포 후 https://<블로그주소>/sitemap.xml 로 접근 가능하면 성공
robots.txt 생성
- 검색 엔진 크롤러에게 사이트 크롤링 규칙을 알려주는 파일
- static/robots.txt 파일 생성
1 2 3 4

User-agent: * Allow: / Sitemap: https://<블로그주소>/sitemap.xml
Google Search Console 등록
- Google Search Console 접속
- URL 접두어 방식 선택 → https://<블로그주소> 입력
- HTML 파일 다운로드 후 static/ 폴더에 저장
  1 2
  
  static/ └── <verifications값>.html
- 배포 후 Google Search Console 내 소유권 확인
- 생성된 사이트맵 Google Search Console에 등록
- 등록 후에 즉시 활성화가 되는 것은 아님
  - 하루 정도 대기 필요

GitHub Blog에서 Giscuss로 댓글 기능 추가

Fri, 19 Dec 2025 09:00:00 +0900

1. GitHub Discussions 활성화

GitHub Blog Repository 접속
Settings 탭 클릭
General 섹션에서 Features 찾기
Discussions 체크박스 활성화

2. Giscus 앱 설치

https://github.com/apps/giscus 접속
Install 클릭
joonlog/joonlog.github.io 저장소 선택

3. Giscus 설정값 생성

https://giscus.app/ko 접속
다음 정보 입력:
- 저장소: joonlog/joonlog.github.io
- 페이지 ↔ Discussions 연결: 경로
- Discussion 카테고리: Announcements 또는 General 선택
giscus 사용에서 출력된 값을 확인

data-repo
data-repo-id
data-category
data-category-id

4. Hugo 설정 파일 수정

config/_default/params.toml 파일 수정

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


[comments]
enabled = true
provider = "giscus" # disqus에서 giscus로 변경

[comments.giscus]
repo = "joonlog/joonlog.github.io"
repoID = "<repo_id>"
category = "<category_이름>"
categoryID = "<category_id>"
mapping = "pathname"
lightTheme = "light"
darkTheme = "dark"
reactionsEnabled = 1
emitMetadata = 0

5. Git 커밋 후 재배포

추가 성공!

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/메인/서브 페이지

Jekyll Chirpy 테마에서 Hugo Stack 테마로 블로그 이관하기

Tue, 11 Nov 2025 09:00:00 +0900

Jekyll Chirpy 테마로 포스팅했던 글들을 Hugo Stack으로 이관

자세한 Hugo Stack 구축 과정은 이 글 참고

Jekyll Chirpy에서 Hugo Stack으로 이관한 이유

Jekyll은 Liquid를 사용해서, 포스팅에 {%, {{ 같은 글자가 있으면 Liquid 템플릿 엔진이 이걸 Liquid 글로 인식을 해서 저 문자 자체로 사용하려면 {% raw %} 태그로 감싸야 했음
Jekyll은 Ruby 언어를 베이스로 짜여져 있고, 계층적 카테고리 구성과 같이 블로그를 커스터마이징할 일이 종종 있는데, 코드를 수정하기에는 Ruby에 대해 아는 바가 없음
최근에 Go를 배우기 시작한 상황에서 Go를 베이스로 한 Hugo로 블로그를 구성하면 좋겠다 싶었음
현재 Jekyll보다 Hugo가 더 점유율이 높고, 업데이트가 자주 있음
직접 구성해보니 구조 자체도 Hugo가 훨씬 간단
빌드부터 배포까지 Hugo가 더 빠름
기존 Chirpy 테마와 비슷하면서 사용자가 많은 테마인 Stack을 선택

블로그 이관 과정

기존 Jekyll 소스코드 별도 브랜치로 백업
- Jekyll 브랜치 생성 후 백업
Hugo Stack Starter로 뼈대만 있는 블로그 배포
기존 블로그 글 이관
- 107개의 블로그 글 이관
- 전체 이관 전에 글 1개로 테스트

이관 시 포스팅 글 변경점

Front Matter

날짜 형식

첫 공백을 T로 변경하고, timezone 앞 공백 제거

1
2
3
4
5


# Jekyll
date: 2024-12-09 18:08:00 +09:00

# Hugo
date: 2024-12-09T18:08:00+09:00

Categories/Tags 배열 따옴표 추가

1
2
3
4
5
6
7


# Jekyll
categories: [Linux, Middleware]
tags: [rocky8, apache, tomcat]

# Hugo
categories: ["Linux", "Middleware"]
tags: ["rocky8", "apache", "tomcat"]

폴더 구조

각 포스팅마다 <포스팅 이름>.md가 아닌, <포스팅 이름> 폴더를 만들고 그 아래 index.md가 있는 구조

1
2
3
4
5
6
7
8


# Jekyll
_posts/2024-12-09-Rocky8ApacheTomcat.md

# Hugo
content/post/2024-12-09-rocky8apachetomcat/
 ├── index.md
 ├── Rocky8ApacheTomcat1.png
 └── Rocky8ApacheTomcat2.png

이미지 경로 변경
- Jekyll에서는 assests/img 경로에 모든 사진을 넣었지만, Hugo에서는 각 포스팅 폴더 안에 각각의 이미지를 넣음
1 2 3 4 5

# Jekyll /img/linux/Rocky8ApacheTomcat1.png # Hugo Rocky8ApacheTomcat1.png

이후 예정 작업

Hugo Theme에는 계층적 카테고리를 지원하는 테마가 없다
이 기능을 사용하기 위해선 별도 커스텀 필요

Hugo 템플릿 Stack 테마로 GitHub Blog 배포하기

Tue, 04 Nov 2025 09:00:00 +0900

GitHub Pages로 Hugo 템플릿의 Stack Theme를 사용해서 깃허브 블로그를 구축

별도의 컨텐츠 설정 없이 배포까지 정상적인지 확인

Hugo Stack 구조

config
- Hugo Stack 설정 폴더
  - 사이트 url, 언어, 페이지네이션, footer/sidebar 파라미터, 메뉴, 모듈 등을 설정
content
- 포스팅 글, 아카이브, 검색, 링크, 카테고리 등의 페이지가 존재
static
- 정적 파일들이 있는 폴더
assets
- 빌드에 포함할 커스텀 css, 이미지를 넣는 폴더
.github
- GitHub Action 배포에 사용할 deploy.yml이 있는 폴더
go.mod
- go 모듈

Hugo Stack 구축

깃허브 소스 클론

1

git clone https://github.com/CaiJimmy/hugo-theme-stack-starter.git

config 수정

config/_default/config.toml

1
2
3
4
5


baseurl = "https://joonlog.github.io"
languageCode = "ko-kr"
title = "Joonlog"
defaultContentLanguage = "ko"
hasCJKLanguage = true

footer, sidebar 수정

config/_default/params.toml

1
2
3


since = 2024
emoji = "🐕"
subtitle = "인프라/개발 기술 블로그"

배포 설정

배포 설정 수정
- master 브랜치에 푸시될때 자동 배포하는 설정을 main 브랜치로 수정
- .github/workflows/deploy.yml
  1 2 3 4 5
  
  on: push: branches: [main] pull_request: branches: [main]
배포 방식 변경
- starter 리포에 있는 기존 deploy.yml은 gh-pages 방식
- 배포 과정:
  1. main 브랜치로 코드 푸시
  2. 빌드
  3. 빌드한 결과물을 gh-pages 브랜치에 푸시
  4. GitHub Pages가 gh-pages 브랜치에서 블로그 서빙
    - 2개의 브랜치에 거렻서 배포되기 때문에 느림
- GitHub Actions Artifact 방식으로 변경
- 배포 과정
  1. main 브랜치로 코드 푸시
  2. 빌드
  3. 빌드한 결과물을 artifact에 업로드
  4. GitHub Pages가 artifact에서 직접 서빙
    - GitHub Pages를 사용할 때의 최신 배포 방식
    - gh-pages 브랜치 관리 불필요
    - 빠름
- .github/workflows/deploy.yml
  - gh-pages 브랜치에 푸시할 필요가 없어져서 contentes 권한을 write로 유지할 필요가 없어짐
  - GitHub Pages에 직접 배포하기 위한 pages:write 권한
  - OIDC 보안을 위한 id-token:write
    1 2 3 4
    
    permissions: contents: read pages: write id-token: write
  - 기존 코드는 gh-pages 브랜치에 푸시하는 코드
  - 대신 artifact에 푸시 + 푸시한 artifact를 GitHub Pages로 배포
    1 2 3 4 5 6 7 8
    
    - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: ./public - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4

GitHub Pages 설정

Repository 생성
- GitHub에서 <username>.github.io Repository 생성
  - 깃허브 블로그로 사용하기 위해선 반드시 위 이름으로 Repository 생성 필요
GitHub Pages 활성화
- Settings - Pages - Build and deployment
  - GitHub Actions 선택

배포 확인

소스 푸시

1
2
3


git add .
git commit -m "First Push"
git push

배포 성공!

참고

Hugo Stack GitHub: https://github.com/CaiJimmy/hugo-theme-stack
Hugo Stack Starter GitHub: https://github.com/CaiJimmy/hugo-theme-stack-starter
Hugo Theme: https://themes.gohugo.io/

Jekyll Chirpy 테마 카테고리 에러 TroubleShooting(2)

Wed, 29 Oct 2025 18:00:00 +0900

문제 재발견

이전에 Jekyll Chirpy 테마 카테고리 중복/누락 TroubleShooting 글에서 _layouts/categories.html Liquid 템플릿을 수정해서 카테고리 문제를 해결했다고 생각지만, 계속해서 버그가 확인됨
- 카테고리 목록 페이지(/categories/)는 제대로 표시됨
- 하지만 개별 카테고리 페이지(/categories/kubernetes/)에 들어가면 메인 카테고리와 서브 카테고리가 전부 섞여서 표시됨
- 예시:
  - Certification > Kubernetes (서브카테고리): 1개 포스트
  - Kubernetes > Architecture (메인카테고리): 34개 포스트
  - /categories/kubernetes/ 접속 시: 35개 포스트 전부 표시

근본 원인

이전 해결책은 _layouts/categories.html (목록 페이지)만 고친 것
진짜 문제는 Jekyll Archives 플러그인

Jekyll Archives 플러그인의 동작 방식
- categories: [Certification, Kubernetes] 형태의 포스트가 있으면 site.categories['Certification']에도 포함되고 site.categories['Kubernetes']에도 포함됨
- /categories/kubernetes/ 와 같은 1단계 경로로만 페이지를 생성하고 /categories/certification/kubernetes/ 같이 2단계 이상으로는 페이지를 생성하지 않음
_layouts/category.html의 한계
1

{% raw %}{% for post in page.posts %}{% endraw %}
- page.posts는 Jekyll Archives가 이미 생성한 데이터
- Liquid 템플릿에서는 이미 섞인 데이터를 받음
- 페이지 생성 자체는 Ruby 플러그인이 하기 때문에 Liquid로는 근본 해결 불가

해결 방법

커스텀 Ruby 플러그인을 작성해서 Jekyll Archives를 대체

1. Jekyll Archives의 categories 비활성화

_config.yml

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


# 변경 전
jekyll-archives:
 enabled: [categories, tags]
 layouts:
 category: category
 tag: tag
 permalinks:
 tag: /tags/:name/
 category: /categories/:name/

# 변경 후
jekyll-archives:
 enabled: [tags]
 layouts:
 tag: tag
 permalinks:
 tag: /tags/:name/

2. 카테고리 플러그인 작성

_plugins/hierarchical-categories.rb

 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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85


# frozen_string_literal: true

module Jekyll
 # Generates hierarchical category pages
 # Primary categories: /categories/primary/
 # Secondary categories: /categories/primary/secondary/
 class HierarchicalCategoryPage < Page
 def initialize(site, base, primary, secondary = nil)
 @site = site
 @base = base
 @dir = if secondary
 File.join('categories', primary.downcase.gsub(' ', '-'))
 else
 'categories'
 end
 @name = if secondary
 "#{secondary.downcase.gsub(' ', '-')}.html"
 else
 "#{primary.downcase.gsub(' ', '-')}.html"
 end

 self.process(@name)
 self.read_yaml(File.join(base, '_layouts'), 'category.html')

 # Set category name for display
 self.data['title'] = secondary || primary
 self.data['category_name'] = secondary || primary
 self.data['primary_category'] = primary
 self.data['secondary_category'] = secondary

 # Filter posts based on category hierarchy
 if secondary
 # Secondary category: posts where categories[0] == primary AND categories[1] == secondary
 self.data['posts'] = site.posts.docs.select do |post|
 post.data['categories'] &&
 post.data['categories'][0] == primary &&
 post.data['categories'][1] == secondary
 end
 else
 # Primary category: posts where categories[0] == primary
 self.data['posts'] = site.posts.docs.select do |post|
 post.data['categories'] &&
 post.data['categories'][0] == primary
 end
 end
 end
 end

 class HierarchicalCategoryPageGenerator < Generator
 safe true
 priority :low

 def generate(site)
 return unless site.layouts.key? 'category'

 # Collect all primary and secondary categories
 primary_categories = {}

 site.posts.docs.each do |post|
 next unless post.data['categories']

 categories = post.data['categories']
 primary = categories[0]
 secondary = categories[1] if categories.length > 1

 next unless primary

 primary_categories[primary] ||= Set.new
 primary_categories[primary] << secondary if secondary
 end

 # Generate pages for each primary category
 primary_categories.each do |primary, secondaries|
 # Generate primary category page
 site.pages << HierarchicalCategoryPage.new(site, site.source, primary)

 # Generate secondary category pages
 secondaries.each do |secondary|
 next if secondary.nil?
 site.pages << HierarchicalCategoryPage.new(site, site.source, primary, secondary)
 end
 end
 end
 end
end

핵심 로직:
- 메인 카테고리: post.categories[0]만 매칭
- 서브 카테고리: post.categories[0] == primary AND post.categories[1] == secondary 동시 매칭
- URL 구조:
  - 메인 카테고리: /categories/kubernetes/
  - 서브 카테고리: /categories/certification/kubernetes/

3. 카테고리 목록 페이지 링크 수정

_layouts/categories.html
- 서브카테고리 URL을 /categories/sub/에서 /categories/primary/sub/로 수정
- URL 마지막 / 제거 (Jekyll이 .html 파일을 디렉토리로 인식하는 문제 방지)

56줄 메인 카테고리 링크

1
2
3
4
5


# 변경 전
{% raw %}{% capture _category_url %}/categories/{{ category_name | slugify | url_encode }}/{% endcapture %}{% endraw %}

# 변경 후
{% raw %}{% capture _category_url %}/categories/{{ category_name | slugify | url_encode }}{% endcapture %}{% endraw %}

121줄 서브 카테고리 링크

1
2
3
4
5


# 변경 전
{% raw %}{% capture _sub_ctg_url %}/categories/{{ sub_category | slugify | url_encode }}/{% endcapture %}{% endraw %}

# 변경 후
{% raw %}{% capture _sub_ctg_url %}/categories/{{ category_name | slugify | url_encode }}/{{ sub_category | slugify | url_encode }}{% endcapture %}{% endraw %}

결과

메인 카테고리 페이지: /categories/kubernetes/
- 메인이 카테고리가 kubernetes인 모든 포스트 표시
서브 카테고리 페이지: /categories/certification/kubernetes/
- 메인 카테고리가 Certification, 서브 카테고리가 Kubernetes인 포스트만 표시
카테고리 목록 페이지에서 클릭 시 올바른 URL로 이동
카테고리 버그 해결!

Jekyll Chirpy 테마 카테고리 에러 TroubleShooting(1)

Sat, 30 Aug 2025 09:00:00 +0900

문제 확인

깃허브 블로그 템플릿으로 Jekyll Chirpy 테마를 사용 중이었는데, 쓰다 보니 카테고리가 내가 설정한 것과 다르게 동작하는 것을 발견했다.

EX 1) AWS를 상위 카테고리로 설정한 글을 작성했는데 실제 블로그에 AWS 카테고리가가 없는 경우
EX 2) Kubernetes는 상위 카테고리로만 설정했었는데, Kubernetes 하위 카테고리로 Kubernetes가 생기고 이전 글들이 똑같이 복사돼서 들어가 있는 경우
EX 3) 하위 카테고리로 AWS를 정했는데 AWS 상위 카테고리에 글이 들어가 있는 경우

원인

Jekyll Chirpy의 _layouts/categories.html 템플릿에서 site.categories를 사용하는 방식의 문제

site.categories의 동작 방식

site.categories는 모든 포스트의 모든 카테고리를 수집
categories : [Certification, AWS]인 글이 있으면 site.categories['AWS']에도 포함됨

결과적으로 같은 글이 여러 상위 카테고리에 중복 표시

1
2
3
4


&#123;% for category in sort_categories %&#125;
 &#123;% assign category_name = category | first %&#125;
 &#123;% assign posts_of_category = category | last %&#125;
 &#123;% if category_name == first_post.categories[0] %&#125;

해결 방법

_layouts/categories.html 상위 카테고리 로직

site.categories 대신 site.posts 직접 순회
첫 번째 카테고리(post.categories[0])만 상위 카테고리로 수집
해당 상위 카테고리를 가진 글들만 대상으로 처리

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


&#123;% assign group_index = 0 %&#125;

&#123;% comment %&#125; Collect all primary categories from posts &#123;% endcomment %&#125;
&#123;% assign primary_categories = '' | split: '' %&#125;
&#123;% for post in site.posts %&#125;
 &#123;% assign primary_cat = post.categories[0] %&#125;
 &#123;% if primary_cat %&#125;
 &#123;% unless primary_categories contains primary_cat %&#125;
 &#123;% assign primary_categories = primary_categories | push: primary_cat %&#125;
 &#123;% endunless %&#125;
 &#123;% endif %&#125;
&#123;% endfor %&#125;
&#123;% assign primary_categories = primary_categories | sort %&#125;

&#123;% for category_name in primary_categories %&#125;
 &#123;% comment %&#125; Get posts that have this as primary category &#123;% endcomment %&#125;
 &#123;% assign posts_of_category = '' | split: '' %&#125;
 &#123;% for post in site.posts %&#125;
 &#123;% if post.categories[0] == category_name %&#125;
 &#123;% assign posts_of_category = posts_of_category | push: post %&#125;
 &#123;% endif %&#125;
 &#123;% endfor %&#125;

_layouts/categories.html 하위 카테고리 로직

해당 상위 카테고리를 첫 번째로 가진 글들의 두 번째 카테고리만 수집

중복 제거 로직 유지

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


&#123;% comment %&#125; Collect subcategories &#123;% endcomment %&#125;
&#123;% assign sub_categories = '' | split: '' %&#125;
&#123;% for post in posts_of_category %&#125;
 &#123;% assign second_category = post.categories[1] %&#125;
 &#123;% if second_category %&#125;
 &#123;% unless sub_categories contains second_category %&#125;
 &#123;% assign sub_categories = sub_categories | push: second_category %&#125;
 &#123;% endunless %&#125;
 &#123;% endif %&#125;
&#123;% endfor %&#125;

_layouts/categories.html 포스트 수 계산 로직

site.categories[category_name] 대신 실제 해당 카테고리 글 개수 계산

하위 카테고리도 정확한 개수 표시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Primary category
&#123;% assign top_posts_size = posts_of_category | size %&#125;

# Subcategory
&#123;% comment %&#125; Count posts for this subcategory under current primary category &#123;% endcomment %&#125;
&#123;% assign posts_size = 0 %&#125;
&#123;% for post in posts_of_category %&#125;
 &#123;% if post.categories[1] == sub_category %&#125;
 &#123;% assign posts_size = posts_size | plus: 1 %&#125;
 &#123;% endif %&#125;
&#123;% endfor %&#125;

빌드 에러 발생 시

Liquid syntax error (line 150): ’endif’ is not a valid delimiter for for tags. use endfor

불필요한 {% endif %} 제거 (for 루프에는 {% endfor %}만 필요)

1
2


&#123;% assign group_index = group_index | plus: 1 %&#125;
&#123;% endfor %&#125;

해결

각 카테고리가 첫 번째 상위 카테고리 기준으로만 분류하도록 수정
중복 포스팅 문제 해결!

GitHub Blog(Jekyll Chirpy) SEO 설정

Fri, 25 Apr 2025 09:00:00 +0900

SEO

SEO는 Search Engine Optimization, 즉 검색 엔진 최적화로 구글이나 네이버 같은 검색 엔진에서 내 블로그가 더 잘 노출되도록 하는 작업이다.

블로그를 운영하더라도, 검색에 노출되지 않으면 방문자가 내 블로그 도메인을 직접 입력해야만 접근 가능하다. 사실상 필수 설정.

GitHub Pages + Jekyll 환경 SEO 설정

jekyll-seo-tag 플러그인 설치
- 블로그에 필요한 SEO 메타 태그들을 자동으로 생성해주는 공식 플러그인
- Gemfile에 추가
1

gem 'jekyll-seo-tag'
- _config.yml에 추가
1 2

plugins: - jekyll-seo-tag
jekyll-sitemap 플러그인 설치
- 블로그 글 전체를 포함한 sitemap.xml 파일을 자동을 생성해주는 플러그인
- 구글, 네이버 같은 검색엔진에 내 사이트 구조를 전달하는 목적의 파일
1

gem 'jekyll-sitemap'
1 2

plugins: - jekyll-sitemap
- 배포 후 https://<블로그주소>/sitemap.xml 로 접근 가능하면 성공
Google Search Console 등록
1. Google Search Console 접속
2. URL 접두어 방식 선택 → https://<블로그주소> 입력
1. 생성된 verifications 값 _config.yml에 입력
1 2

webmaster_verifications: google: "<값 입력>"
1. 배포 후 Google Search Console 내 소유권 확인
1. 2번에서 생성된 사이트맵 Google Search Console에 등록
- 등록 후에 즉시 활성화가 되는 것은 아님
  - 하루 정도 대기 필요

참고

SEO: https://standing-o.github.io/posts/jekyll-seo/

GitHub 블로그(Jekyll Chirpy) 오류 TroubleShooting

Sun, 29 Dec 2024 09:00:00 +0900

Jekyll - Chirpy 테마

로컬 테스트 오류

Unable to monitor directories for changes because iNotify max watches exceeded.
Linux의 inotify 파일 시스템 감시자의 최대 수 제한을 초과했기 때문에 발생

1코어 1기가로 실행 중이기 때문에 제한인 것으로 추정
inotify 값 변경해서 해결
1
2
3
cat /proc/sys/fs/inotify/max_user_watches

sudo sysctl fs.inotify.max_user_watches=524288

GitHub Action 의존성 오류

git push 후에 github action에서 발생한 오류

의존성 누락으로 인해 _sass/main.bundle.scss에서 @use ‘vendors/bootstrap’ 참조 불가

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


Error: Can't find stylesheet to import.
 ╷
1 │ @use 'vendors/bootstrap';
 │ ^^^^^^^^^^^^^^^^^^^^^^^^
 ╵
 main.bundle.scss 1:1 @use
 /home/runner/work/joonlog.github.io/joonlog.github.io/assets/css/jekyll-theme-chirpy.scss 1:1 root stylesheet
 Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/jekyll-theme-chirpy.scss':
 Can't find stylesheet to import.
 ------------------------------------------------
 Jekyll 4.3.4 Please append `--trace` to the `build` command
 for any additional information or backtrace.
 ------------------------------------------------

참고: https://github.com/cotes2020/jekyll-theme-chirpy/discussions/1809

ci 파일에 npm 의존성 주입 추가로 해결 가능
아래 코드를 jekyll.yml의 Build with Jekyll Step 위에 작성

1
2


name: npm build
run: npm install && npm run build

GitHub Action 의존성 오류2

git push 후에 github action에서 발생한 오류

7시간 전까지 정상 동작 했는데 GitHub Action 중 오류

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


...
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE package: '@semantic-release/npm@12.0.1',
npm warn EBADENGINE required: { node: '>=20.8.1' },
npm warn EBADENGINE current: { node: 'v18.20.5', npm: '10.8.2' }
npm warn EBADENGINE }
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE package: '@semantic-release/release-notes-generator@14.0.1',
npm warn EBADENGINE required: { node: '>=20.8.1' },
npm warn EBADENGINE current: { node: 'v18.20.5', npm: '10.8.2' }
npm warn EBADENGINE }
...
[js] [!] Error: Cannot find module '/home/runner/work/joonlog.github.io/joonlog.github.io/node_modules/@jridgewell/gen-mapping/dist/gen-mapping.umd.js'
[js] at createEsmNotFoundErr (node:internal/modules/cjs/loader:1177:15)
[js] at finalizeEsmResolution (node:internal/modules/cjs/loader:1165:15)
[js] at resolveExports (node:internal/modules/cjs/loader:590:14)
[js] at Function.Module._findPath (node:internal/modules/cjs/loader:664:31)
[js] at Function.Module._resolveFilename (node:internal/modules/cjs/loader:1126:27)
[js] at Function.Module._load (node:internal/modules/cjs/loader:981:27)
[js] at Module.require (node:internal/modules/cjs/loader:1231:19)
[js] at require (node:internal/modules/helpers:177:18)
[js] at Object.<anonymous> (/home/runner/work/joonlog.github.io/joonlog.github.io/node_modules/@jridgewell/source-map/dist/source-map.cjs:6:18)
[js] at Module._compile (node:internal/modules/cjs/loader:1364:14)

정상 동작 하던 커밋으로 롤백했는데도 같은 에러 발생 ⇒ GitHub 쪽 버전 문제?

warn 발생하는 node 문제인가 싶어 jekyll.yml에 아래 코드 추가해서 node 22이상으로 사용 후 해결됨 - npm 설치 후 빌드 시 node 20 이상이 필요하게 변경된 것으로 추정 ⇒ 버전 지정 안하면 깃허브는 node를 18버전으로 사용

1
2
3
4


 - name: Setup Node.js
 uses: actions/setup-node@v3
 with:
 node-version: '22.x' # Node 22 이상 사용

GitHub 블로그 구축 - Jekyll Chirpy

Wed, 25 Dec 2024 09:00:00 +0900

Jekyll Chirpy 테마

https://github.com/cotes2020/jekyll-theme-chirpy

Jekyll Chirpy 사용 이유

기술 블로그용으로 가장 적합
- 다른 Jekyll 테마들은 스타트업 블로그 스타일이나 쇼핑몰에서 사용할 것 같은 많은데, 개인용 기술블로그 테마로는 가장 깔끔하다고 느꼈다
- 카테고리, 타임라인 별로 작성한 글을 볼 수 있고, 블로그 내 검색 기능이 빨라서 좋았다
- 게시글 내에 있는 항목 별 바로가기 기능과, 게시글마다 읽는데 얼마나 걸리는지 나와있는 것도 맘에 들었다

많은 사용자
- 커스터마이징 할 때 오류가 발생해도 사용자가 많으면 고치기가 수월하다
- 특히 한국인 사용자가 많은 테마로 더 편한 면이 있다

Jekyll Chirpy 구조

_config.yml

Jekyll 블로그의 기본 설정 파일
사이트 제목, 설명, URL, 언어, 플러그인 등 전반적인 설정을 정의

_data

언어 설정, 사이드바 구성, 카테고리 또는 태그와 같은 반복적인 데이터 관리에 사용

_includes

재사용이 가능한 header, footer, banner와 같은 HTML을 저장

_layouts

페이지 레이아웃 템플릿을 저장
default.html, post.html 등의 파일이 포함되어 각 페이지의 구조를 정의

_posts

블로그 글을 작성하는 공간
각 파일은 YYYY-MM-DD-title.md 형식으로 저장
Markdown 형식으로 작성하며, YAML front matter로 메타데이터(제목, 날짜, 태그, 카테고리)를 지정

_site

Jekyll 빌드 결과물이 저장되는 디렉터리
사용자가 직접 수정하지 않으며, GitHub Actions 또는 로컬 빌드 시 생성

_tabs

블로그의 탭 네비게이션을 구성
about.md, archive.md와 같은 파일을 포함
탭 메뉴에 표시되는 페이지의 내용과 경로를 정의

assets

정적 파일(css, 이미지, JS 파일 등)을 저장
css/, img/, js/ 등의 하위 디렉터리가 포함

_sass

Sass 파일을 저장
Chirpy 테마의 CSS를 수정하려면 이 디렉터리를 편집

.github

GitHub Actions 설정이 위치
workflows/ 디렉터리에는 Chirpy의 CI/CD 파이프라인 설정이 저장됨

깃허브 블로그 구축 과정

블로그 Repo 생성

저장소 생성
- 깃허브에서 username.github.io Repo 생성
GitHub Pages 활성화
- 저장소 설정 > Pages 섹션에서 브랜치 선택 후 활성화
블로그 업로드
- 작성 후 저장소에 Push → GitHub Pages가 자동으로 GitHub Actions 사용해 배포

Jekyll - Chirpy 테마 적용

Chirpy 복사
- chirpy를 단순 fork하면 이후에 깃허브 잔디 심기가 곤란하니까 clone 후 copy

1
2
3
4


git clone git@github.com:joonlog/joonlog.github.io.git
git clone https://github.com/cotes2020/jekyll-theme-chirpy.git chirpy
cp -r chirpy/* joonlog
cp -r chirpy/.* joonlog

Git 설정

1
2
3
4


cd joonlog

git remote set-url origin git@github.com:joonlog/joonlog.github.io.git
git pull origin main

로컬 테스트(선택)

의존성 설치

1
2
3
4
5
6
7
8
9


sudo dnf install ruby ruby-devel gcc make -y
sudo dnf groupinstall "Development Tools"
sudo gem install bundler

bundle install
npm install

bundle exec jekyll serve
 http://localhost:4000

깃허브 블로그 배포

Git Push

1
2
3


git add .
git commit -am "test"
git push origin main

Repo - 저장소 설정 - 페이지 섹션 - 배포 형식을 GitHub Actions로 변경
- GitHub Actions 말고 기존 껄로 배포하면 index.html만 나타남

- Configure 후 npm 의존성을 “Build with Jekyll” 단계 전에 추가 후에 Commit
```bash
name: npm build
run: npm install && npm run build
```
- ./github/workflows/starter/pages-deploy.yml 삭제
- 삭제 안하면 pages-deploy.yml도 같이 실행되어서 오류 발생

여기까지 하고 브라우저에서 username.github.io로 접속하면 블로그에 테마가 적용된 게 보일 것이다.

글 포스팅

구분	새 페이지 추가	새 게시물 추가
목적	고정 콘텐츠(정적 페이지) 작성	블로그 글(동적 콘텐츠) 작성
위치	프로젝트 루트 또는 서브 디렉토리	`_posts/` 디렉토리
파일명 규칙	자유로운 이름 (`about.md`)	`YYYY-MM-DD-title.md` 형식
URL	`/about`, `/contact` 등	`/year/month/day/title` 형식
목록 표시	목록에 포함되지 않음	블로그 목록에 자동 포함

형식 : yyyy-mm-dd-제목.md
확장자는 .md 또는 .markdown
중간에 공백을 넣지 않음
작성한 파일은 _posts 디렉토리에 위치

Front Matter

사이트의 게시물에 대해 제목 및 레이아웃과 같은 변수와 메타데이터를 설정하기 위해 Markdown 또는 HTML 파일의 맨 위에 YAML 전문을 추가

파일명: YYYY-MM-DD-title.md

1
2
3
4
5
6


---
title : Rocky8 MySQL Replication & HAproxy 연동
date : 2024-12-10 09:00:00 +09:00
categories : [Linux, DB]
tags : [rocky8, mysql, haproxy, replication] #소문자만 가능
---

블로그에 포스팅이 되었는지 확인

참고

공식문서: https://docs.github.com/ko/pages

jekyll chirpy 테마: https://github.com/cotes2020/jekyll-theme-chirpy

GitHub Blog on Joonlog

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

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

2. generate-categories.go 개선

2.1 ioutil 제거

2.2 url 필드 추가

생성 결과 예시

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

Hugo Stack에서 SEO 설정(Google Searche Console)

SEO

GitHub Pages + Hugo 환경 SEO 설정

GitHub Blog에서 Giscuss로 댓글 기능 추가

1. GitHub Discussions 활성화

2. Giscus 앱 설치

3. Giscus 설정값 생성

4. Hugo 설정 파일 수정

5. Git 커밋 후 재배포

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. 메뉴 설정

구현 화면

Jekyll Chirpy 테마에서 Hugo Stack 테마로 블로그 이관하기

Jekyll Chirpy에서 Hugo Stack으로 이관한 이유

블로그 이관 과정

이관 시 포스팅 글 변경점

이후 예정 작업

Hugo 템플릿 Stack 테마로 GitHub Blog 배포하기

Hugo Stack 구조

Hugo Stack 구축

배포 설정

GitHub Pages 설정

배포 확인

참고

Jekyll Chirpy 테마 카테고리 에러 TroubleShooting(2)

문제 재발견

근본 원인

해결 방법

1. Jekyll Archives의 categories 비활성화

2. 카테고리 플러그인 작성

3. 카테고리 목록 페이지 링크 수정

결과

Jekyll Chirpy 테마 카테고리 에러 TroubleShooting(1)

문제 확인

원인

해결 방법

해결

GitHub Blog(Jekyll Chirpy) SEO 설정

SEO

GitHub Pages + Jekyll 환경 SEO 설정

참고

GitHub 블로그(Jekyll Chirpy) 오류 TroubleShooting

2. `generate-categories.go` 개선