깃허브 블로그는 Claude Code에게 한 단계씩 부탁하면 코딩을 배워본 적이 없어도 계정 생성부터 첫 글 발행까지 1시간 안팎이면 내 github.io 주소로 열 수 있어요. 대신 막히는 지점은 거의 정해져 있어요. 커밋은 했는데 블로그에 아무 변화가 없는 푸시 누락, 그리고 파일명 한 글자 때문에 조용히 사라지는 첫 글이에요. 아래에서는 저장소 만들기, GitHub Pages 배포, 첫 글 발행을 순서대로 짚고 자주 나는 배포 오류를 해결하는 순서까지 정리했어요. 끝에는 무료 깃허브 블로그와 워드프레스를 같은 기준으로 비교해서, 기록용인지 수익용인지에 따라 어디서 시작할지 고를 수 있게 했어요.
- 깃허브 블로그는 어떻게 굴러가고, 정말 무료일까
- 계정부터 저장소까지, Claude Code에게 이렇게 부탁해요
- 커밋과 푸시, 여기서 제일 많이 헷갈려요
- 테마 고르고 GitHub Pages로 배포하기
- 첫 글 발행, 그리고 배포 오류 해결 순서
- 무료 깃허브 블로그 vs 워드프레스, 목적에 따라 골라요
- 이럴 땐 어떻게?
- 참고자료
깃허브 블로그는 어떻게 굴러가고, 정말 무료일까
📌 핵심 요약
깃허브 블로그는 Claude Code에게 단계별로 부탁하면 1시간 안팎에 무료 github.io 주소로 띄울 수 있고, 막히는 곳은 대부분 커밋·푸시 개념과 글 파일명 규칙이에요.
깃허브 블로그는 GitHub Pages라는 무료 호스팅 위에 올린 정적 사이트예요. 정적 사이트는 미리 만들어둔 HTML 파일을 방문자에게 그대로 보여주는 방식이에요.
워드프레스는 반대예요. 누가 글을 열 때마다 서버가 데이터베이스에서 글을 꺼내 페이지를 조립해요. 그래서 서버가 필요하고 호스팅 비용이 들어요.
깃허브 블로그에서 그 조립은 Jekyll이라는 도구가 미리 해둬요. 마크다운(.md)으로 글을 쓰면 Jekyll이 테마를 입혀 HTML로 바꿔줘요. GitHub Pages가 Jekyll을 기본 지원해서 서버를 따로 빌릴 필요가 없어요.
주소 규칙도 알아두면 좋아요. 저장소(repository)는 블로그 파일을 담는 온라인 폴더예요. 저장소 이름을 사용자명.github.io로 만들면 https://사용자명.github.io 주소가 생겨요. 이름이 다르면 주소 뒤에 /저장소이름이 붙어요.
무료인 건 맞지만 조건이 있어요. 공개 저장소라면 무료 플랜으로 쓸 수 있고, 비공개 저장소로 Pages를 운영하려면 유료 플랜이 필요해요. 공식 문서에는 사이트 용량 1GB, 월 대역폭 100GB 수준의 권장 한도가 안내돼 있어요. 이미지를 장당 500KB로 잡아도 2,000장 가까이 되는 크기라 개인 블로그가 닿기는 어려워요. 한도는 바뀔 수 있으니 공식 문서에서 한 번 확인해 주세요.
공개 저장소라는 건 글 원고도 공개된다는 뜻이에요. 쓰다 만 초안을 푸시하면 누구나 저장소에서 읽을 수 있어요. _drafts 폴더는 사이트에는 안 올라가지만 저장소에서는 보이니, 민감한 초안은 아예 푸시하지 않는 게 안전해요.
계정부터 저장소까지, Claude Code에게 이렇게 부탁해요
준비물은 세 가지예요. 이메일 주소, Claude Code가 설치된 컴퓨터, 그리고 Git이에요. Claude Code의 설치 방법과 요금제는 자주 바뀌니 공식 문서에서 확인하는 게 좋아요. Git 설치 여부는 Claude Code에게 “내 컴퓨터에 git이 있는지 확인해줘”라고 먼저 물어보면 돼요.
역할 분담을 정해두면 덜 헤매요. 회원가입, 이메일 인증, 로그인 승인처럼 본인 확인이 필요한 일은 내가 하고, 폴더 만들기·명령어 실행·파일 작성은 Claude Code에게 맡기는 구조예요.
가입할 때 사용자명(username)은 신중하게 정하세요. 이 이름이 그대로 블로그 주소가 돼요. 영문 소문자로 짧게 짓는 게 좋고, 나중에 바꾸면 주소도 바뀌어서 이미 공유한 링크가 끊겨요.
작업 폴더 만들고 Claude Code 열기
github-blog처럼 영문 이름의 폴더를 만들고, 터미널에서 그 폴더로 이동한 뒤 claude를 실행해요. 한글 폴더명은 경로 오류를 부르는 경우가 있어요.
깃허브 로그인 연결하기
“GitHub CLI로 깃허브 로그인을 도와줘”라고 하면 gh auth login 절차를 안내해줘요. 깃허브는 비밀번호만으로 푸시하는 방식을 막아둬서, 브라우저에 뜬 코드를 입력하는 이 인증 단계가 꼭 필요해요.
저장소 생성 부탁하기
아래 프롬프트처럼 사용자명과 원하는 결과를 구체적으로 알려줘요.
연결 상태 확인하기
“원격 저장소 연결 상태를 보여줘”라고 하면 git remote -v 결과가 나와요. origin 옆에 내 사용자명.github.io 주소가 보이면 성공이에요.
“나는 코딩을 처음 해보는 초보야. 깃허브 사용자명은 myname이야. myname.github.io라는 공개 저장소를 만들고 지금 폴더와 연결해줘. 명령어를 실행하기 전에 무엇을 하는지 한 줄씩 설명해줘.”
마지막 문장이 핵심이에요. Claude Code는 명령어를 실행하기 전에 승인을 묻는데, 설명을 요청해두면 무엇을 승인하는지 알고 누를 수 있어요. 모르는 명령어가 나오면 그 자리에서 “이게 무슨 뜻이야?”라고 되물으면 돼요.
커밋과 푸시, 여기서 제일 많이 헷갈려요
깃허브 블로그에서 가장 흔한 질문은 “분명 저장했는데 왜 안 뜨지?”예요. 원인은 대부분 저장·커밋·푸시를 같은 것으로 여기는 데 있어요.
택배로 비유하면 쉬워요. 파일 저장(Ctrl+S)은 물건을 내 방에 만들어두는 거예요. add는 보낼 물건을 상자에 담는 단계, 커밋(commit)은 상자를 봉하고 “첫 글 추가” 같은 메모를 붙이는 단계예요. 푸시(push)는 그 상자를 깃허브라는 창고로 실제로 보내는 단계예요.
커밋까지만 하면 상자는 아직 내 방에 있어요. 깃허브가 받은 게 없으니 블로그도 그대로예요. 이때 git status를 실행하면 “Your branch is ahead of ‘origin/main’ by 1 commit”이라는 문장이 보여요. 보낼 상자가 1개 남았다는 뜻이에요.
명령어를 외울 필요는 없어요. “변경한 파일 커밋하고 푸시해줘”라고 하면 세 단계를 한 번에 처리해줘요. 커밋 메시지는 나중에 기록을 찾을 때 쓰이니 “소개 페이지 문구 수정”처럼 무엇을 바꿨는지 적어달라고 하세요.
자주 부딪히는 또 하나가 push rejected 오류예요. 깃허브 웹사이트에서 파일을 직접 고친 뒤 내 컴퓨터에서 또 푸시하면 생겨요. 창고에 내가 모르는 상자가 먼저 들어와 있으니 받아오라는 신호예요. “pull로 최신 내용 먼저 받아온 다음 푸시해줘”라고 부탁하면 돼요.
💡 꼭 알아두세요
수정은 한 곳에서만 하는 습관을 들이면 충돌 오류가 크게 줄어요. 웹에서 고쳤다면 작업 전에 pull부터 하고, 막히면 git status 결과를 Claude Code에게 그대로 보여주세요.
테마 고르고 GitHub Pages로 배포하기
디자인을 처음부터 짤 필요는 없어요. Jekyll 테마를 가져와 설정만 바꾸는 게 일반적인 흐름이에요. 입문자가 많이 비교하는 건 아래 세 가지예요.
| 테마 | 특징 | 배포 방식 | 어울리는 사람 |
|---|---|---|---|
| Chirpy | 다크 모드, 카테고리·태그·검색 기본 탑재 | 스타터 템플릿 + GitHub Actions | 공부 기록, 기술 블로그 |
| Minimal Mistakes | 레이아웃이 다양하고 문서·포트폴리오형에 강함 | remote_theme 설정 또는 템플릿 복제 | 블로그와 포트폴리오를 한곳에 |
| Minima | Jekyll 기본 테마, 설정 항목이 적음 | 브랜치에서 바로 배포 | 주소부터 띄워보고 싶은 사람 |
테마를 정했다면 “Chirpy 스타터 템플릿으로 내 저장소를 구성해줘. 사이트 제목은 OO, 언어는 한국어, 시간대는 Asia/Seoul로 해줘”처럼 부탁해요.
다음은 깃허브 웹에서 직접 할 설정이에요. 저장소의 Settings → Pages에서 Build and deployment의 Source를 골라요. 브랜치 파일을 바로 빌드하는 Deploy from a branch와, 워크플로 파일로 빌드하는 GitHub Actions 두 가지예요.
여기서 많이 막혀요. Actions용으로 만든 테마인데 Source를 브랜치로 두면 블로그 대신 README만 보이거나 레이아웃이 깨져요. 테마 설명에 적힌 배포 방식과 Source 설정을 꼭 맞춰주세요.
사이트 전체 설정 파일인 _config.yml도 한 번은 열어봐야 해요. 특히 url과 baseurl이 중요해요. 사용자명.github.io 저장소라면 url에 https://사용자명.github.io를 넣고 baseurl은 비워두는 게 기본이에요. 이 값이 어긋나면 CSS 경로가 틀려져 글자만 보이는 화면이 나와요.
푸시 후에는 저장소 상단 Actions 탭에서 진행 상황을 봐요. 노란 점은 빌드 중, 초록 체크는 배포 완료, 빨간 X는 실패예요. 초록 체크가 뜨고 몇 분 안에 주소에 반영되는 게 보통이에요.
내 컴퓨터에서 미리 보려면 Ruby와 Bundler가 필요해요. Windows는 Devkit이 포함된 RubyInstaller를, macOS는 기본 Ruby가 오래된 경우가 많아 Homebrew 등으로 따로 설치하는 편이 무난해요. bundle exec jekyll serve를 실행하면 http://localhost:4000에서 볼 수 있어요. 처음엔 건너뛰고 Actions 결과로 확인해도 충분해요.
첫 글 발행, 그리고 배포 오류 해결 순서
글은 _posts 폴더에 마크다운 파일로 넣어요. 파일명은 반드시 연-월-일-제목.md 형식이어야 해요. 예를 들면 2026-09-11-first-post.md예요. 제목 부분은 글 주소가 되니 영문 소문자와 하이픈으로 쓰는 게 깔끔해요.
파일 맨 위에는 Front Matter를 붙여요. 글의 제목·날짜·분류를 적는 머리표로, — 줄 두 개 사이에 적어요.
---
title: 깃허브 블로그 첫 글
date: 2026-09-11 20:00:00 +0900
categories: [기록]
tags: [github, 블로그]
---date 끝의 +0900은 한국 시간이라는 표시예요. 이걸 빼면 시간이 다르게 해석될 수 있어요. 밤에 쓴 글이 아직 오지 않은 “미래 글”로 판단되면 Jekyll은 기본 설정상 그 글을 빌드에서 빼요. 오류 메시지 없이 글만 조용히 사라져서 가장 찾기 어려운 원인 중 하나예요.
본문 마크다운은 몇 가지면 충분해요. ## 뒤에 쓰면 소제목, **로 감싸면 굵은 글씨, 줄 앞에 – 를 쓰면 목록이에요. “_posts에 오늘 날짜로 첫 글 파일을 만들고 Front Matter를 채워줘. 본문은 내가 쓸게”라고 하면 틀을 잡아줘요.
배포가 실패하면 Actions 탭의 빨간 X를 눌러 실패한 단계(job)를 열어요. 빨간 글씨 오류 줄을 복사해 Claude Code에 붙여넣고 “이 오류의 원인과 수정 방법을 알려줘”라고 하면 돼요. 대부분 파일 몇 줄만 고치면 해결되는 문제예요.
자주 나오는 원인은 YAML 들여쓰기에 탭 문자가 섞였거나, 따옴표를 닫지 않았거나, 테마가 요구하는 설정이 빠진 경우예요. Chirpy 스타터는 배포 전에 링크를 검사하는 단계가 있어서 깨진 내부 링크 하나로도 배포가 멈출 수 있어요.
📋 글이 안 보일 때 점검 체크리스트
✓ 파일명이 2026-09-11-제목.md 형식인가요
✓ Front Matter 위아래 — 줄이 모두 있나요
✓ date가 현재보다 미래가 아닌가요(+0900 포함)
✓ 커밋만 하고 푸시를 빠뜨리지 않았나요
✓ Actions 탭이 초록 체크인가요
✓ 강력 새로고침(Ctrl+Shift+R, 맥은 Cmd+Shift+R)을 해봤나요
무료 깃허브 블로그 vs 워드프레스, 목적에 따라 골라요
두 플랫폼을 같은 기준에 놓고 보면 장단점이 거의 정반대예요. 무엇이 더 좋은지보다 내 목적에 무엇이 맞는지가 기준이에요.
| 기준 | 깃허브 블로그 | 워드프레스 |
|---|---|---|
| 비용 | 호스팅 0원, 도메인은 선택 | 호스팅 월 요금 + 도메인 연 요금 |
| 글 발행 | 마크다운 작성 후 커밋·푸시 | 관리자 화면 편집기에서 바로 발행 |
| 디자인 수정 | 설정 파일·CSS 수정, AI 코딩 도구와 궁합이 좋음 | 테마·플러그인을 클릭으로 설정 |
| 관리 부담 | 서버·보안 업데이트 걱정이 거의 없음 | 코어·플러그인 업데이트와 백업 필요 |
| SEO 도구 | jekyll-seo-tag·jekyll-sitemap 플러그인 | Rank Math 같은 SEO 플러그인 |
| 애드센스 | 개인 도메인 연결과 이용 정책 확인 필요 | 내 도메인이라 신청 흐름이 단순 |
| 어울리는 목적 | 공부 기록, 개발 로그, 포트폴리오 | 수익형 블로그, 브랜드·창업 사이트 |
가장 큰 차이는 수익화예요. 애드센스는 사이트 소유를 확인하는 절차가 있는데, github.io는 깃허브의 도메인이라 내 소유로 증명하기 어려워요. 그래서 깃허브 블로그로 애드센스를 준비한다면 개인 도메인 연결이 사실상 출발점이에요. 또 깃허브 이용 정책은 Pages를 상거래나 상업 서비스 운영에 쓰지 말라고 안내하니, 광고를 붙이기 전에 최신 정책을 확인해두세요.
발행 마찰도 따져봐야 해요. 워드프레스는 휴대폰으로도 바로 글을 올릴 수 있지만, 깃허브 블로그는 파일을 만들고 푸시해야 해요. 일주일에 3~4편 이상 꾸준히 쓸 계획이라면 이 작은 차이가 쌓여요.
반대로 깃허브 블로그만의 장점도 분명해요. 사이트 전체가 파일이라 “헤더 색을 바꿔줘”, “글 목록에 읽는 시간을 표시해줘”처럼 Claude Code에게 부탁하기 좋아요. 바이브코딩을 배우는 과정 자체가 콘텐츠가 돼요. 모든 수정이 커밋으로 남아서 망가져도 이전 상태로 되돌리기 쉬워요.
고민된다면 세 가지만 물어보세요. 수익화가 1순위인지, 글을 자주 빠르게 올려야 하는지, 코드를 만지며 배우는 게 목적인지예요. 앞의 두 질문에 “예”라면 워드프레스, 마지막 질문에 “예”라면 깃허브 블로그가 맞아요. 포트폴리오는 깃허브에, 수익형 글은 워드프레스에 두는 식으로 나눠 운영하는 방법도 있어요.
이럴 땐 어떻게?
푸시했는데 10분이 지나도 블로그가 예전 그대로예요
Actions 탭부터 확인하세요. 빨간 X라면 빌드 실패라 오류 줄을 보고 고치면 되고, 초록 체크인데 그대로라면 브라우저 캐시일 가능성이 커요. 시크릿 창으로 열어보고, 그래도 안 되면 체크리스트의 날짜와 파일명을 점검하세요.
사이트는 열리는데 디자인이 다 깨지고 글자만 보여요
대부분 _config.yml의 url·baseurl이 어긋났거나 Pages의 Source가 테마와 맞지 않는 경우예요. 사용자명.github.io 저장소라면 baseurl을 비우고, Actions용 테마라면 Source를 GitHub Actions로 바꾼 뒤 다시 푸시해 보세요.
저장소 이름을 잘못 지어서 주소 뒤에 /저장소이름이 붙어요
새로 만들 필요 없이 저장소 Settings에서 이름을 사용자명.github.io로 바꾸면 돼요. 사용자명 철자가 정확히 같아야 하고, 바꾼 뒤에는 _config.yml의 url과 baseurl도 새 주소에 맞춰주세요.
구글에서 내 블로그 이름을 검색해도 안 나와요
새 사이트는 구글이 존재 자체를 모르니 직접 알려줘야 해요. Google Search Console에 사이트를 등록해 소유 확인을 하고, jekyll-sitemap이 만든 sitemap.xml 주소를 제출하세요. 색인까지는 며칠에서 몇 주가 걸리는 게 일반적이에요.
나중에 개인 도메인을 연결하고 싶어요
가능해요. Settings → Pages의 Custom domain에 도메인을 입력하고, 도메인 구입처 DNS에 깃허브가 안내하는 레코드를 추가하면 돼요. 연결 후 Enforce HTTPS를 켜고 _config.yml의 url도 새 도메인으로 바꿔주세요. DNS 반영에는 시간이 걸릴 수 있어요.
참고자료
- GitHub Pages 공식 문서 — 저장소 이름 규칙, 배포 Source 설정, 용량·대역폭 한도, 커스텀 도메인 연결 방법
- Jekyll 공식 문서 — _posts 파일명 규칙, Front Matter, Windows·macOS별 설치 방법
- Claude Code 공식 문서 — 설치 방법과 기본 사용법, 명령어 실행 권한 설정
- Google Search Console — 사이트 소유 확인과 사이트맵 제출
깃허브 블로그 만들기에서 비전공자가 막히는 곳은 코드 자체가 아니라 흐름이에요. 저장소 이름이 곧 주소가 되고, 커밋은 상자 봉인이고 푸시는 발송이라는 것만 잡히면 나머지는 Claude Code에게 한 단계씩 부탁하며 따라갈 수 있어요. 첫 글이 안 보여도 당황할 필요 없어요. Actions 탭, 파일명, 날짜 순서로 점검하면 대부분 원인이 드러나요. 정리하면, 배우는 과정을 기록하고 포트폴리오를 쌓고 싶다면 깃허브 블로그로, 애드센스와 수익형 운영이 먼저라면 워드프레스로 시작하는 순서를 권해요. 오늘은 사용자명.github.io 저장소 하나를 만드는 것부터 시작해 보세요.
함께 보면 좋은 글
