Jekyll on Joonlog

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