1. 개요

Notion CMS 블로그는 Notion을 글 작성·콘텐츠 관리 도구로 쓰고, 공개 화면은 별도 웹앱에서 렌더링하는 방식입니다. 에디터 경험은 Notion에 맡기면서도 디자인, 라우팅, 검색, 배포 방식은 직접 제어할 수 있어 기존 블로그 플랫폼의 작성 편의성과 커스텀 블로그의 자유도를 함께 노릴 수 있습니다.

다양한 블로그 서비스 (Github Pages, Tistory, Medium, Velog)

누구나 그렇듯 대학생 시절부터 공부한 내용을 정리할 나만의 블로그를 만들고 싶다는 생각을 했었습니다. Github Pages, Tistory 를 써보려 했으나 아래 한계가 늘 걸림돌이었습니다.

글 쓰는 것 자체가 불편하다 보니 점점 글을 안 쓰게 되었고, 블로그 운영도 멈췄습니다. 몇 년이 지나 개인 스터디·프로젝트를 진행하며 체계적으로 기록하고 다시 꺼내볼 공간이 필요하다는 걸 깨달았습니다.

평소 정리에 Notion 을 많이 쓰다 보니 자연스럽게 Notion 기반 블로그를 떠올렸습니다. 다만 단순히 Notion 페이지를 publish 하는 방식은 디자인·기능 커스터마이징이 불가능했습니다. 그래서 Notion 을 CMS (Content Management System) 로 쓰고, 디자인과 기능은 직접 개발하기로 했습니다.

2. 설계 / 구상

단순 publish 로는 카테고리·태그 검색이나 편의 기능을 제공하기 어려웠기에, Notion 을 CMS 로 두고 기획부터 개발까지 직접 하기로 했습니다. 기획은 퇴근 후 틈틈이 진행해 약 1달이 걸렸습니다.

컴포넌트 디자인 전, 블로그 색감을 정할 때 v0.dev 로 컬러 팔레트를 만들어 친구들에게 자문을 구했습니다(배경색은 직접 정함).

v0.dev 로 그린 컬러 팔레트

이후 가장 작은 단위의 컴포넌트(Typography, Button 등) 부터 시작해 확장하는 구조로 디자인을 진행하고, 친구들의 피드백으로 수정을 반복했습니다.

피그마로 직접 그린 블로그 컴포넌트 디자인

컴포넌트를 기반으로 만든 페이지 디자인

3. 개발 / 구현

이 프로젝트는 Figma MCP + Github Copilot 을 사용한 Vibe Coding 방식으로 진행했습니다.

Figma 와 Github Copilot

Figma 로 디자인한 컴포넌트 URL 만 넣으면(사전 설정 필요) Github Copilot 이 컴포넌트 코드, Storybook, 테스트 코드를 작성해 주었습니다.

├── PostRow
│   ├── PostRow.stories.tsx
│   ├── PostRow.test.tsx
│   ├── PostRow.tsx
│   └── index.tsx
└── TagList
    ├── TagList.stories.tsx
    ├── TagList.test.tsx
    ├── TagList.tsx
    └── index.tsx

다만 FE 경험이 부족했던 저에게는 Vibe Coding 중에도 고민이 끊이지 않았습니다.

"Props 설계는 지금 할까 나중에 할까? 디자인 요소부터 개발할까? 다크 모드는 언제 만들까? Notion 데이터 로직을 먼저 구현할까?"

일단 부딪혀가며 수많은 시행착오와 리팩토링을 거듭했습니다. Vibe Coding 특성상 AI 가 작성한 코드가 의도와 다르게 동작하는 경우가 있어, 품질 유지를 위해 CI 환경에 공을 들였습니다.

3.1. Storybook & 테스트 코드 의무화

copilot-instructions.md 에 "컴포넌트 구현 시 반드시 Storybook 과 테스트 코드를 작성할 것"을 명시하고, codecov.yml 로 테스트 커버리지 80% 이상을 목표로 했습니다.

coverage 리포트 예시

3.2. Github Actions 기반 자동 테스트

PR 을 올리면 Github Actions 가 자동으로 테스트·빌드를 실행하도록 설정했습니다. 빌드 + 테스트 + 정적 분석이 모두 통과해야만 main 에 merge 되도록 해, 깨진 코드가 병합되는 최악의 상황을 막았습니다.

Github Checks 항목

3.3. Dependabot 을 이용한 패키지 관리

dependabot.yml 에 업데이트 규칙과 auto-merge 여부를 정의해 의존성을 주기적으로 갱신했습니다. 덕분에 오래된 라이브러리 방치를 막고 보안 패치도 빠르게 적용할 수 있었습니다.

dependabot + auto-merge 로 dev 패키지 자동 업데이트

4. 배포

배포 방식은 오래 고민한 부분입니다. 처음엔 자체 서버 배포를 생각했지만, 블로그는 정적(static) 빌드만으로 충분해 굳이 서버가 필요 없었습니다. 그래서 Github Pages 를 선택해, Notion 글을 빌드 시점에 정적으로 변환한 결과물을 배포하는 방식으로 갔습니다.

그런데 빌드를 실행할 때마다 Notion 데이터를 가져오는 부분에서 timeout 이 발생했습니다. 원인을 못 찾다가 react-notion-x의 Notion page fetch 동작과 관련 사례를 찾아보니, collection/database가 있는 페이지에서 fetch가 멈출 수 있는 맥락이 있었습니다.

제안된 대로 react-notion-x 를 특정 버전으로 다운그레이드하니 빌드가 정상 완료됐고, 마침내 자체 개발한 Notion CMS 기반 블로그를 배포할 수 있었습니다.

5. 마무리 / 회고

처음엔 2달이면 끝날 줄 알았지만, 기획이 길어지고 개인 사정이 겹쳐 총 4달이 걸렸습니다. 그래도 퇴근 후 틈틈이 완성해 배포까지 마쳐 뿌듯했습니다. 올해 목표였던 연간 사이드 프로젝트 2개 중 하나를 마무리했고, 첫 React 기반 FE 프로젝트에서 더 나은 프로세스·구조를 고민할 수 있었습니다.

아직 남은 기능도 있습니다(언젠가 구현 예정).

• About 페이지
• ToC (Table of Contents)
• Fuzzy Search

마지막으로 기획·디자인·기능 하나하나에 피드백을 아끼지 않은 친구들에게 고맙다는 말을 전하고 싶습니다.

6. 참고문헌

• v0v0.app
• react-notion-xgithub.com