Post

Chirpy 홈 화면이 비어 보일 때 점검할 것

Posted
By prof park sungtae
17 min read
Chirpy 홈 화면이 비어 보일 때 점검할 것

Chirpy 테마를 처음 적용했는데 중앙 Home 영역이 비어 보이면 당황하기 쉽습니다.

하지만 대부분은 테마 자체의 문제가 아니라, 포스트 수가 부족하거나 홈 레이아웃이 기본 구조와 맞지 않는 경우가 많습니다.

또 _posts 파일명 규칙이나 Front Matter 형식이 조금만 어긋나도 홈에서 정상적으로 표시되지 않을 수 있습니다.

이 글에서는 홈 화면이 비어 있을 때 먼저 체크해 볼 부분을 차례대로 정리합니다.

1. 아직 발행된 포스트가 없는 경우

가장 단순하지만 제일 먼저 확인해야 하는 부분입니다.

  • _posts 폴더 안에 마크다운 파일이 한 개도 없다면
    Chirpy 홈에는 당연히 포스트 목록이 나타나지 않습니다.
  • 예제 포스트를 하나라도 만들어 두면
    기본 홈 레이아웃에 최신 글이 자동으로 표시됩니다.

테스트용으로 아래처럼 아주 간단한 글을 하나 만들어 보세요.

1
2
3
4
5
6
7

***
title: "테스트 포스트"
date: 2026-04-04 10:00:00 +0900
categories: [test]
tags: [chirpy]
***
홈 화면 노출 확인용 테스트 포스트입니다.

2. _posts 파일명 규칙이 잘못된 경우

Jekyll은 _posts 안의 파일명을 기준으로 글을 인식합니다.

올바른 규칙:

1
2

YYYY-MM-DD-slug.md
예: 2026-04-04-my-first-post.md

자주 하는 실수:

  • 2026-4-4-my-first-post.md (0이 빠진 월/일)
  • 2026-04-04_my-first-post.md (언더스코어 사용)
  • my-first-post.md (날짜가 없음)

이렇게 되어 있으면 Jekyll이 “포스트”로 인식하지 못해
홈 화면 목록에 잡히지 않습니다.

3. Front Matter(상단 설정)가 빠졌거나 문법 오류인 경우

파일 맨 위의 --- 블록이 없거나 형식이 깨져도
해당 파일은 일반 페이지로 처리되거나 빌드에서 무시될 수 있습니다.

정상 예시:

1
2
3
4
5
6
7

***
title: "Chirpy 홈 화면 테스트"
date: 2026-04-04 09:00:00 +0900
categories: [test]
tags: [chirpy, home]
***
본문 내용 시작…

점검 포인트:

  • 맨 처음과 본문 시작 전 --- 가 정확히 두 번 들어가 있는지
  • title: / date: / categories: / tags: 키 이름 오타가 없는지
  • categories: [a, b] 처럼 대괄호 배열 문법이 맞는지

Front Matter에 문법 오류가 있으면
GitHub Actions 빌드에서 빨간 ❌ 로 실패 표시가 나오는 경우가 많습니다.

4. date 가 미래이거나 형식이 잘못된 경우

Chirpy는 기본적으로 date 값을 기준으로 포스트를 정렬합니다.

  • date 가 현재보다 먼 미래로 설정되어 있으면
    일부 설정에서는 목록에서 숨겨지거나 이상하게 정렬될 수 있습니다.
  • 형식은 다음과 같이 쓰는 것이 안전합니다.
1

date: 2026-04-04 09:00:00 +0900
  • 2026/04/04 나 04-04-2026 처럼 다른 형식은 피하는 게 좋습니다.

5. published: false 또는 초안 상태인 경우

Jekyll은 published: false 가 붙은 글이나 _drafts 아래 있는 글을
기본 빌드에서 제외합니다.

  • 글 상단에 이런 설정이 있지 않은지 확인합니다.
1

published: false
  • _drafts 폴더에 있는 글은 _posts 로 옮겨야 홈에 노출됩니다.

6. 홈 레이아웃 파일이 수정되었는지 확인

Chirpy 홈 화면은 보통 index.html 또는 _layouts/home.html 을 기반으로 렌더링됩니다.

초기에 실수로 이 파일들을 크게 수정하거나,
루프 부분을 삭제하면 포스트가 있어도 화면에 아무것도 나오지 않을 수 있습니다.

점검 방법:

  1. 템플릿을 크게 건드린 기억이 있다면
    chirpy-starter 원본 저장소와 비교(diff)해 봅니다.
  2. site.posts 를 순회하는 루프가 존재하는지 확인합니다.

예시 개념:

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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

  <!-- 포스트 카드 렌더링 -->

이 부분이 통째로 삭제되어 있거나
조건문 안에 잘못 감싸져 있으면 목록이 비게 됩니다.

7. GitHub Actions 빌드 상태 확인

코드가 아무리 맞아도 빌드가 실패하면 최신 내용이 배포되지 않습니다.

  1. GitHub 저장소의 Actions 탭을 열어
    최근 워크플로 실행 상태를 확인합니다.
  2. Deploy Jekyll site to Pages 의 상태가 초록색(✅)인지 확인합니다.
  3. 빨간색(❌)이라면 로그를 열고
    • _config.yml 오류
    • 특정 포스트의 Front Matter 에러 등을 먼저 해결해야 합니다.

빌드가 성공해야만 새 포스트가 홈에 반영됩니다.

8. 캐시(브라우저 / Cloudflare 등) 문제 확인

모든 설정이 맞는데도 여전히 홈이 비어 보인다면,
단순 캐시 문제일 수도 있습니다.

  • 브라우저에서 시크릿 모드로 접속해 새로고침.
  • Cloudflare 같은 CDN을 쓰는 경우라면
    캐시 삭제(Purge Cache)를 한 뒤 다시 확인합니다.

9. 마지막 체크 리스트

홈이 비어 있을 때는 아래 질문을 순서대로 점검해 보세요.

  1. _posts 안에 실제 포스트 파일이 한 개 이상 있는가?
  2. 파일명이 YYYY-MM-DD-slug.md 형식을 지켰는가?
  3. Front Matter --- 블록이 정확하게 들어가 있는가?
  4. date 값이 미래 날짜가 아니고, 형식도 올바른가?
  5. published: false 나 _drafts 상태로 남아 있지 않은가?
  6. 홈 템플릿(index.html/home.html)의 포스트 루프를 지워버리지 않았는가?
  7. GitHub Actions 빌드가 성공했는가?
  8. 시크릿 모드/캐시 삭제 후에도 여전히 비어 보이는가?

보통은 1~4번에서 원인이 금방 나오고,
레イ아웃을 많이 만졌다면 6번을 한 번 더 유심히 보면 문제를 찾을 수 있습니다.

troubleshooting
chirpy home jekyll
This post is licensed under CC BY 4.0 by the author.