블로그 다시 만들기

낡아가는 블로그

약 2년 전, Gatsby  기반의 블로그를 Astro  기반으로 마이그레이션했다. 자주 포스팅하지는 않았지만, 최신 프론트엔드 기술의 흐름을 조금이라도 체험해보고 싶어 블로그를 갈아엎었다.

그때는 ‘테마가 조금 더 예뻤으면 좋겠다’는 생각이 들어, 괜찮아 보이는 오픈 소스 템플릿을  적용했다. 덕분에 손쉽게 블로그를 수정할 수 있었고, 이후 2년 동안 단 한 편의 포스트만 올렸다.

참고로 내가 링크한 astro-paper 템플릿은 지금도 새로이 블로그를 만들어보고 싶은 분들에게 강력히 추천한다. Astro를 통해 정적 빌드 방식의 웹사이트 빌드 방법을 파헤쳐볼 수도 있고, 테마 자체도 완성도가 높다.

개인 노트에 글쓰기는 꾸준히 해 왔지만, 블로그로 포스팅을 하지 않은 이유는 여러 가지가 있다. 글을 쓰는 건 내 자유지만, ‘올릴 거라면 누군가에게 도움이 되면 좋겠다’ 는 부담이 있었던 것 같다. 아니면 단순히 귀찮았던 걸 수도 있다.

최근 들어 가장 크게 느낀 귀찮음은 바로 ‘유지 비용’ 이었다.

마크다운으로 글을 쓰고 커밋 후 저장소로 푸시하면 자동으로 배포되는 편리한 워크플로우인데, 왜 유지 비용이 들까? 결국 블로그도 하나의 소프트웨어다. 의존성은 낡고, 배포 환경은 보안 취약점을 관리해야 한다는 부담이 생긴다. 오래된 저장소를 가지고 있다면 dependabot  이 알아서 보안 업데이트 PR을 올릴 때마다 신경이 쓰이기도 한다.

또 새로 만들자. 이번엔 혼자가 아니다.

블로그를 운영하지 않을 때는 유지 비용은 전혀 상관없다. 그냥 방치하면 그만이다.

하지만 글을 쓰려는 순간, 저장소의 의존성을 업데이트하려는 시점부터 문제가 시작된다. Astro는 방치한 사이 메이저 버전이 바뀌었고, 내가 사용하던 테마도 여러 부분이 수정되었다. 업그레이드 도구가 제공되지 않아 직접 마이그레이션하려면 큰 작업이 필요했다. 결국 쓰려던 글은 아이디어로만 남고, 퍼블리싱은 요원해졌다.

이럴 거면 새로 만드는 게 낫지 않을까? 요즘은 AI 에이전트가 있으니.

프로덕션 환경이라면 이런 생각은 위험하지만, 블로그는 개인 프로젝트다. 영향 범위가 거의 없으니 새로 만들기 쉬웠다. 다만 새로 만드는 비용이 기존 제품을 유지보수하는 비용보다 저렴해야 한다.

요즘은 Claude Code , Codex , Gemini CLI  등 AI 도구 덕분에 블로그를 쉽게 재구축할 수 있다고 판단했다. 그래서 그 경험을 공유해본다.

이번 블로그 제작 과정은 요구사항 정리 > 필요한 도구 조사 > 마이그레이션 적용 > 약간의 트러블슈팅 의 단계로 약 8시간이 소요됐다. 앞 두 단계가 전체 시간의 절반을 차지했다.

요구사항 정리하기

개발자 블로그라는 ‘제품’ 의 요구사항을 생각해보자.

• 포스트 목록을 볼 수 있다.
• 포스트 내용을 볼 수 있다.
• 글쓴이 소개를 볼 수 있다.
• SNS, GitHub 등 외부 링크를 제공한다.
• (Optional) 포스트의 태그를 모아볼 수 있다.
• (Optional) 포스트를 검색할 수 있다.
• (Optional) Table of Contents 를 볼 수 있다.
• (Optional) 포스트의 댓글을 볼 수 있다.
• (Optional) RSS Feed 를 제공할 수 있다.

그리고 숨은 핵심 요구사항이 하나 있다. 바로 ‘유지보수가 용이할 것’ 이다. 즉, 적은 코드로 비슷한 결과물을 낼 수 있고, 의존성 업데이트의 비용이 낮은 구조 가 이상적이다.

이 기준으로 블로그용 도구를 찾아보다가 Nextra 를 선택했다.

Nextra?

Simple, powerful and flexible site generation framework with everything you love from Next.js .

Nextra 는 Next.js 기반으로 콘텐츠 기반 웹사이트 제작 프레임워크다.

2022~2023년쯤 사내 컴포넌트 라이브러리의 문서를 만들 때 활용해본 경험이 있었고, 그때부터 ‘언젠가 블로그를 다시 만든다면 이걸 써봐야겠다’고 생각했다.

(경쟁 후보로 Notionpresso  도 고려했지만, Notion을 CMS로 다루기엔 불편했다.)

Next.js 의 SSR(Server-Side Rendering)과, SSG(Static Site Generation)를 모두 지원하고, 문서 및 블로그용 테마를 기본 제공한다. 스타일링은 Tailwind CSS , 콘텐츠는 MDX 로 작성할 수 있다.

아직 MDX를 쓸 생각은 없지만, 언젠가 동적인 콘텐츠를 만들 때 유용할 것이다.

AI와 함께하는 마이그레이션

처음엔 Nextra 의 기본 테마로 시작하려 했지만, 아주 쓸만한 템플릿 을 발견하면서 작업이 훨씬 빨라졌다.

Codex CLI를 이용해 다음의 프롬프트로 시작했다:

이 블로그에 전면적인 리팩터링을 할 거야.
Astro 기반으로 되어있는 블로그를 [Nextra](nextra.site) 기반으로 싹 바꾸는 작업이지.

(위에 작성한 요구사항을 붙여넣음)

먼저 `data-temp` 폴더를 만들고
블로그 글(markdown) 과  그와 연관된 image 애셋을 모두 옮긴 뒤
모든 프로젝트 파일을 다 지워버리자.

마크다운 글이 이미지와 제대로 링크되도록 신경써.

테마와 주요 뷰 컴포넌트는 (이 저장소)[https://github.com/phucbm/nextra-blog-starter] 의 구현을 참고해

Codex와 몇 차례 대화를 주고받으며 버그를 수정하고 레이아웃을 다듬자, 대부분의 기능이 빠르게 완성됐다. 머릿속의 아이디어를 직접 코드로 옮기지 않아도 된다는 점이 특히 편했다.

Codex가 가장 큰 도움이 되었던 부분은 Tailwind CSS 기반의 스타일링이었다. 오랜 기간 동안 Ant Design 기반의 컴포넌트만 사용하면서 최소한의 스타일링만 하다 보니 Tailwind CSS를 다뤄볼 기회가 없었다. 그래서 TOC 컴포넌트를 기능적으로 다듬는 과정이 번거로웠는데, details, summary 태그 기반으로 생각보다 쉽게 컴포넌트를 구성할 수 있었다.

이번 프로젝트는 개인적으로 두 번째 ‘Vibe Coding’ 실험이었다. 이전보다 훨씬 매끄럽게 진행되었고, 작업 중 중점적으로 지킨 원칙은 다음과 같다:

• 작업마다 바로바로 커밋하기
• 명령을 내리기 전에 계획 검토하기 - 설명이 구체적일수록 좋다
• Reasoning 모델을 쓴다면 사고 과정 관찰하기 - 가급적이면 시켜놓고 딴 짓 하지 않는다
• 결과물을 살펴보고 ‘이 과정을 통해 내가 원하는 기능이 구현되고 있는가?’ 를 작게 회고하기 - 필요하다면 과감하게 이전 커밋으로 되돌아간다

이제 글만 쓰면 된다

이제는 편하게 마크다운으로 글을 쓰고 저장소로 푸시만 하면 끝이다. 귀찮았지만 오랜만에 쓰고 싶었던 글감이 있었기에 블로그를 새로 만드는 작업부터 할 수 있었다. 직접 블로그를 만들고 싶은 분들이나 미래의 나에게 이 글이 참고가 되면 좋겠다.

지금이라도 ‘내가 익힌 것을 정리할 겸 블로그를 만들어보고 싶은데, 무엇으로 하면 좋을까? 개인 블로그 구축은 너무 손이 많이 가.’ 라고 고민하는 분들에게 말씀드리고 싶은게 있다.

어렵게 생각하지 말고 바로 작성 가능한 플랫폼을 이용하여 글을 쓰세요. 개인 사이트는 나중에 여유가 생길 때 만들어도 됩니다.

하지만 머릿속의 글쓰기 아이디어는 시간이 지나면 증발합니다.

이건 사실 나 자신에게도 하는 말이다.

나는 저널과 개인 노트 작성에는 익숙하다. 개인 노트에 있는 글을 조금만 다듬어도 블로그에 올릴만한 소재가 적지 않을 것이다. 하지만 블로그 등으로 갈무리하는 글의 가치는 AI 시대 덕분에 훨씬 낮아졌다. 그래서 가끔 글을 쓸 의욕을 잃곤 한다. 그럼에도 불구하고 AI 도구를 통해 정리된 정보의 ‘수동적 소비자’에서 벗어나 글을 쓰는 ‘생산자’ 로서의 정체성을 유지하려 애쓰는 일은 언젠가 도움이 되리라 믿는다.

정적 사이트로 빌드할 때 알아두면 좋은 것

미래의 나를 위한 메모다.

• Nextra 는 v4부터 App Router  기반으로만 동작한다.
  • 아주 사소한 것이라도 ‘어떻게 하면 서버 컴포넌트 위주로 구성할 수 있을까?’ 를 생각해본다. 예를 들어 React.useState 등을 쓰지 않는다던가, 브라우저 API 호출을 하지 않는다던가.
• SSR보다는 정적 사이트로 빌드해 배포하는 편이 효율적이다. 특히 현재 배포 환경인 Cloudflare Workers의 경우 더 편하다. 
  • https://nextra.site/docs/guide/static-exports 
• 자주 활용되는 컴포넌트는 mdx-components.tsx 파일에 등록하자.
• 페이지별 커스터마이징은 page.jsx|tsx 파일 안에 구현 가능하다.
  • https://nextra.site/docs/file-conventions/content-directory#add-mdxpathpagejsx-file