글 목록으로 돌아가기

테마 소개와 구조

Velog Style Jekyll Theme 소개

velog의 읽기 흐름을 참고해 Jekyll과 GitHub Pages에 맞게 다시 구성한 오픈소스 개발 블로그 테마를 소개합니다.

choi woo-nyong 2026년 4월 2일 · 3분 읽기 · 수정 2026년 4월 3일

Jekyll Theme Velog Style GitHub Pages Open Source

이 테마는 읽기 편한 글 목록, 시리즈, 태그, 검색, GitHub 프로필 동기화, 기여 그래프를 한 번에 갖춘 Jekyll 기반 개발 블로그 출발점입니다. 단순히 보기 좋은 화면만 넣는 대신, 실제로 저장소를 복제한 뒤 어떻게 설정하고 운영하는지까지 문서형 데모로 함께 제공하는 것을 목표로 만들었습니다.

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

화면 미리보기

홈

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

시리즈

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

글 상세

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

이 테마가 해결하려는 문제

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

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

이 테마는 그 중간을 노렸습니다. 글은 가볍게 읽히고, 운영자는 _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 동기화, 배포까지 순서대로 읽으면 한 번에 전체 구조를 파악할 수 있습니다.

댓글