라이트 모드와 다크 모드를 모두 지원하며, 기본값은 시스템 모드를 따릅니다. 아래 화면은 다크 모드 기준으로 캡처한 실제 데모입니다.

화면 미리보기

홈

홈에서는 프로필, 기여 그래프, 태그 목록, 글 목록을 한 화면 흐름 안에서 바로 볼 수 있습니다. “최근 글을 먼저 보여주면서도 탐색 도구를 잃지 않는 구조”가 이 테마의 핵심입니다.

시리즈

시리즈 탭은 글 목록과 다른 밀도를 갖도록 카드형 레이아웃을 사용합니다. 사용자는 시리즈를 “연재 묶음”처럼 인식하고, 개별 글과는 다른 방식으로 탐색할 수 있습니다.

글 상세

글 상세에서는 시리즈명, 제목, 설명, 작성자 메타, 태그, 썸네일, 본문, 이전/다음 포스트까지 한 흐름으로 이어집니다. 문서형 블로그에서 필요한 정보가 처음 접속한 사용자에게도 무리 없이 보이도록 정리한 구조입니다.

이 테마가 해결하려는 문제

정적 블로그 테마는 보통 두 방향으로 갈립니다.

• 화면은 예쁘지만 설정 지점이 흩어져 있어서 초기에 손대기 어렵거나
• 기능은 충분하지만 글 읽는 흐름이 무겁고 오래된 느낌이 나는 경우

이 테마는 그 중간을 노렸습니다. 글은 가볍게 읽히고, 운영자는 _config.yml, _data/profile.yml, _data/theme.yml, _data/series.yml만 바꿔도 빠르게 자기 블로그로 전환할 수 있게 구성했습니다.

기본으로 제공하는 화면

이 저장소를 실행하면 아래 흐름이 바로 보입니다.

1. 프로필과 GitHub 기여 그래프가 있는 상단 소개 영역
2. 글 / 시리즈 탭
3. 글 탭에서는 태그 필터와 검색
4. 시리즈 탭에서는 카드형 시리즈 목록
5. 글 상세에서는 태그, 본문, 이전/다음 글 네비게이션

즉, 블로그를 시작하는 순간부터 “소개 페이지”, “카드 샘플”, “설정 샘플”이 아니라 실제 운영 화면에 가까운 구조를 확인할 수 있습니다.

이 테마가 특히 잘 맞는 경우

• GitHub Pages 위에 개발 블로그를 빠르게 올리고 싶은 경우
• velog처럼 가볍게 읽히는 목록 구조를 좋아하는 경우
• 글, 시리즈, 태그, 검색을 모두 갖춘 출발점을 원하는 경우
• README와 데모 글까지 함께 공개할 오픈소스 테마 저장소가 필요한 경우

디렉터리 구조를 어떻게 읽으면 좋은가

가장 중요한 파일은 다음 다섯 묶음입니다.

_config.yml               # 사이트 메타, URL, 외부 연동
_data/profile.yml         # 기본 프로필 정보
_data/theme.yml           # UI 옵션과 문구
_data/series.yml          # 시리즈 표시 이름과 설명
_posts/*.md               # 실제 블로그 글

CSS와 레이아웃은 이미 기본 구조가 잡혀 있기 때문에, 처음부터 HTML을 뜯기보다 위 파일들을 먼저 바꾸는 편이 훨씬 빠릅니다.

오픈소스 테마로 배포하기 위해 정리한 기준

이 저장소는 공개용 테마라는 전제를 두고 샘플 자산도 함께 정리했습니다.

• 프로필 SVG와 문서용 프리뷰 이미지는 이 저장소에서 직접 만든 자산
• 포스트 커버는 라이선스가 명확한 무료 사진만 사용
• 빈 예시 폴더와 폐기된 데모 세트 제거
• 실제로 쓰이지 않는 분기나 스타일은 정리
• _posts에는 lorem ipsum 대신 사용 설명서 역할을 하는 데모 글 배치

이 기준 덕분에 저장소를 그대로 공개해도 “샘플이 너무 허전해서 다시 만들어야 하는 상태”를 피할 수 있습니다.

처음 가져간 뒤 추천하는 순서

새 블로그를 만들 때는 아래 순서가 가장 빠릅니다.

1. _config.yml에서 title, description, url, baseurl 수정
2. _data/profile.yml에서 기본 이름과 소개 문구 수정
3. _data/theme.yml에서 탭, 헤더, 검색 문구, GitHub 연동 옵션 조정
4. _posts의 샘플 글을 유지하거나 교체
5. 필요하면 scripts/fetch_github_contributions.rb로 GitHub 프로필 연결

다음 글부터는 이 과정을 각각 자세히 설명합니다. 설치, 설정, 글 작성, GitHub 동기화, 배포까지 순서대로 읽으면 한 번에 전체 구조를 파악할 수 있습니다.

준비물

로컬 미리보기를 위해 필요한 것은 아래 정도입니다.

• Ruby와 Bundler
• Git
• 선택 사항: gh auth login 또는 GitHub 토큰

GitHub 연동이 없더라도 화면은 정상으로 열립니다. 다만 이 경우 프로필과 잔디 그래프는 샘플 상태를 유지합니다.

가장 짧은 실행 순서

BUNDLE_FORCE_RUBY_PLATFORM=true bundle install
ruby scripts/fetch_github_contributions.rb
BUNDLE_FORCE_RUBY_PLATFORM=true bundle exec jekyll serve

두 번째 줄은 선택입니다. GitHub 프로필과 기여 그래프를 연결하지 않을 거라면 생략해도 됩니다.

미리보기 주소

현재 저장소 이름 기준 기본 주소는 다음입니다.

http://127.0.0.1:4000/

커스텀 도메인을 쓰고 baseurl을 비워 둔 상태라면 로컬 미리보기 주소도 루트(/)로 열립니다. 프로젝트 페이지를 쓸 때만 저장소 이름에 맞는 baseurl이 필요합니다.

GitHub 동기화 없이 실행하는 경우

토큰이 아직 없거나 GitHub 연동을 나중에 붙일 생각이라면 이렇게 실행해도 됩니다.

BUNDLE_FORCE_RUBY_PLATFORM=true bundle install
BUNDLE_FORCE_RUBY_PLATFORM=true bundle exec jekyll serve

이 경우 화면은 아래처럼 동작합니다.

• 프로필 이름과 소개는 _data/profile.yml의 샘플 값 사용
• 브라우저 탭 아이콘과 헤더 이미지는 기본 프로필 이미지 사용
• 잔디 그래프는 캐시가 없으면 비어 있거나 마지막 캐시 상태를 사용

처음 실행할 때 자주 걸리는 문제

gem 설치가 실패하는 경우

Apple Silicon이나 특정 네이티브 gem 환경에서는 Ruby 플랫폼 관련 오류가 날 수 있습니다. 그래서 이 저장소는 예시 명령에 BUNDLE_FORCE_RUBY_PLATFORM=true를 기본으로 넣어 두었습니다.

잔디 그래프가 비어 보이는 경우

아래 중 하나만 준비되어 있으면 됩니다.

• GITHUB_GRAPHQL_TOKEN
• GITHUB_TOKEN
• gh auth login

셋 다 없으면 스크립트는 공개 GitHub 데이터를 가져오지 못합니다.

주소는 열리는데 스타일이 이상한 경우

가장 먼저 _config.yml의 baseurl과 실제 저장소 이름이 같은지 확인하세요. 프로젝트 페이지는 저장소 이름이 곧 URL 경로가 되기 때문에, 이 값이 어긋나면 CSS와 JS 경로가 같이 틀어집니다.

추천 로컬 워크플로

처음 테마를 가져간 뒤에는 아래 흐름이 편합니다.

1. bundle install
2. _config.yml에서 title, url, baseurl 수정
3. _data/profile.yml 수정
4. jekyll serve로 화면 확인
5. 그 다음에 GitHub 동기화와 배포 설정 진행

이 순서대로 가면 “배포까지는 됐는데 주소가 꼬여 있는 상태”를 훨씬 덜 만나게 됩니다.

어떤 파일을 어디에 쓰는가

_config.yml

사이트 자체의 주소와 메타데이터를 담당합니다.

• 블로그 제목
• 설명
• url
• baseurl
• Google Analytics, Algolia, Giscus 같은 외부 연동

이 파일은 “사이트 레벨 설정”이라고 생각하면 됩니다.

_data/theme.yml

화면에 보이는 UI 옵션과 문구를 담당합니다.

• 헤더 GitHub / RSS / 다크모드 토글 노출
• 글 / 시리즈 / 소개 탭 노출 여부
• 홈 검색 placeholder
• 홈의 기본 로딩 개수
• GitHub 프로필 동기화 사용 여부

이 파일은 “테마 레벨 설정”입니다.

_data/profile.yml

GitHub 연동이 없을 때 보여줄 기본 프로필을 정의합니다.

• 표시 이름
• 소개 문구
• 기본 아바타
• 기본 GitHub 링크

즉, 동기화 실패 상황까지 포함해 화면이 비어 보이지 않도록 받쳐 주는 파일입니다.

_data/series.yml

시리즈 키와 표시용 제목, 설명을 분리합니다.

theme-overview:
  title: 테마 소개와 구조
  description: 홈 구성, 글 목록, 시리즈 카드처럼 테마의 핵심 화면 구성을 빠르게 훑습니다.

글 front matter에는 짧은 키만 넣고, 실제 카드에 보일 문구는 이 파일에서 관리하는 방식이 더 유지보수에 좋습니다.

가장 많이 바꾸는 옵션 예시

소개 탭을 숨기고, 헤더에서 RSS는 숨기고, GitHub 프로필 동기화만 유지하고 싶다면 아래처럼 바꿀 수 있습니다.

header:
  show_github_link: true
  show_rss_link: false
  show_theme_toggle: true

tabs:
  show_about: false

profile:
  github_sync:
    enabled: true

브랜드만 빠르게 바꾸는 체크리스트

새 프로젝트에 이 테마를 가져갔다면 아래 순서가 가장 효율적입니다.

1. _config.yml의 title, description, url, baseurl 수정
2. _data/profile.yml의 기본 이름과 소개 수정
3. _data/theme.yml의 헤더 버튼과 탭 옵션 조정
4. _data/series.yml에 실제 시리즈 제목 입력
5. _posts의 샘플 글을 유지하거나 교체

언제 HTML/CSS를 열어야 하나

대부분의 커스터마이징은 데이터 파일에서 끝나지만, 아래 경우에는 템플릿이나 CSS를 열어야 합니다.

• 카드 간격이나 폰트 크기를 바꾸고 싶을 때
• 태그/시리즈 레이아웃 구조를 바꾸고 싶을 때
• 헤더 아이콘 모양 자체를 교체하고 싶을 때

즉, 텍스트와 옵션은 데이터 파일, 구조와 스타일은 레이아웃/CSS라는 기준으로 보면 복잡도가 많이 내려갑니다.

기본 front matter

가장 많이 쓰는 형태는 아래 정도입니다.

---
title: 글 제목
description: 목록에 보일 요약
date: 2026-04-03 09:00:00 +0900
updated_at: 2026-04-03 21:00:00 +0900
thumbnail: /assets/images/posts/my-post-cover.png
series: theme-overview
tags:
  - Jekyll
  - Theme
---

각 필드가 화면에서 쓰이는 곳

시리즈를 붙이는 방식

포스트는 series: theme-overview처럼 키만 넣고, 실제 표시용 제목과 설명은 _data/series.yml에 둡니다.

이렇게 분리하면 같은 시리즈 이름을 여러 글에서 반복 입력할 필요가 없고, 시리즈 카드 문구를 한 곳에서 수정할 수 있습니다.

태그는 어떻게 보이는가

태그는 두 군데에서 동시에 쓰입니다.

• 홈 왼쪽 태그 패널
• 글 카드와 글 상세의 태그 링크

그래서 태그는 단순 메모 용도가 아니라 실제 탐색 체계라고 생각하고 붙이는 편이 좋습니다. 너무 세분화하면 목록이 지저분해지고, 너무 넓으면 필터 가치가 떨어집니다.

썸네일 규칙

이 테마는 thumbnail이 있을 때만 이미지를 그립니다.

• 카드: thumbnail이 있을 때만 표시
• 상세: thumbnail이 있을 때만 상단 이미지 표시
• 시리즈 카드: 대표 글의 thumbnail이 있을 때만 표시

즉, 이미지가 없는 글은 텍스트 중심 카드로 자연스럽게 남고, 이미지가 있는 글만 시각적으로 강조됩니다.

커버 이미지 준비 팁

오픈소스 데모 저장소라면 썸네일도 대충 넣기보다 기준을 정해 두는 편이 좋습니다.

• 너무 작은 이미지는 피하기
• 카드와 상세 모두에서 자연스럽게 보이도록 가로형 비율 사용
• 저작권 출처를 NOTICE.md에 남기기
• 데모용이라면 분위기가 비슷한 이미지를 한 세트로 맞추기

이 저장소는 실제 공개용 데모로 보이도록 코드 화면, 작업 환경, 노트북 사용 장면처럼 개발 블로그와 자연스럽게 어울리는 커버 이미지를 사용합니다.

Markdown 지원 범위

현재 데모 글 기준으로 확인해 둔 요소는 다음과 같습니다.

• 제목과 일반 문단
• 리스트와 체크리스트
• 표
• 코드 블록
• 이미지
• 링크
• 인용문
• raw HTML
• YouTube iframe

문서형 블로그에 필요한 기본 범위는 충분히 커버한다고 보면 됩니다.

글 발행 전 체크리스트

실제 운영에서는 아래 정도만 확인하면 안정적입니다.

1. description이 카드 요약으로 자연스러운지
2. tags가 너무 많지 않은지
3. series 키가 _data/series.yml에 존재하는지
4. thumbnail 경로가 실제 자산과 일치하는지
5. updated_at를 수정했는지

이 기준만 지켜도 홈 목록, 시리즈, 상세 화면이 한 번에 자연스럽게 맞춰집니다.

기본 배포 흐름

파이프라인이 하는 일은 아래 네 단계입니다.

1. gem 설치
2. GitHub 프로필과 기여 그래프 캐시 동기화
3. jekyll build
4. _site/ 내용을 gh-pages 브랜치로 푸시

Jenkins를 쓰지 않더라도, 핵심은 “정적 결과물을 어디에 배포할지”입니다. CI가 GitHub Actions든 Jenkins든 결과만 gh-pages에 올리면 구조는 같습니다.

GitHub Pages 설정

프로젝트 페이지를 쓰는 경우 GitHub 저장소 설정에서 아래 두 가지를 맞춰야 합니다.

• Pages source: gh-pages 브랜치
• Folder: / (root)

이 설정이 빠지면 브랜치는 갱신돼도 실제 사이트는 열리지 않습니다.

저장소 이름과 baseurl

가장 자주 틀리는 부분은 baseurl입니다. 프로젝트 페이지는 저장소 이름이 URL 경로가 되므로, 저장소를 jekyll-theme-velog로 바꿨다면 _config.yml도 이렇게 맞아야 합니다.

url: "https://blog.woonyong.org"
baseurl: ""

커스텀 도메인을 쓴다면 baseurl은 보통 비워 두는 편이 맞습니다. 반대로 github.io/저장소명 프로젝트 페이지를 그대로 쓸 때는 저장소 이름을 baseurl로 넣어야 합니다.

Jenkins에서 필요한 것

이 저장소의 Jenkinsfile을 그대로 쓰려면 아래 자격 증명이 필요합니다.

• github-pages
  • username: GitHub 사용자명
  • password: GitHub Personal Access Token

그리고 Jenkins 에이전트에는 Ruby와 Bundler가 있어야 합니다.

수동 배포로 검증하는 방법

자동화 전에 먼저 로컬 빌드만 검증하고 싶다면 아래 명령으로 충분합니다.

BUNDLE_FORCE_RUBY_PLATFORM=true bundle exec jekyll build

그 다음 _site 내용이 올바른지 확인한 뒤, 원하는 배포 도구로 gh-pages에 올리면 됩니다.

배포 후 확인 체크리스트

배포가 끝났다면 아래 네 가지를 바로 보는 편이 좋습니다.

1. Pages 주소가 200 응답인지
2. index.html이 올바른 baseurl을 쓰는지
3. feed.xml과 썸네일 이미지가 정상 응답인지
4. 홈과 시리즈 페이지가 같은 경로 체계를 쓰는지

정적 블로그는 에러 로그보다 “잘못된 링크 경로”가 더 흔한 장애 원인이기 때문에, 이 체크리스트만으로도 대부분의 배포 문제를 초기에 잡을 수 있습니다.

어떤 데이터를 가져오나

동기화 스크립트는 두 종류의 캐시를 만듭니다.

• _data/github_profile_cache.json
  • 이름, 아바타, 프로필 링크, 소개 텍스트
• _data/github_contributions_cache.json
  • 최근 1년 기여 캘린더

빌드 시점에는 이 캐시 파일만 읽기 때문에, 브라우저에서 토큰이 노출되지 않습니다.

필요한 설정

_data/theme.yml에서 아래 두 옵션을 켜면 됩니다.

hero:
  github_contributions:
    enabled: true
    username: your-github-id

profile:
  github_sync:
    enabled: true

username이 비어 있으면 _data/profile.yml의 GitHub 링크에서 계정 이름을 유추합니다.

실행 명령

ruby scripts/fetch_github_contributions.rb

인증은 아래 셋 중 하나면 됩니다.

• GITHUB_GRAPHQL_TOKEN
• GITHUB_TOKEN
• gh auth login

fallback 규칙

이 테마가 오픈소스 템플릿으로 쓸 만한 이유 중 하나가 바로 이 부분입니다. GitHub 연결이 완벽하지 않아도 화면이 망가지지 않습니다.

• GitHub 아바타가 있으면 아바타를 사용
• GitHub 이름이 있으면 표시 이름을 덮어씀
• GitHub bio가 비어 있으면 _data/profile.yml의 소개 문구 유지
• 잔디 캐시가 없으면 마지막 캐시 또는 기본 화면 사용

즉, 사용자 입장에서는 “연결되면 자동으로 좋아지고, 연결이 안 돼도 깨지지 않는” 구조입니다.

Jenkins와 함께 쓸 때

Jenkins 파이프라인에서는 빌드 전에 이 스크립트를 실행하도록 구성해 두었습니다. 그래서 하루 한 번 빌드를 돌리면 GitHub 프로필과 기여 그래프도 함께 최신 상태로 갱신할 수 있습니다.

동기화가 안 될 때 확인할 것

1. GitHub username이 실제 계정과 같은지
2. 토큰 또는 gh auth login이 준비돼 있는지
3. 캐시 파일이 생성됐는지
4. _data/profile.yml fallback 문구만 보이고 있지는 않은지

이 흐름만 이해하면 프로필 동기화는 별도 백엔드 없이도 충분히 안정적으로 운영할 수 있습니다.