도휘닷컴

Astro와 TypeScript를 기반으로 외부 CMS 의존성 없이 독립적으로 설계·운영하는 정적 기술 블로그 및 포트폴리오 플랫폼(dohwi.com) 구축 기록입니다. 한국어와 영어를 동등하게 다루는 다국어 아키텍처, 빌드 타임 정적 전문 검색, Satori 기반 동적 OG 렌더링, 자체 Nginx 컨테이너 배포 파이프라인을 직접 구성했습니다.

항목	내용
사이트 URL	`https://dohwi.com`
핵심 기술	`Astro`, `TypeScript`, `Tailwind CSS`, `MDX`, `Pagefind`
주요 기능	KO/EN 다국어 라우팅, 클라이언트 정적 검색, Satori 동적 OG, RSS 피드, sitemap
배포 환경	Docker 컨테이너 및 자체 호스팅 Nginx (`dist_tmp` → `rsync` 빌드 파이프라인)

왜 만들게 되었나

기존 상용 블로그 서비스나 무거운 풀스택 프레임워크는 레이아웃 제약이 크거나, 단순 문서 사이트임에도 브라우저로 대용량 자바스크립트 런타임을 전송하는 비효율이 있었습니다. 또한 글과 프로젝트가 늘어날수록 다국어 메타데이터와 검색 기능을 외부 유료 서비스 없이 깔끔하게 통제하기 어려웠습니다.

외부 플랫폼이나 무거운 프레임워크 대신, 웹 표준과 정적 생성 방식을 활용해 가볍고 빠른 자체 기술 블로그 플랫폼을 구축하고자 개발을 시작했습니다.

기존 방식과의 비교

비교 항목	상용 블로그 / 풀스택 프레임워크	도휘닷컴 (Astro 정적 플랫폼)
런타임 오버헤드	수백 KB 이상의 무거운 JS 번들 브라우저 전송	제로 JS 지향, 정적 HTML/CSS 중심의 초경량 서빙
다국어 제어권	유료 플러그인 또는 제한된 번역 메타데이터	KO/EN 대칭적 라우팅 및 빌드 타임 타입 단위 완전 제어
검색 시스템	외부 유료 검색 API 의존 또는 무거운 검색 엔진	Pagefind 기반 완전 정적 인덱싱 & 클라이언트 지연 로드
인프라 종속성	특정 PaaS/CMS 플랫폼 벤더 락인	자체 Docker + Nginx 컨테이너 환경에서 독립 배포

겪었던 문제점

순수 콘텐츠 사이트라 하더라도 다국어 메타데이터 정합성, 서버 없는 전문 검색, 무중단 배포 등 프로덕션 수준의 완성도를 확보하는 과정에서 현실적인 난관들이 있었습니다.

정적 다국어(i18n) 라우팅과 메타데이터 일관성 유지
콘텐츠 디렉터리(contents/blog, contents/projects) 내 한국어와 영어 파일이 쌍을 이루도록 유지하면서, 언어별 Canonical URL, hreflang 대체 링크, Open Graph 태그가 어긋나지 않도록 빌드 타임에 엄격히 검증해야 했습니다.
별도 서버 없는 다국어 전문 검색 구현
Elasticsearch나 외부 클라우드 검색 API를 띄우지 않고 순수 정적 파일만으로 검색을 구현해야 했습니다. 특히 언어별(lang:ko, lang:en) 필터링과 모달 UI 라이프사이클(인스턴스 생성/해제, 스크립트 지연 로드)을 클라이언트 리소스 낭비 없이 최적화하는 과정이 필요했습니다.
빌드 시점 인덱싱과 배포 무중단 정합성
pagefind는 빌드 산출물 디렉터리를 직접 읽고 인덱스를 생성하므로, Astro 빌드 산출물과 검색 인덱스가 원자적으로 교체되지 않으면 빌드 도중 서빙 불일치나 캐시 충돌이 발생할 수 있었습니다.

설계와 해결 방법

Content Collections 기반 엄격한 스키마 검증
src/content.config.ts에서 Astro glob 로더와 Zod 스키마를 정의하여 lang, translationKey, 메타데이터 필드를 빌드 타임에 타입 단위로 강제했습니다. 번역 누락이나 필수 필드 오류를 빌드 단계에서 원천 차단합니다.
Pagefind 기반 정적 검색과 언어 필터링
검색 모달(SearchModal.astro)을 열 때만 Pagefind 에셋을 지연 로드(Lazy load)하도록 구성하고, DOM 속성(data-pagefind-lang, data-pagefind-filter)을 연동해 현재 언어에 맞는 검색 결과만 정확히 노출되도록 제어했습니다.
Satori & Resvg 동적 OG 파이프라인
빌드 시점에 글과 프로젝트 메타데이터를 기반으로 SVG를 합성하고 PNG로 렌더링(src/lib/og.ts)하여, 외부 썸네일 생성 서비스 없이도 완전한 브랜딩 이미지를 자동 생성합니다.
임시 디렉터리와 rsync를 결합한 무중단 빌드 파이프라인
빌드 스크립트를 astro build --outDir dist_tmp && pagefind --site dist_tmp; rsync -a --delete --exclude='.prerender' dist_tmp/ dist/로 구성하여, 인덱싱 완료 후 최종 산출물이 원자적(Atomic)으로 일괄 교체되도록 설계했습니다.

프로젝트 목록 화면

언어 전환, 태그, 링크 구조를 일관된 규칙으로 정리한 프로젝트 목록 화면.

배운 점

정적 사이트 제너레이터를 사용하더라도 다국어 SEO, 클라이언트 검색 라이프사이클, 컨테이너 서빙 헤더 정책까지 밑바닥부터 직접 설계하며 웹 표준의 강력함을 깊이 체감했습니다. 무거운 자바스크립트 프레임워크나 외부 SaaS에 기대지 않고도, 현대적인 정적 아키텍처만으로 빠르고 안정적인 프로덕션 웹 서비스를 구축할 수 있음을 배웠습니다.

마치며

글 상세 화면

목차와 OG 비주얼을 결합해 읽기 흐름을 정리한 글 상세 화면.

불필요한 런타임 의존성을 걷어내고 웹 표준과 정적 아키텍처에 집중함으로써, 빠르고 관리하기 쉬운 지속 가능한 개인 기술 블로그의 기틀을 마련했습니다.