[블로그 개편기 - 4] Astro와 MDX로 만든 작고 확장 가능한 운영 구조

콘텐츠 모델을 정한 뒤 기술 스택은 Astro, TypeScript, MDX, GitHub Pages로 수렴했다. 목표는 기능을 많이 넣는 것이 아니라 정적 사이트의 단순함을 유지하면서 필요한 곳에만 표현력을 여는 것이었다.

Astro와 MDX

Astro는 콘텐츠 중심 정적 사이트를 빠르게 제공하기 좋다. JavaScript를 꼭 필요한 곳에만 보내고, 빌드 결과를 GitHub Pages에 그대로 올릴 수 있다.

MDX는 운영 방식의 핵심이다. 일반 글은 Markdown처럼 쓰되 Feature 글에서는 이미지 그리드나 화면 너비를 가득 쓰는 사진 같은 컴포넌트를 호출할 수 있다. 쉬운 작성과 높은 표현력을 한 저장 형식 안에 둔 셈이다.

게시물에는 제목, 설명, 날짜, 카테고리, 게시물 타입, 표지 이미지와 대체 텍스트, 태그, 추천 여부, 초안 여부를 기록한다. 스키마가 이 값을 검증하므로 오타로 존재하지 않는 카테고리가 생기거나 잘못된 타입이 빌드에 섞이는 일을 줄인다.

이미지는 먼저 단순하게

사진 중심 사이트라고 처음부터 CDN이나 CMS를 붙이지는 않았다. 이미지는 public/images/에 두고, 콘텐츠에서는 안정적인 경로와 의미 있는 alt를 사용한다.

사진이 크게 늘면 Cloudinary나 Cloudflare R2로 옮길 수 있고, 작성 화면이 필요해지면 Git 기반 CMS를 더할 수 있다. 중요한 것은 지금 필요하지 않은 복잡성을 미리 운영하지 않되, 콘텐츠 구조를 다시 쓰지 않고도 이동할 수 있게 만드는 것이다.

검색 서버 없이 검색하기

검색은 Pagefind를 사용한다. 빌드가 끝난 정적 HTML을 읽어 색인을 만들기 때문에 별도 검색 서버가 없다.

정적 빌드 결과를 색인해 별도 검색 서버 없이 동작하는 검색 화면.

빌드 흐름은 다음과 같다.

Astro 정적 빌드 → Pagefind 색인 생성 → GitHub Pages 배포

검색은 화면에 입력창 하나만 보이지만, 운영 측면에서는 서버 비용과 장애 지점을 늘리지 않는 선택이다.

나중을 위해 지금 복잡해지지 않기

콘텐츠 파일은 src/content/posts/YYYY-MM-DD-slug.mdx 형태로 관리한다. 초기에는 날짜별 폴더도 검토했지만, 현재 규모에서는 한 폴더의 단일 파일 구조가 더 단순했다.

이 프로젝트에서 확장 가능하다는 말은 모든 기능을 미리 넣는다는 뜻이 아니다. 데이터의 경계를 명확히 하고, 저장소나 작성 도구를 바꿀 때 글 자체를 다시 쓰지 않아도 된다는 뜻에 가깝다.

다음 글에서는 기술보다 더 많은 재작업을 만들었던 모바일 메뉴와 반응형 정보구조를 정리한다.