Kreath Archive

프로젝트 소개

"나를 기록하고 보여주는 공간"을 목표로 만든 종합 개인 아카이브 사이트입니다.

기술 블로그, 프로젝트 포트폴리오, 독서 리뷰를 흩어지지 않게 한곳에 모아 관리하고 싶다는 필요에서 출발했습니다. 단순한 블로그가 아니라 내가 배우고, 만들고, 읽은 것을 체계적으로 기록하는 아카이브를 지향합니다.

핵심 설계 원칙

• 콘텐츠 중심: MDX 파일을 Git으로 관리하여 별도 CMS 없이도 버전 관리와 협업이 가능한 구조
• 타입 안전성: Velite + Zod 스키마를 통해 콘텐츠의 frontmatter부터 본문까지 빌드 타임에 타입 검증
• 성능 우선: 정적 생성(SSG) 기반으로 빠른 초기 로딩과 SEO 최적화를 동시에 달성
• 확장 가능한 구조: 섹션(Tech, Projects, Books)별 독립적인 콘텐츠 스키마와 라우팅으로 새로운 카테고리 추가가 용이

주요 기능

콘텐츠 관리

• MDX 기반 작성: 마크다운에 React 컴포넌트를 결합하여 풍부한 콘텐츠 표현
• 시리즈 기능: 연관된 포스트를 시리즈로 묶어 순서대로 탐색할 수 있는 네비게이션 제공
• 카테고리 & 태그: 다중 분류 체계로 콘텐츠를 체계적으로 정리
• 독서 리뷰: 책별 챕터 단위 리뷰, 평점, 읽기 상태 관리 지원

사용자 경험

• 다크/라이트 테마: next-themes 기반 시스템 설정 연동 및 수동 전환
• 커맨드 팔레트: Cmd+K로 전체 콘텐츠 검색 및 빠른 네비게이션
• 반응형 디자인: 모바일부터 데스크톱까지 최적화된 레이아웃
• 코드 구문 강조: Shiki 기반 다중 테마 지원, 라인 하이라이트 및 복사 기능

SEO & 분석

• 구조화된 데이터: JSON-LD(BlogPosting, Person, WebSite) 자동 생성
• 메타데이터 자동화: 페이지별 OG Image, Twitter Card, Canonical URL 설정
• 사이트맵 & RSS: 동적 sitemap.xml과 RSS 피드 자동 생성
• Analytics 연동: Google Analytics 4 + Umami 이중 트래킹

소셜 & 인터랙션

• 댓글 시스템: Giscus를 통한 GitHub Discussions 기반 댓글
• 공유 기능: 주요 SNS 및 링크 복사 공유 버튼

기술 스택

아키텍처

content/           ← MDX 콘텐츠 (Git 관리)
  tech/            ← 기술 블로그 포스트
  projects/        ← 프로젝트 포트폴리오
  books/           ← 독서 리뷰 (시리즈 구조)
       ↓ Velite (빌드 타임 변환)
       ↓ Zod 스키마 검증 → 타입 안전 데이터
       ↓
app/               ← Next.js App Router
  tech/            ← SSG 기반 블로그 페이지
  projects/        ← 프로젝트 상세 페이지
  books/           ← 독서 리뷰 페이지
       ↓
components/        ← 재사용 UI 레이어
  mdx/             ← Callout, CodeBlock 등 커스텀 컴포넌트
  ui/              ← 범용 UI 프리미티브

개발 과정에서의 기술적 선택

Velite를 콘텐츠 엔진으로 선택한 이유

Contentlayer가 유지보수 중단된 상황에서, Velite는 Zod 스키마 기반의 타입 안전성과 빠른 빌드 속도를 제공합니다. frontmatter 오류를 빌드 타임에 잡아주기 때문에 콘텐츠가 많아져도 안정적으로 관리할 수 있습니다.

Tailwind CSS v4 도입

v4의 CSS-first 설정 방식과 개선된 성능을 활용하여, globals.css에서 CSS 변수 기반의 테마 시스템을 구성했습니다. 다크/라이트 모드 전환 시 색상 체계가 일관되게 유지됩니다.

정적 생성 + 점진적 확장

모든 콘텐츠 페이지를 SSG로 생성하여 빠른 로딩 속도를 확보하면서, 댓글이나 Analytics 같은 동적 기능은 클라이언트 사이드에서 처리하는 하이브리드 접근을 채택했습니다.