Astro 블로그 구축기 #3 - 이미 만든 블로그에 테마 입히기

지난 글에서 Astro를 설치하고 블로그 템플릿으로 기본 블로그를 띄워봤다. 블로그를 직접 구축하는 가장 큰 장점이 뭘까. 바로 디자인을 내 멋대로 꾸밀 수 있다는 것이지. 그래서 지금 이 글을 게시하고 있는 이 블로그를 예전 하이텔 느낌으로 디자인 할 수 있었다. 그래, 모름지기 블로그는 내 맘대로 꾸밀 수 있어야지. 물론, 글쓰는 것보다 꾸미는데 집중하면 안되겠지만.

나처럼 처음부터 끝까지 코딩해서 디자인 작업을 진행할 수도 있지만 너무 어렵고 힘들고 디자인에 재주도 없고(그렇다고 지금 블로그가 디자인적으로 썩 좋아보이는 건 아니지만.) 누가 대신 디자인 해줬으면 좋겠고 하는 마음이 있다면 누군가 만든 테마를 가져다가 내 블로그를 꾸미는 것도 방법이다.

Astro는 내 맘대로 꾸밀 수 있다는 장점이 있지만 워드프레스처럼 “테마 설치” 버튼을 누르면 짠 하고 바뀌는 그런 걸 기대했다면 미리 마음을 내려놓자. Astro 테마는 대부분 플러그인이 아니라 완성된 프로젝트 템플릿이다. 그러니까 테마를 “설치”한다기보다는 테마와 내 블로그 중 한쪽을 다른 쪽으로 “옮기는” 작업이라고 생각하는 게 맞다.

테마는 어디서 찾나

Astro 공식 사이트의 테마 페이지에 가면 블로그, 포트폴리오, 문서 사이트 등 카테고리별로 테마가 모여 있다.

Astro 공식사이트 테마 페이지

무료와 유료가 섞여 있으니 필터로 골라보면 된다. 마음에 드는 테마를 찾았다면 보통 GitHub 저장소 링크가 붙어 있으니 그쪽으로 들어가서 README를 먼저 읽어보자.

테마를 고를 때 디자인 말고도 꼭 확인할 것들이 있다.

Astro 버전: 테마의 package.json에서 astro 버전을 확인한다. 내 블로그와 메이저 버전이 다르면 손이 많이 간다.
스타일링 방식: Tailwind를 쓰는지, 그냥 CSS를 쓰는지. Tailwind 테마라면 관련 설정까지 같이 가져와야 한다.
라이선스: MIT 같은 오픈소스 라이선스인지, 출처 표기가 필요한지 확인한다.
최근 커밋: 오랫동안 관리가 안 된 테마는 최신 Astro에서 빌드가 안 될 수도 있다.

방법 1. 테마 프로젝트로 내 글을 옮기기

개인적으로 가장 추천하는 방법이다. 블로그를 막 만든 상태라 내가 직접 고친 부분이 많지 않다면 이게 제일 빠르고 깔끔하다.

지난 글에서 npm create astro@latest로 프로젝트를 만들었는데, 여기에 --template 옵션을 붙이면 GitHub 저장소를 템플릿으로 바로 프로젝트를 만들 수 있다.

# GitHub 저장소를 템플릿으로 새 프로젝트 생성
npm create astro@latest -- --template <github-사용자명>/<테마-저장소명>

중간의 --는 오타가 아니다. npm에게 “여기서부터는 Astro 생성 도구에 넘길 옵션”이라고 알려주는 구분자다.

프로젝트가 만들어지면 이제 내 블로그의 내용을 하나씩 옮긴다.

Step1. 글 파일 복사

기존 블로그의 src/content/blog 아래 마크다운 파일들을 테마의 콘텐츠 폴더로 복사한다. 테마마다 폴더 이름이 blog일 수도, posts일 수도 있으니 테마의 구조를 먼저 확인하자. 글에서 쓰는 이미지가 src/assets 같은 곳에 있다면 그것도 같은 상대 경로로 옮겨야 이미지가 깨지지 않는다.

Step2. frontmatter 맞추기

여기가 제일 귀찮은 부분이다. Astro는 src/content.config.ts에서 글의 frontmatter 형식(스키마)을 검사하는데, 테마마다 필드 이름이 다르다. 예를 들어 내 블로그는 이렇게 생겼다.

schema: ({ image }) =>
	z.object({
		title: z.string(),
		description: z.string(),
		pubDate: z.coerce.date(),
		updatedDate: z.coerce.date().optional(),
		heroImage: z.optional(image()),
		tags: z.array(z.string()).default([]),
		draft: z.boolean().default(false),
	}),

그런데 테마는 pubDate 대신 date를, heroImage 대신 cover를 쓸 수도 있다. 이럴 때 선택지는 두 가지다.

내 글들의 frontmatter를 테마 형식에 맞게 일괄 수정한다.
테마의 스키마와 컴포넌트를 내 필드 이름에 맞게 고친다.

글이 몇 개 없다면 1번, 글이 많다면 2번이 편하다. 어느 쪽이든 npm run dev를 돌려보면 형식이 안 맞는 글은 에러 메시지로 친절하게 알려주니 그걸 보면서 하나씩 고치면 된다.

Step3. 설정과 integration 옮기기

astro.config.mjs에서 아래 항목들을 확인해서 테마 쪽으로 옮긴다.

site: 내 블로그 주소. RSS나 sitemap이 이 값을 쓴다.
integrations: 내가 쓰던 mdx, sitemap 같은 integration
기타 내가 추가했던 설정들

package.json도 비교해서 내가 추가로 설치했던 패키지가 있다면 테마 쪽에도 npm install로 설치해준다. 나 같은 경우는 댓글(Artalk)이나 이미지 확대(medium-zoom) 같은 걸 붙여놨으니 이것들도 같이 옮겨야 한다.

방법 2. 내 블로그에 테마의 디자인만 가져오기

이미 이것저것 기능을 많이 붙여놔서 프로젝트를 갈아엎기 싫다면, 반대로 테마에서 디자인 관련 파일만 쏙 빼오는 방법이 있다.

Astro 프로젝트에서 화면 모양을 담당하는 곳은 대체로 정해져 있다.

폴더	역할
`src/layouts`	페이지의 전체 뼈대 (헤더, 푸터, 본문 영역)
`src/components`	헤더, 카드, 태그 목록 같은 조각들
`src/styles`	전역 CSS
`public`	폰트, 파비콘, 아이콘 같은 정적 파일

이 폴더들을 테마에서 가져온 뒤, 내 페이지 파일(src/pages 아래)이 새 레이아웃을 쓰도록 import 경로를 바꿔주면 된다.

다만 이 방법은 생각보다 손이 많이 간다. 테마의 컴포넌트가 테마의 frontmatter 필드 이름을 기준으로 짜여 있기 때문에 결국 방법 1의 Step2와 같은 작업을 컴포넌트 안에서 하게 된다. 그리고 테마가 Tailwind를 쓴다면 Tailwind 설치와 설정까지 따라와야 한다.

방법 3. Git으로 테마를 합치기

테마 제작자가 업데이트할 때마다 그 변경사항을 계속 받아오고 싶다면 Git의 원격 저장소(remote)로 테마를 등록해서 합치는 방법도 있다.

# 작업용 브랜치를 먼저 만든다
git checkout -b theme-apply

# 테마 저장소를 원격으로 등록하고 가져온다
git remote add theme https://github.com/<github-사용자명>/<테마-저장소명>.git
git fetch theme

# 서로 관련 없는 히스토리를 합친다
git merge theme/main --allow-unrelated-histories

--allow-unrelated-histories는 내 블로그와 테마가 서로 다른 프로젝트로 시작했기 때문에 필요한 옵션이다. 경고하자면 첫 병합 때 충돌이 엄청나게 난다. 거의 모든 파일이 충돌한다고 보면 된다. 그래서 반드시 별도 브랜치에서 진행하고, 충돌을 다 정리한 다음에 메인 브랜치로 합치자. 한 번 고생해두면 이후 테마 업데이트는 git fetch theme과 git merge theme/main으로 받아올 수 있다.

어떤 방법을 고를까

정리하면 이렇다.

블로그를 막 만들었고 커스터마이징이 거의 없다 → 방법 1
직접 붙인 기능이 많아서 프로젝트를 유지하고 싶다 → 방법 2
테마 업데이트를 계속 따라가고 싶다 → 방법 3

어느 방법이든 작업 전에 Git 브랜치를 하나 따두는 걸 잊지 말자. 테마 작업은 생각보다 많은 파일을 건드리기 때문에 언제든 원래대로 돌아갈 수 있어야 마음이 편하다.

놓치기 쉬운 것들

마지막으로 테마를 바꾸고 나서 내가 확인한 체크리스트다.

글 주소가 그대로인지: 나는 글 파일명을 yyyyMMdd_###.md 형식으로 쓰는데, 이 파일명이 그대로 글 주소가 된다. 테마가 /blog/ 대신 /posts/ 같은 다른 경로를 쓰면 기존 링크가 다 깨진다. 경로를 맞추거나 astro.config.mjs의 redirects로 예전 주소를 새 주소로 넘겨주자.
RSS와 sitemap: 바뀐 주소로 제대로 생성되는지 빌드 결과(dist 폴더)에서 확인한다.
이미지: heroImage처럼 frontmatter에서 쓰는 이미지가 잘 나오는지, 본문 이미지 경로가 깨지지 않았는지 본다.
빌드 테스트: npm run dev에서 잘 되더라도 배포 전에 꼭 npm run build를 한 번 돌려보자. 개발 서버에서는 안 보이던 에러가 빌드에서 나오는 경우가 종종 있다.

다음 시간엔 실제로 테마 하나를 골라서 내 블로그에 적용해보는 과정을 따라가 보겠다. 안녕!