지킬 Chirpy 테마 이미지 완벽 마스터 가이드: 엑박 해결부터 썸네일 최적화까지
지킬 Chirpy 테마에서 발생하는 이미지 엑박 현상 해결책부터 대표 이미지, 썸네일 설정, 용량 최적화, 자주 발생하는 에러 트러블슈팅까지 하나로 총정리했습니다.
지킬(Jekyll)의 Chirpy 테마는 깔끔하고 세련된 디자인으로 많은 개발자와 비즈니스 블로거들의 사랑을 받고 있습니다. 하지만 마크다운(Markdown) 기반의 정적 사이트 특성상, 처음 블로그를 구축하면 이미지가 깨지는 엑박 현상을 겪거나 대표 이미지 및 썸네일 설정법이 헷갈려 당황하는 경우가 많습니다.
이 글에서는 Chirpy 테마에서 이미지가 보이지 않는 근본적인 원인과 해결책을 파악하고, 대표 이미지(Featured Image)와 썸네일 설정, 로딩 속도를 올리는 크기 조절 기술, 그리고 실무에서 자주 마주치는 에러 케이스까지 빠짐없이 정리해 드립니다. 이 가이드를 마스터하시면 가독성 높은 고품질 포스트를 발행하는 것은 물론, 구글 검색엔진이 좋아하는 웹 최적화 구조를 완성하는 구체적인 이득을 얻으실 수 있습니다.
1. 이미지 엑박 현상 원인과 올바른 경로 설정법
Chirpy 테마에서 포스트를 배포했을 때 이미지가 깨지는 가장 큰 원인은 상대 경로 지정 오류와 지킬 자체의 baseurl 설정 누락 때문입니다.
1-1. 이미지 미표시 문제 해결 (Fix Post Image Not Showing)
로컬 컴퓨터 환경에서는 이미지가 잘 보이지만, 깃허브 페이지(GitHub Pages)에 배포만 하면 이미지가 깨지는 현상이 발생합니다. 이는 마크다운 파일에서 경로를 지정할 때 절대 경로와 상대 경로의 개념이 어긋났기 때문입니다. Chirpy 테마는 기본적으로 assets/img/ 디렉터리 내부에 이미지를 보관하도록 권장합니다. 본문에서 이미지를 불러올 때는 반드시 맨 앞에 슬래시(/)를 붙인 루트 상대 경로를 사용해야 배포 후에도 주소가 뒤틀리지 않습니다.
1
2
3
4
5
6
<!-- 잘못된 예: 로컬 환경이나 특정 페이지에서 깨질 수 있음 -->
<!-- 올바른 예: 루트 상대 경로 지정 -->
1-2. 마크다운 이미지 문법과 경로 최적화
Chirpy 테마는 지킬 빌드 시스템을 따르기 때문에, 설정 파일인 _config.yml의 url과 baseurl 속성이 매우 중요합니다. 만약 본인의 저장소 이름이 유저네임 가상 도메인(예: username.github.io/blog) 형태라면, baseurl에 /blog가 정확히 입력되어 있어야 합니다. 반대로 username.github.io처럼 루트 도메인을 그대로 쓰는 경우라면 baseurl은 빈 문자열("")로 두어야 합니다. 경로 지정 시 이 주소가 자동으로 연동되므로, 앞서 언급한 루트 상대 경로(/assets/img/...) 규칙만 철저히 지키면 구글 크롤러가 이미지 주소를 정확히 수집하여 이미지 검색 탭에도 안정적으로 노출됩니다.
1-3. 자주 발생하는 에러 케이스 체크리스트
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 로컬에서는 정상, 배포 후 깨짐 | baseurl 미설정 또는 상대 경로 사용 | /assets/img/... 루트 상대 경로로 통일 |
| 특정 글에서만 이미지 깨짐 | 파일명에 한글·공백·특수문자 포함 | 영문 소문자 + 하이픈(-) 조합으로 파일명 변경 |
| 빌드는 성공하지만 404 발생 | 이미지 파일을 실제로 커밋하지 않음 | git add로 이미지 파일이 포함됐는지 확인 |
| 모바일에서만 레이아웃 깨짐 | 이미지 원본 해상도가 과도하게 큼 | width/height 속성 명시 + 반응형 클래스 적용 |
| GitHub Actions 빌드 실패 | 이미지 경로 대소문자 불일치 (Linux는 대소문자 구분) | 실제 파일명과 마크다운 경로의 대소문자 일치 확인 |
팁: GitHub Pages는 Linux 서버에서 빌드되므로 Windows·macOS에서는 문제없던 대소문자 불일치가 배포 후에만 에러로 나타나는 경우가 흔합니다. 파일명은 항상 소문자로 통일하는 것이 안전합니다.
2. 대표 이미지 및 썸네일 설정과 크기 최적화 테크닉
본문 이미지를 올바르게 띄웠다면, 이제 독자의 시선을 사로잡는 블로그 홈 화면의 대표 이미지(Featured Image)와 썸네일(Thumbnail)을 정교하게 제어할 차례입니다.
2-1. Chirpy 초보자를 위한 대표 이미지 및 썸네일 설정 (Featured & Thumbnail Guide)
Chirpy 테마는 포스트 맨 위 Front Matter에 몇 줄의 메타데이터 코드를 추가하는 것만으로 멋진 배경 이미지와 대표 이미지를 생성해 줍니다. 포스트 최상단의 --- 사이에 아래 속성을 정의해 주면 됩니다.
1
2
3
image:
path: /assets/img/posts/main-cover.png
alt: 지킬 Chirpy 테마 이미지 가이드 대표 이미지
여기서 path 속성에 지정된 이미지는 포스트 본문 맨 위에 거대한 대표 이미지로 출력되며, 동시에 블로그 메인 홈 화면에서 이 글을 소개하는 썸네일 이미지로 자동 연동됩니다. alt 태그는 이미지의 시각 장애인용 대체 텍스트이자 구글 SEO의 핵심 평가 요소이므로, 글의 주제를 명확히 담은 핵심 키워드를 조합하여 작성하는 것이 유리합니다.
2-2. LQIP(저해상도 미리보기)로 체감 속도 높이기
Chirpy는 이미지 로딩 중 흐릿한 미리보기를 보여주는 LQIP 기능을 지원합니다. lqip 속성에 base64로 인코딩된 초저해상도 썸네일을 넣어주면, 큰 이미지가 로드되는 동안 사용자가 빈 화면을 보지 않아도 됩니다.
1
2
3
4
image:
path: /assets/img/posts/main-cover.png
lqip: data:image/webp;base64,UklGRiQAAABXRUJQVlA4IBgAAAAwAQCdASoEAAQAAkA4JZQCdAEO/...
alt: 대표 이미지 설명
base64 값은 cwebp나 온라인 LQIP 생성 도구로 원본 이미지를 가로 20px 내외로 축소·압축해 추출할 수 있습니다.
2-3. 레이아웃을 해치지 않는 이미지 리사이즈(Resize) 가이드
고해상도 이미지를 그대로 업로드하면 스마트폰 화면에서 이미지가 잘리거나, 페이지 로딩 속도가 느려져 독자가 이탈하는 문제가 발생합니다. Chirpy 테마는 크람다운(Kramdown) 프로세서를 사용하므로 본문 마크다운 코드 바로 뒤에 미디어 속성을 부여하여 이미지 크기와 정렬을 조절할 수 있습니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- 이미지 가로/세로 크기를 지정하고 중앙 정렬하는 Kramdown 문법 -->
{: width="800" height="450" .normal}
<!-- 좌측/우측 정렬 + 텍스트 줄바꿈 -->
{: width="400" .right}
<!-- 어두운 테마/밝은 테마에 따라 다른 이미지 표시 -->
{: .light }
{: .dark }
<!-- 이미지 캡션 추가 -->
_이미지 하단에 표시되는 캡션 텍스트입니다_
width와 height를 명시적으로 함께 지정하면 이미지가 로딩되기 전에도 브라우저가 자리를 미리 확보해 두기 때문에, 레이아웃이 갑자기 밀리는 누적 레이아웃 이동(CLS) 문제도 함께 줄일 수 있습니다. 이는 구글의 Core Web Vitals 핵심 지표 중 하나입니다.
2-4. 파일 용량 최적화: WebP 변환과 반응형 이미지
이미지 파일 자체의 용량을 최적화하는 것도 필수적입니다.
- 블로그에 사진을 업로드하기 전 가로 폭을 최대 1200px 이하로 맞추세요.
- 파일 포맷은 JPG·PNG 대신 압축률이 뛰어난 WebP 포맷으로 변환해 저장하세요.
- 대표 이미지는 1200×630px(OG 이미지 비율)로 별도 제작하면 SNS 공유 시에도 깨지지 않습니다.
- 가능하다면
srcset을 활용한 반응형 이미지 처리로, 모바일에는 작은 용량을, 데스크톱에는 고해상도 이미지를 제공하세요.
1
2
# cwebp로 PNG/JPG를 WebP로 일괄 변환하는 예시
cwebp -q 80 sample.png -o sample.webp
웹사이트 속도가 대폭 향상되면서 구글의 사용자 경험 지표(Core Web Vitals) 점수가 올라가 상위 노출에 압도적으로 유리해집니다.
3. SEO 관점에서 챙겨야 할 추가 체크포인트
- alt 텍스트는 모든 이미지에 작성: 대표 이미지뿐 아니라 본문 삽입 이미지에도 빠짐없이 alt를 채워야 구글 이미지 검색 유입을 기대할 수 있습니다.
- 이미지 사이트맵 자동 포함 확인: Chirpy의
jekyll-sitemap플러그인은 기본적으로 페이지 sitemap만 생성하므로, 이미지 SEO를 강화하려면 구글 서치 콘솔에서 이미지 색인 현황을 별도로 점검하세요. - 파일명에 키워드 포함:
sample.png대신chirpy-image-guide-cover.webp처럼 핵심 키워드를 파일명에 넣으면 이미지 검색 노출에 도움이 됩니다. - CDN 활용: Cloudinary 등 외부 CDN에 이미지를 올리고
image: path:에 전체 URL을 지정하면 GitHub Pages 저장 용량 부담을 줄이고 로딩 속도도 개선할 수 있습니다.
결론
지킬 Chirpy 테마에서 이미지를 다루는 일은 다음 네 가지 공식만 이해하면 누구나 완벽하게 제어할 수 있습니다.
- 경로 규칙: 루트 상대 경로(
/assets/img/...) 사용 - Front Matter 메타데이터로 대표 이미지·alt·LQIP 설정
- width/height 명시 + WebP 변환을 통한 용량·속도 최적화
- 파일명·대소문자·sitemap 점검을 통한 SEO 마무리
흩어져 있던 이미지 트러블슈팅 지식을 하나로 모아 구조를 깔끔하게 정돈해 보세요. 깨지는 이미지 없이 완벽한 레이아웃을 유지할 때 독자의 신뢰도와 체류 시간이 동시에 상승합니다.
수익형 자동화 블로그 구축과 검색 엔진 최적화의 최신 트렌드를 선점하세요!
뉴스레터를 구독하시면, 복잡한 지킬 소스코드 디버깅부터 AI(Claude, n8n)를 활용한 고품질 콘텐츠 자동 생성 기법까지 현업의 생생한 노하우를 가장 빠르게 전달해 드립니다. 지금 바로 뉴스레터를 구독하시고 차별화된 블로그 자산을 구축해 보세요!