“테마만 3일째 고르고 있어요” 깃허브 블로그 테마 추천과 선택 기준

깃허브에 jekyll-theme 토픽으로 등록된 테마만 수천 개가 넘어요. 그래서 처음 깃허브 블로그를 만들려는 사람 대부분이 글 한 줄 쓰기 전에 테마 고르기에서 며칠을 흘려보내죠. 먼저 결론부터 말하면, 비전공자가 지금 당장 고를 만한 답은 셋 중 하나예요. 글 위주 기술 블로그면 Chirpy, 포트폴리오를 겸하려면 Minimal Mistakes, 설치 난이도를 최대한 낮추고 싶으면 Beautiful Jekyll. 이 세 개 밖으로 나가는 순간 한글 깨짐과 빌드 오류를 혼자 감당해야 하는 확률이 확 올라가요. 아래에서 왜 이 셋인지, 그리고 테마를 고른 다음 실제로 뭘 건드려야 블로그가 굴러가는지를 순서대로 풀어볼게요.

• “테마만 고르다 일주일이 지나갔어요” 왜 이렇게 어려울까
• 깃허브 블로그 테마, 뭘 기준으로 골라야 하나요?
• 비전공자가 감당할 수 있는 테마는 어떤 게 있나요?
• 테마 적용 방법은 몇 가지이고 뭐가 제일 쉬운가요?
• 테마를 깔고 나서 꼭 건드려야 하는 설정은?
• 테마 수정하다 막히면 Claude Code로 어떻게 푸나요?
• 글을 올렸는데 왜 안 보이나요? 자주 터지는 오류 정리
• 깃허브 블로그 vs 워드프레스·티스토리, 누구에게 맞나요?
• 자주 묻는 질문
• 참고자료

“테마만 고르다 일주일이 지나갔어요” 왜 이렇게 어려울까

테마 고르기가 유독 오래 걸리는 이유는 취향 문제가 아니에요. 판단 기준이 없는 상태에서 선택지가 너무 많기 때문이죠. 깃허브 토픽 페이지에 올라온 Jekyll 테마만 수천 개고, 데모 화면은 다들 예쁘게 만들어 두거든요.

문제는 데모가 예쁜 것과 내가 운영할 수 있는 것이 전혀 다른 얘기라는 점이에요. 어떤 테마는 2019년 이후 커밋이 멈춰 있어서 최신 Ruby나 GitHub Pages 환경에서 빌드 자체가 안 돼요. 어떤 테마는 영문 폰트 기준으로 줄 간격을 잡아 놔서 한글을 넣으면 글자가 서로 붙어 보이고요.

비전공자가 겪는 가장 흔한 순서는 이래요. 예쁜 테마를 Fork → 로컬 실행에서 오류 → 구글 검색 → 해결 방법이 3년 전 글 → 포기하고 다른 테마 Fork → 반복. 여기서 빠져나오려면 “예쁜가”가 아니라 “내가 고칠 수 있는가”로 질문을 바꿔야 해요.

그래서 이 글은 테마 목록 나열이 아니라, 고르는 기준 → 후보 압축 → 적용 → 최소 설정 → 오류 대응까지를 한 번에 붙여서 정리했어요. 순서대로 따라가면 한나절 안에 글이 보이는 상태까지 갈 수 있어요.

깃허브 블로그 테마, 뭘 기준으로 골라야 하나요?

테마 고를 때 봐야 할 건 여섯 가지예요. 이 중 앞의 세 개가 특히 중요한데, 초보자가 막히는 지점 대부분이 여기서 갈리거든요.

첫째, 최근 커밋 날짜. 스타 수는 과거의 인기지 현재의 안전성이 아니에요. 스타 1만 개인데 마지막 커밋이 3년 전인 테마보다, 스타 2천 개인데 지난달에도 커밋이 있는 테마가 훨씬 안전해요. 깃허브 저장소 첫 화면에서 파일 목록 위 “last commit” 표시를 먼저 확인하세요. 1년 이상 멈춰 있으면 후보에서 빼는 게 마음 편해요.

둘째, 문서화 수준. README에 설치 절차가 명령어 단위로 적혀 있는지, 별도 Docs 사이트나 위키가 있는지를 보세요. 문서가 부실한 테마는 설정 하나 바꾸려고 남의 코드를 처음부터 읽어야 해요. Minimal Mistakes처럼 전용 문서 사이트를 갖춘 테마는 그 자체로 진입장벽을 크게 낮춰 줘요.

셋째, 한글 대응. 국내 사용자에겐 이게 성능 점수보다 실질적으로 중요해요. 확인할 건 세 가지예요. 본문 폰트가 시스템 한글 폰트로 fallback 되는지, 줄 간격(line-height)이 1.6 이상인지, 그리고 한글 제목으로 글을 썼을 때 URL이 어떻게 만들어지는지요.

넷째, SEO 기본기. jekyll-seo-tag, jekyll-sitemap, jekyll-feed 플러그인이 기본 포함돼 있는지 _config.yml의 plugins 항목에서 확인하세요. 이 셋이 있으면 메타 태그·사이트맵·RSS가 자동으로 만들어져서 서치콘솔 등록이 훨씬 수월해요. 없으면 직접 넣어야 하는데, 초보자에겐 이게 은근히 큰 일이에요.

다섯째, 커스터마이징 난이도. 색상이나 로고를 바꾸려는데 SCSS 파일 10개를 뒤져야 하는 테마가 있고, _sass/변수파일 하나만 고치면 되는 테마가 있어요. 저장소에서 _sass 폴더 구조를 미리 열어 보면 감이 와요.

여섯째, 라이선스와 크레딧 조건. 대부분 MIT라 자유롭지만, 일부 테마는 푸터의 제작자 표기를 지우지 못하게 하는 조건이 붙어 있어요. 나중에 디자인을 다 갈아엎고 싶을 때 걸림돌이 되니 LICENSE 파일은 한 번 읽어 두세요.

비전공자가 감당할 수 있는 테마는 어떤 게 있나요?

위 기준을 통과하면서 한국어 사용자 레퍼런스도 많은 후보를 추리면 다섯 개 정도가 남아요. 표로 성격부터 먼저 비교해 볼게요. 스타 수나 최종 업데이트 같은 숫자는 계속 바뀌니, 저장소에서 직접 확인하는 걸 전제로 대략의 규모감만 참고하세요.

Chirpy는 요즘 국내 깃허브 블로그에서 가장 많이 보이는 테마예요. 왼쪽 사이드바에 카테고리·태그·아카이브가 정리돼 있고, 글 오른쪽에 목차가 자동으로 붙어요. 코드 블록 복사 버튼, 다크모드, 조회수 연동 같은 기능이 이미 들어 있어서 따로 붙일 게 거의 없죠. 다만 구조가 촘촘한 만큼 레이아웃을 크게 바꾸려면 Liquid 템플릿을 건드려야 해서, 디자인을 확 갈아엎을 생각이라면 부담스러워요.

Minimal Mistakes는 문서화가 이 계열에서 가장 잘 돼 있는 편이에요. 사이드바 표시 여부, 글 목록 형태, 스킨 색상 같은 걸 _config.yml과 프론트매터 옵션으로 조절할 수 있어서 코드를 덜 만져도 돼요. 한 사이트 안에 블로그와 포트폴리오 컬렉션을 나눠 담기 좋아서, 작업물 정리를 겸하려는 사람에게 잘 맞아요.

Beautiful Jekyll은 “오늘 안에 일단 띄우고 싶다”에 가장 가까운 선택지예요. 저장소를 Fork하고 _config.yml의 이름·설명·소셜 링크만 바꿔도 곧바로 사이트가 나와요. 기능이 단순한 대신 확장성은 낮아서, 나중에 욕심이 생기면 테마를 옮기게 될 가능성이 있어요.

Hugo 계열인 PaperMod는 Ruby 환경 설치가 부담스러운 사람에게 대안이 돼요. Jekyll은 로컬 미리보기를 하려면 Ruby와 Bundler를 깔아야 하는데, 이 단계에서 버전 충돌로 막히는 경우가 꽤 많거든요. Hugo는 실행 파일 하나 설치로 끝나고 빌드 속도도 빨라요. 대신 GitHub Pages에 올리려면 GitHub Actions 워크플로 파일을 직접 넣어야 해서, 그 한 단계가 추가된다는 점은 감안해야 해요.

테마 적용 방법은 몇 가지이고 뭐가 제일 쉬운가요?

Jekyll 테마를 붙이는 방법은 크게 네 가지예요. 어떤 걸 고르느냐에 따라 이후 난이도가 완전히 달라져요.

비전공자에게 권하는 경로는 테마가 제공하는 템플릿(Use this template) 또는 Fork예요. remote_theme이 코드는 깔끔하지만, 정작 레이아웃을 바꾸려 할 때 고쳐야 할 파일이 내 저장소에 없어서 더 헤매게 되거든요. 파일이 눈에 보이는 쪽이 배우기에도 낫고 Claude Code 같은 도구에 맡기기에도 좋아요.

로컬 환경 없이 웹에서만 운영하는 것도 가능해요. 깃허브 웹 편집기에서 마크다운 파일을 만들어 커밋하면 Actions가 알아서 빌드하거든요. 다만 한 번 커밋할 때마다 빌드가 끝날 때까지 기다려야 해서, 디자인을 여러 번 고칠 때는 로컬에서 bundle exec jekyll serve로 미리 보는 편이 훨씬 빨라요.

테마를 깔고 나서 꼭 건드려야 하는 설정은?

테마를 붙였다고 끝이 아니에요. 그대로 두면 제작자 이름과 샘플 이미지가 그대로 노출되고, 검색엔진에도 제대로 잡히지 않아요. 최소한 아래 항목은 첫날에 정리하는 게 좋아요.

_config.yml 기본 정보부터 손보세요. title, tagline, description, author, url, baseurl, timezone 정도가 핵심이에요. timezone을 Asia/Seoul로 바꾸지 않으면 오늘 쓴 글이 미래 날짜로 인식돼 목록에서 사라지는 일이 생겨요. 실제로 초보자가 “글이 안 보여요”라고 하는 사례의 상당수가 이 시간대 설정과 발행 시각 문제예요.

한글 가독성도 초반에 잡아 두면 좋아요. 대부분의 테마는 영문 폰트 위주라 한글에서 자간·행간이 답답해 보여요. 커스텀 스타일 파일에 본문 line-height를 1.7~1.8로 올리고, font-family에 한글 웹폰트나 시스템 폰트를 앞쪽에 추가하는 정도만 해도 체감이 크게 달라져요.

카테고리와 태그 구조는 글이 쌓이기 전에 정해야 나중에 갈아엎지 않아요. 권장하는 형태는 카테고리는 3~5개로 크게, 태그는 자유롭게예요. 카테고리를 10개 넘게 만들면 각 카테고리에 글이 한두 개씩만 쌓여서 목록 페이지가 텅 비어 보이거든요. Chirpy처럼 계층형 카테고리를 지원하는 테마는 상위 1단계·하위 1단계까지만 쓰는 게 관리하기 편해요.

댓글은 Giscus를 많이 써요. 깃허브 Discussions를 댓글 저장소로 쓰는 방식이라 별도 서비스 가입이 없고, 공식 사이트에서 저장소 이름을 넣으면 설정 스크립트를 만들어 줘요. 다만 댓글을 남기려면 방문자도 깃허브 계정이 있어야 해서, 일반 독자 대상 블로그라면 참여율이 낮다는 점은 알고 시작하는 게 좋아요.

SEO 기본 세팅은 사이트맵 확인 → 서치콘솔 등록 순이에요. 배포 후 내주소/sitemap.xml과 내주소/feed.xml이 열리는지 먼저 확인하고, 열리면 구글 서치콘솔에 도메인 또는 URL 접두어로 등록한 뒤 사이트맵 주소를 제출하세요. 네이버 서치어드바이저에도 같은 방식으로 등록할 수 있어요. 깃허브 페이지는 정적 HTML이라 크롤링 자체는 잘 되는 편이지만, 등록을 안 하면 색인까지 시간이 오래 걸려요.

테마 수정하다 막히면 Claude Code로 어떻게 푸나요?

테마 커스터마이징에서 비전공자가 막히는 지점은 대개 Liquid 템플릿 문법과 SCSS 변수예요. {% for post in site.posts %} 같은 코드가 어디서 무엇을 반복하는지 감이 안 오면, 사이드바 항목 하나 빼는 것도 손을 못 대게 되죠.

이때 Claude Code 같은 터미널 기반 AI 코딩 도구가 유용한 이유는, 파일을 붙여넣지 않아도 프로젝트 폴더 전체를 읽고 어떤 파일을 고쳐야 하는지 먼저 찾아 주기 때문이에요. 블로그 폴더에서 실행한 뒤 자연어로 요청하면 되고요.

요청을 쓸 때는 세 가지를 같이 주면 결과가 훨씬 정확해져요. 지금 화면에서 보이는 상태, 원하는 결과, 건드리면 안 되는 범위예요.

반대로 피해야 할 요청은 “블로그를 예쁘게 만들어줘” 같은 통째 맡기기예요. 범위가 넓으면 여러 파일이 한꺼번에 바뀌고, 뭔가 깨졌을 때 어디를 되돌려야 할지 알 수 없게 돼요. 한 번에 하나씩, 바꾼 뒤 로컬에서 확인하고 커밋하는 리듬이 결과적으로 더 빨라요.

그리고 커밋을 자주 하는 습관이 사실상의 안전장치예요. 수정 전에 커밋해 두면 문제가 생겨도 이전 상태로 되돌릴 수 있어요. 깃을 잘 모르더라도 git add . → git commit -m "메시지" 두 줄만 익혀 두면 충분해요.

AI가 만들어 준 코드가 항상 맞지는 않는다는 점도 염두에 두세요. 특히 Jekyll 버전에 따라 지원되지 않는 문법을 제안하는 경우가 있어요. 빌드 오류가 나면 오류 메시지 전문을 그대로 붙여 다시 물어보는 게 가장 빠른 해결 경로예요. 메시지를 요약해서 전달하면 진짜 원인이 담긴 줄이 빠져서 엉뚱한 답이 돌아오거든요.

글을 올렸는데 왜 안 보이나요? 자주 터지는 오류 정리

깃허브 블로그 초반에 나오는 문제는 종류가 생각보다 몇 개 안 돼요. 아래 순서로 점검하면 대부분 해결돼요.

1) 파일명 형식이 틀렸을 때. 글 파일은 _posts 폴더 안에 2026-09-16-제목.md 형식이어야 해요. 날짜 구분자가 점이거나 자릿수가 한 자리면(예: 2026-9-16) 아예 글로 인식되지 않아요.

2) 프론트매터가 빠졌거나 문법이 깨졌을 때. 파일 맨 위 --- 사이에 title, date 등이 들어가야 해요. 제목에 콜론(:)이 들어가면 YAML이 깨지므로 큰따옴표로 감싸야 해요. 들여쓰기에 탭을 쓰면 오류가 나니 공백을 쓰세요.

3) 날짜가 미래일 때. date를 오늘보다 뒤로 적었거나 timezone 설정이 없어서 시차 때문에 미래로 계산되면 글이 숨겨져요. Jekyll은 기본적으로 미래 글을 빌드에서 제외하거든요.

4) 빌드가 실패했을 때. 저장소 Actions 탭을 열어 최근 실행이 빨간색인지 보세요. 실패한 작업을 클릭해 로그를 펼치면 어느 파일 몇 번째 줄이 문제인지 나와요. 로그 맨 아래가 아니라 Error가 처음 등장한 줄을 찾아 읽는 게 요령이에요.

5) 배포는 됐는데 디자인만 깨질 때. 거의 baseurl 문제예요. 저장소 이름이 사용자명.github.io가 아니면 baseurl에 저장소 이름을 넣어야 CSS 경로가 맞아요. 로컬에선 멀쩡한데 배포하면 글자만 남는 전형적인 증상이죠.

6) 로컬은 되는데 배포에서만 깨질 때. GitHub Pages 기본 빌드는 허용된 플러그인만 실행해요. 화이트리스트에 없는 플러그인을 쓰면 로컬과 결과가 달라져요. 이 경우 GitHub Actions로 직접 빌드해서 결과물을 올리는 방식으로 바꾸면 플러그인 제약에서 벗어날 수 있어요.

깃허브 블로그 vs 워드프레스·티스토리, 누구에게 맞나요?

테마를 고르기 전에 사실 이 질문을 먼저 정리하는 게 순서일 수도 있어요. 깃허브 블로그는 장점이 뚜렷한 만큼 한계도 분명하거든요.

깃허브 블로그가 잘 맞는 사람은 코드와 기록을 함께 남기고 싶은 사람이에요. 마크다운으로 쓰고 커밋하는 흐름이 작업 습관과 맞물리고, 글이 전부 텍스트 파일로 남아 플랫폼이 사라질 걱정도 없어요. 포트폴리오로 쓰기에도 저장소 자체가 근거가 되죠.

반대로 광고 수익이 목표라면 깃허브 블로그는 최적의 출발점이 아니에요. 글쓰기에 커밋이 필요하다는 마찰이 발행 빈도를 떨어뜨리고, 테마마다 광고를 넣을 자리를 직접 만들어야 해요. 수익형 블로그를 염두에 두고 있다면 워드프레스나 티스토리로 시작해 발행 속도를 확보하는 편이 현실적이에요.

그래서 상황별 정리는 이래요. 개발·학습 기록과 포트폴리오가 목적이면 깃허브 블로그에 Chirpy나 Minimal Mistakes, 광고 수익과 확장을 노린다면 워드프레스, 일단 글쓰기 습관부터 만들고 싶다면 티스토리. 둘을 병행하는 것도 나쁘지 않아요. 실제로 학습 로그는 깃허브에, 정리된 글은 워드프레스에 나눠 올리는 방식으로 운영하는 사례도 많거든요.

자주 묻는 질문

이미 운영 중인 깃허브 블로그의 테마만 나중에 바꿀 수 있나요?

가능해요. 글 파일이 마크다운이라 _posts 폴더를 새 테마 저장소로 옮기면 대부분 그대로 살아나요. 다만 프론트매터 키 이름이 다를 수 있어서 categories·tags·이미지 경로는 손봐야 하고, 기존 글 주소가 바뀌면 검색 유입이 끊기므로 permalink 형식을 이전과 같게 맞추는 게 중요해요.

무료 테마만으로 충분한가요?

대부분의 경우 충분해요. Chirpy, Minimal Mistakes 같은 대표 테마는 무료 오픈소스인데도 목차·다크모드·SEO 플러그인·댓글 연동까지 갖추고 있어요. 유료 템플릿은 디자인 완성도가 높은 대신 유지보수가 끊기면 대응이 어려울 수 있으니, 업데이트 이력을 먼저 확인하세요.

로컬 환경 설치 없이 웹에서만 운영해도 되나요?

돼요. 깃허브 웹 편집기에서 마크다운 파일을 만들고 커밋하면 자동으로 빌드·배포돼요. 다만 디자인이나 레이아웃을 여러 번 수정할 때는 매번 배포를 기다려야 해서, 그럴 계획이면 로컬 미리보기 환경을 갖추는 게 시간을 아껴 줘요.

깃허브 블로그는 구글에 잘 노출되나요?

정적 HTML로 만들어져 크롤링에는 유리한 편이에요. 다만 자동으로 잘 잡히는 건 아니라서, 사이트맵이 생성되는지 확인하고 구글 서치콘솔과 네이버 서치어드바이저에 직접 등록해야 해요. 색인까지는 보통 수일에서 수주가 걸리니 초반에 조급해하지 않는 게 좋아요.

테마를 고를 때 스타 수가 가장 중요한 기준인가요?

아니에요. 스타 수보다 최근 커밋 날짜와 이슈 응답 여부가 더 중요해요. 스타가 많아도 유지보수가 멈춘 테마는 환경이 바뀌면 빌드가 깨지고, 그때 도와줄 사람이 없어요. 스타는 참고 지표로만 보고 활성도를 우선 확인하세요.

참고자료

• GitHub Pages 공식 문서 — 저장소 설정, 배포 방식, 커스텀 도메인 연결 안내
• Jekyll 공식 문서 — 설치, 프론트매터, Liquid 문법, 빌드 옵션 설명
• Hugo 공식 문서 — Ruby 없이 정적 사이트를 만들고 싶을 때 참고
• 구글 서치콘솔 — 사이트 소유 확인과 사이트맵 제출로 색인 요청

테마 고르기에서 시간을 잡아먹는 이유는 선택지가 많아서가 아니라 기준이 없어서예요. 최근 커밋·문서화·한글 대응 이 세 가지만 걸러도 후보는 순식간에 서너 개로 줄어들고, 그중에서 목적에 맞는 하나를 집으면 끝이에요. 글 중심이면 Chirpy, 포트폴리오를 겸하면 Minimal Mistakes, 오늘 안에 띄우고 싶으면 Beautiful Jekyll — 이 순서로 결정하는 걸 권해요. 그리고 테마는 언제든 바꿀 수 있지만 안 쓴 글은 되돌릴 수 없으니, 완벽한 디자인보다 첫 글 발행을 먼저 하는 쪽이 결국 더 빨리 굴러가요. 막히는 지점이 생기면 오류 메시지 전문을 그대로 들고 AI 도구에 물어보는 습관 하나만 들여도 대부분은 그날 안에 풀려요.

함께 보면 좋은 글

• 워드프레스 테마 속도, 테마만 바꾸면 정말 빨라질까?
• 블로그 스팟 애드센스 연결, 신청 5분보다 어려운 건 따로 있어요
• “접속이 안 되는데요?” 알드라이브 FTP 접속 방법, 첫 연결부터 오류 해결까지