Jekyll 블로그를 Astro로 전면 개편한 기록

오랫동안 사용하던 GitHub 블로그를 전면 개편했다.

기존 블로그는 Jekyll과 Chirpy 테마를 기반으로 만들어져 있었다. 이미 완성된 테마를 사용했기 때문에 빠르게 블로그를 시작할 수 있었지만, 시간이 지날수록 내가 원하는 방식과는 조금씩 맞지 않기 시작했다.

특히 가장 아쉬웠던 부분은 카테고리였다. 나는 글을 태그보다 카테고리 중심으로 정리하는 편이고, 하나의 카테고리 아래에 여러 단계의 하위 카테고리를 두고 싶었다. 하지만 기존 구조에서는 카테고리를 원하는 방식으로 확장하거나 탐색하기가 쉽지 않았다.

결국 기존 테마를 조금씩 수정하는 대신, 블로그의 구조 자체를 새로 설계하기로 했다.

왜 Jekyll 대신 Astro를 선택했나

처음에는 Jekyll 테마를 유지하면서 디자인만 바꾸는 방법도 생각했다.

Jekyll 자체가 사용할 수 없을 정도로 오래된 도구는 아니다. GitHub Pages와의 호환성이 좋고, 단순한 정적 블로그를 운영하기에는 여전히 충분하다. 다만 Ruby와 Gem 의존성을 관리해야 하고, 테마 구조에 따라 원하는 기능을 수정하기가 번거로울 수 있다.

이번 개편에서는 기존 테마를 고치는 것보다 다음 조건을 자유롭게 구현하는 것이 더 중요했다.

여러 단계로 확장할 수 있는 계층형 카테고리
화면 왼쪽에 고정된 카테고리 사이드바
항상 접근할 수 있는 검색 기능
카테고리보다 눈에 덜 띄지만 필요한 태그 기능
Markdown 기반의 글 작성 방식
GitHub Pages를 통한 정적 배포

이 조건을 기준으로 Jekyll 대신 Astro를 선택했다.

Astro는 정적 사이트를 만들기 좋고, 필요한 부분만 직접 구성할 수 있다. 완성된 Astro 테마를 그대로 사용하지 않고, 블로그의 골격과 컴포넌트를 직접 만드는 방향으로 진행했다.

가장 중요했던 카테고리 구조

이번 개편의 핵심은 디자인보다 카테고리 체계였다.

현재 카테고리는 다음과 같이 구성했다.

AI
- Master’s Degree
  - Data Science
  - Competitions
  - Capstone Design
- Projects
  - DanceBridge
- Self-Study
  - Certifications
  - Courses & Books
  - etc
- Resources

카테고리는 categories.yml이라는 별도의 설정 파일에서 관리한다. 새로운 카테고리를 추가하거나 기존 카테고리를 이동할 때 페이지 코드를 직접 수정할 필요가 없다.

각 카테고리는 세 가지 주요 정보를 가진다.

id: 글에서 참조하는 고유 식별자
name: 화면에 표시되는 이름
slug: URL에 사용되는 값

예를 들어 카테고리의 화면 표시 이름이나 트리상의 위치를 변경해도 id만 유지하면 기존 글을 일일이 수정할 필요가 없다.

- id: projects
  name: Projects
  slug: projects
  children:
    - id: dancebridge
      name: DanceBridge
      slug: dancebridge

카테고리 깊이에는 별도의 제한을 두지 않았다. 앞으로 3단계나 4단계 이상의 하위 카테고리가 필요해져도 같은 구조로 확장할 수 있다.

상위 카테고리 페이지에서는 하위 카테고리에 포함된 글까지 함께 볼 수 있도록 구성했다. 예를 들어 Master's Degree 카테고리에 들어가면 Data Science, Competitions, Capstone Design에 속한 글을 모두 확인할 수 있다.

고정 사이드바와 검색

데스크톱 화면에서는 왼쪽에 카테고리 사이드바가 고정된다.

카테고리를 펼치거나 접을 수 있고, 각 카테고리 옆에는 포함된 글의 개수가 표시된다. 선택한 카테고리는 별도의 배경색과 강조색으로 구분된다.

모바일에서는 고정 사이드바 대신 메뉴 버튼을 눌러 여는 드로어 방식으로 변경된다. 데스크톱과 모바일이 동일한 카테고리 데이터를 사용하기 때문에 두 화면에서 카테고리 구조가 달라질 가능성도 줄였다.

검색은 정적 사이트 검색 도구인 Pagefind를 사용했다. 별도의 검색 서버 없이 빌드된 HTML을 인덱싱한다. 글 제목뿐 아니라 본문, 카테고리, 태그도 검색 대상에 포함된다.

태그 기능도 유지했다. 다만 태그는 블로그의 주 탐색 수단이 아니기 때문에 글 목록과 본문 하단에서 작은 크기로 표시되도록 했다.

글 작성 방식

블로그 글은 이전과 마찬가지로 Markdown으로 작성한다.

모든 글은 src/content/posts 폴더에 저장하며, 파일 상단에는 다음과 같은 정보를 입력한다.

---
title: "글 제목"
description: "글에 대한 간단한 설명"
publishedAt: 2026-08-22
category: projects
tags:
  - Astro
  - GitHub Pages
draft: false
---

각 글은 하나의 기본 카테고리에 속한다. 태그는 필요할 때 여러 개를 추가할 수 있다.

작성 중인 글은 draft: true로 설정하면 빌드 결과에서 제외된다. 카테고리 설정에 존재하지 않는 ID를 글에서 사용하면 검증 단계에서 오류가 발생하도록 구성했다.

기존 글 이전과 배포 방식

기존 Jekyll 블로그에 있던 글도 새로운 Markdown 콘텐츠 구조로 이전했다.

본문은 유지하면서 Jekyll 전용 frontmatter를 Astro 콘텐츠 스키마에 맞게 변경했다. 이전이 끝난 뒤에는 Ruby의 Gemfile, Jekyll 설정 파일, Chirpy 플러그인과 테마 전용 파일을 제거했다.

배포 방식도 Astro에 맞게 변경했다.

현재는 master 브랜치에 변경 사항을 올리면 GitHub Actions가 다음 작업을 수행한다.

Node.js와 pnpm 환경 구성
콘텐츠와 카테고리 설정 검증
Astro 정적 페이지 빌드
Pagefind 검색 인덱스 생성
결과물을 GitHub Pages에 배포

로컬에서는 다음 명령으로 블로그를 실행할 수 있다.

pnpm dev

프로덕션 빌드는 다음 명령으로 확인한다.

pnpm build
pnpm preview

디자인 정리

전체적인 디자인은 ‘차분한 연구 노트’를 기준으로 정했다.

배경은 완전한 흰색 대신 아이보리를 사용하고, 사이드바에는 조금 더 짙은 회베이지를 적용했다. 강조색은 채도가 낮은 브라운을 사용했다.

인터페이스 영역에는 Pretendard를 사용하고, 글 제목과 본문에는 MaruBuri를 적용했다. 카테고리와 검색 기능은 명확하게 보이도록 하면서도, 실제 글을 읽을 때는 시선이 본문에 머물도록 조정했다.

아직 세세하게 다듬을 부분은 남아 있지만, 처음 목표로 했던 구조는 완성됐다.

개편을 마치며

이번 개편은 단순히 블로그의 색상이나 테마를 바꾸는 작업이 아니었다.

어떤 내용을 기록할 것인지, 그리고 그 기록을 앞으로 어떻게 분류하고 찾아볼 것인지 다시 생각하는 과정에 가까웠다.

기존 테마에 내 기록 방식을 맞추는 대신, 내가 기록하는 방식에 맞춰 블로그 구조를 설계했다는 점이 가장 만족스럽다.

앞으로 카테고리 구조는 계속 달라질 수 있다. 새로운 프로젝트나 공부 주제가 생기면 카테고리가 추가될 것이고, 필요하지 않은 분류는 삭제하거나 이동할 수도 있다. 이번에 만든 구조라면 그런 변화에도 비교적 부담 없이 대응할 수 있을 것 같다.

이제 블로그의 틀은 어느 정도 완성됐다. 앞으로는 이 공간을 실제 기록으로 채우는 일이 남았다.