Gatsby로 GitHub 블로그 시작하기 — 설치부터 첫 배포까지

안녕하세요, 자바파커입니다.

개발자라면 한 번쯤 나만의 기술 블로그를 운영해보고 싶다는 생각을 해보셨을 겁니다. 네이버 블로그, 티스토리, 벨로그 등 다양한 플랫폼이 있지만, 저는 GitHub Pages + Gatsby 조합을 강력히 추천합니다.

이 포스팅에서는 Gatsby와 gatsby-starter-hoodie 테마를 활용해 GitHub 블로그를 처음부터 배포까지 완성하는 전 과정을 다룹니다.

왜 GitHub Pages 블로그인가?

GitHub Pages 블로그를 선택해야 하는 이유는 명확합니다.

비용 0원: 호스팅 비용이 전혀 들지 않습니다. GitHub에서 무료로 제공합니다.
개발자 친화적: Git으로 버전 관리를 하고, 마크다운으로 글을 씁니다. 개발자에게 이보다 자연스러운 워크플로우는 없습니다.
마크다운 기반: 코드 블록, 수식, 표 등을 편리하게 작성할 수 있습니다. 기술 블로그에 최적화된 형식입니다.
커스터마이징 자유: HTML, CSS, JavaScript를 완전히 제어할 수 있습니다. 원하는 기능을 직접 추가하고, 디자인을 자유롭게 변경할 수 있습니다.
커스텀 도메인 지원: 무료 HTTPS와 함께 나만의 도메인을 연결할 수 있습니다.
SEO 유리: 정적 사이트 생성(SSG) 방식이라 검색엔진 최적화에 유리합니다.

다른 플랫폼과 비교

블로그 플랫폼을 선택할 때 가장 많이 고민하는 옵션들을 비교해 보겠습니다.

항목	GitHub Pages	티스토리	벨로그	Medium
비용	무료	무료	무료	일부 유료
커스터마이징	완전 자유	스킨 수준	제한적	거의 불가
마크다운	네이티브 지원	부분 지원	네이티브 지원	부분 지원
코드 블록	커스텀 가능	기본	기본	기본
SEO 제어	완전 제어	제한적	제한적	불가
광고 수익	직접 설정	카카오 애드핏	불가	Partner Program
초기 설정 난이도	높음	낮음	매우 낮음	매우 낮음

초기 설정이 다소 복잡하다는 단점이 있지만, 이 시리즈를 따라오시면 어렵지 않게 완성할 수 있습니다.

사전 준비

Gatsby 블로그를 시작하기 전에 다음 도구들이 필요합니다.

Node.js 설치

Gatsby는 Node.js 기반 프레임워크입니다. Node.js 공식 사이트에서 LTS 버전을 설치합니다.

# 설치 확인
node --version
# v20.x.x 이상 권장

npm --version
# 10.x.x 이상

팁: nvm(Node Version Manager)을 사용하면 Node.js 버전을 쉽게 관리할 수 있습니다.

Git 설치

Git 공식 사이트에서 설치하거나, 아래 명령어로 확인합니다.

git --version
# git version 2.x.x

GitHub 계정 생성

GitHub에 계정이 없다면 가입합니다. GitHub Pages를 사용하려면 GitHub 계정이 필수입니다.

Gatsby 설치 및 프로젝트 생성

Gatsby CLI 설치

먼저 Gatsby CLI를 전역으로 설치합니다.

npm install -g gatsby-cli

gatsby-starter-hoodie로 프로젝트 생성

gatsby-starter-hoodie는 깔끔한 디자인과 다크모드, 시리즈 기능 등을 기본 제공하는 테마입니다. 이 블로그(AI JAVAPARK)에서도 사용하고 있습니다.

# 프로젝트 생성
npx gatsby new my-blog https://github.com/devHudi/gatsby-starter-hoodie

# 프로젝트 폴더로 이동
cd my-blog

프로젝트 생성이 완료되면 다음과 같은 폴더 구조가 생성됩니다.

my-blog/
├── contents/
│   └── posts/          # 블로그 글 저장 폴더
├── src/
│   ├── assets/         # 테마, 이미지 등 정적 자원
│   ├── components/     # React 컴포넌트
│   ├── pages/          # 페이지 컴포넌트
│   └── templates/      # 템플릿 컴포넌트
├── static/             # 정적 파일 (favicon 등)
├── blog-config.js      # 블로그 설정 파일
├── gatsby-config.js    # Gatsby 설정 파일
├── gatsby-node.js      # Gatsby Node API
└── package.json

blog-config.js 설정

프로젝트 루트에 있는 blog-config.js 파일을 열어 블로그 기본 정보를 설정합니다.

module.exports = {
  title: "AI JAVAPARK",
  description: "개발과 AI를 다루는 기술 블로그",
  author: "자바파커",
  siteUrl: "https://blog.javapark.kr",
  links: {
    github: "https://github.com/javapark",
    // 사용하지 않는 링크는 빈 문자열로 두면 됩니다
    linkedIn: "",
    facebook: "",
    instagram: "",
    email: "mailto:your-email@example.com",
  },
  utterances: {
    repo: "javapark/blog-comments",
    type: "pathname",
  },
}

각 항목을 설명하면 다음과 같습니다.

title: 블로그 제목입니다. 브라우저 탭과 헤더에 표시됩니다.
description: 블로그 설명입니다. SEO 메타 태그에 사용됩니다.
author: 작성자 이름입니다.
siteUrl: 배포될 블로그 URL입니다. GitHub Pages 기본 URL(https://username.github.io) 또는 커스텀 도메인을 입력합니다.
links: SNS 링크입니다. 프로필 영역에 아이콘으로 표시됩니다.
utterances: GitHub Issues 기반 댓글 시스템 설정입니다.

로컬 개발 서버 실행

설정을 마쳤다면 로컬에서 블로그를 확인해 봅시다.

# 개발 서버 실행
gatsby develop

브라우저에서 http://localhost:8000으로 접속하면 블로그를 확인할 수 있습니다.

# 만약 포트 충돌이 발생한다면 포트를 변경할 수 있습니다
gatsby develop -p 9000

개발 서버는 핫 리로딩을 지원하므로, 파일을 수정하면 브라우저가 자동으로 새로고침됩니다. 글을 쓰면서 실시간으로 결과를 확인할 수 있어 매우 편리합니다.

빌드 테스트

배포 전에 프로덕션 빌드가 정상적으로 되는지 확인하는 것이 좋습니다.

# 프로덕션 빌드
gatsby build

# 빌드 결과 로컬에서 확인
gatsby serve

gatsby serve를 실행하면 http://localhost:9000에서 빌드된 결과물을 확인할 수 있습니다.

GitHub Pages 배포

이제 가장 중요한 단계인 배포를 진행합니다.

GitHub 리포지토리 생성

GitHub에서 New repository를 클릭합니다.
Repository name을 username.github.io 형식으로 입력합니다. (예: javapark.github.io)
Public으로 설정합니다. (GitHub Pages 무료 플랜은 Public 리포지토리에서만 동작합니다.)
Create repository를 클릭합니다.

원격 리포지토리 연결

# 기존 원격 저장소 제거 (starter 원본이 연결되어 있을 수 있습니다)
git remote remove origin

# 새 리포지토리 연결
git remote add origin https://github.com/username/username.github.io.git

# 기본 브랜치를 main으로 설정
git branch -M main

# 첫 커밋 및 푸시
git add .
git commit -m "Initial commit"
git push -u origin main

gh-pages 패키지로 배포

gh-pages 패키지를 사용하면 빌드 결과물만 별도 브랜치에 배포할 수 있습니다.

# gh-pages 패키지 설치
npm install gh-pages --save-dev

package.json에 배포 스크립트를 추가합니다.

{
  "scripts": {
    "deploy": "gatsby build && gh-pages -d public -b gh-pages"
  }
}

배포를 실행합니다.

npm run deploy

GitHub Pages 설정

GitHub 리포지토리 > Settings > Pages로 이동합니다.
Source를 Deploy from a branch로 선택합니다.
Branch를 gh-pages로 선택하고 폴더는 / (root)로 설정합니다.
Save를 클릭합니다.

몇 분 뒤 https://username.github.io에 블로그가 배포됩니다.

배포 확인

# 배포 상태 확인 (GitHub CLI가 설치되어 있다면)
gh api repos/{owner}/{repo}/pages --jq '.status'

브라우저에서 https://username.github.io에 접속하여 블로그가 정상적으로 표시되는지 확인합니다.

첫 글 작성해보기

배포가 완료되었으니 첫 글을 작성해 봅시다.

# 글 폴더 생성
mkdir -p contents/posts/my-first-post

contents/posts/my-first-post/index.md 파일을 만들고 다음과 같이 작성합니다.

---
title: "나의 첫 블로그 포스팅"
description: "GitHub 블로그에 첫 글을 작성했습니다."
date: 2026-04-04
update: 2026-04-04
tags:
  - 블로그
  - 시작
---

## 안녕하세요!

이것은 나의 첫 블로그 포스팅입니다.

### 코드 블록도 됩니다

\```javascript
console.log("Hello, Blog!");
\```

글을 작성한 뒤 다시 배포합니다.

npm run deploy

자주 묻는 질문 (FAQ)

Q1. GitHub Pages는 정말 무료인가요?

네, 완전히 무료입니다. Public 리포지토리에서는 GitHub Pages를 무료로 사용할 수 있으며, 월 트래픽 제한은 약 100GB입니다. 일반적인 개인 블로그에서는 이 제한에 도달할 일이 거의 없습니다.

Q2. gatsby-starter-hoodie 대신 다른 테마를 써도 되나요?

물론입니다. Gatsby Starter Library에서 다양한 테마를 확인할 수 있습니다. 다만 이 시리즈에서는 gatsby-starter-hoodie를 기준으로 설명하므로, 다른 테마를 선택하면 설정 방법이 다를 수 있습니다.

Q3. 커스텀 도메인은 어떻게 연결하나요?

GitHub 리포지토리 Settings > Pages에서 Custom domain 항목에 원하는 도메인을 입력합니다. 그 전에 도메인 DNS 설정에서 CNAME 레코드를 username.github.io로 지정해야 합니다. 이 부분은 시리즈 후반부에서 자세히 다룰 예정입니다.

다음 포스팅에서는 Gatsby 블로그 스킨 커스터마이징 방법을 다룹니다. 콘텐츠 폭, 폰트, 색상, 다크모드까지 나만의 블로그 디자인을 만들어 보겠습니다.