이 블로그를 만들며 사용한 기술들
이 블로그는 어떤 조합으로 만들었을까
블로그를 만들기 전에는 글만 올릴 수 있으면 된다고 생각했다.
그런데 막상 만들기 시작하니, 글을 쓰는 공간이면서 동시에 나를 설명하는 포트폴리오 역할도 해야 했다.
단순히 마크다운을 렌더링하는 수준을 넘어서, 글 목록 구조, 포스트 상세, 공유 메타데이터, 댓글, 문의 폼, 검색 노출까지 한 번에 정리할 필요가 있었다.
그래서 이번에는 익숙한 기술만 나열하기보다, 왜 이 조합을 선택했는지 기준을 갖고 구성했다.
전체 구조
이 블로그는 크게 세 층으로 나뉜다.
- App Router 기반 페이지 구조
- 마크다운 포스트를 읽고 정리하는 콘텐츠 계층
- 공통 UI와 메타데이터를 담당하는 표현 계층
블로그 글은 posts/ 아래의 마크다운 파일로 관리하고, Next.js가 이를 읽어 실제 페이지로 렌더링한다.
여기에 About, Portfolio, Contact 같은 정적 페이지를 함께 두어 블로그와 포트폴리오가 자연스럽게 이어지도록 구성했다.
사용한 기술
Next.js 16
이 프로젝트의 중심 프레임워크다.
페이지 라우팅, metadata, sitemap, robots, RSS 같은 웹사이트 운영에 필요한 기본 기능을 App Router 안에서 한 흐름으로 정리할 수 있다는 점이 가장 좋았다.
특히 이 블로그에서는 아래 기능들이 Next.js 위에서 자연스럽게 연결된다.
- 포스트 상세 페이지 라우팅
robots.txt,sitemap.xml,rss.xml생성- 공유용 Open Graph 메타데이터 관리
- Contact API 라우트 처리
블로그처럼 콘텐츠 중심 사이트를 만들 때는, 페이지와 메타데이터를 같은 구조 안에서 다룰 수 있다는 점이 생각보다 큰 장점이었다.
React 19
실제 UI를 구성하는 기본 레이어는 React다.
블로그 자체는 정적인 페이지가 많지만, 태그 필터링이나 문의 폼처럼 사용자 상호작용이 필요한 부분은 React의 컴포넌트 모델 덕분에 깔끔하게 분리할 수 있었다.
이번 블로그에서는 과하게 복잡한 상태 관리보다는, 필요한 만큼만 클라이언트 컴포넌트를 사용하는 쪽으로 정리했다.
덕분에 정적인 페이지는 최대한 단순하게 두고, 상호작용이 필요한 부분만 선택적으로 클라이언트에 맡길 수 있었다.
TypeScript
블로그 프로젝트라고 해서 타입이 덜 중요하진 않았다.
오히려 포스트 메타데이터처럼 파일 기반으로 관리되는 값들은 한번 구조가 어긋나면 나중에 찾기 귀찮은 문제가 되기 쉽다.
그래서 아래 같은 구조를 타입으로 명확히 잡아 두었다.
- 포스트 메타데이터
- 작성자 정보
- 문의 폼 payload
- metadata에 전달되는 값들
콘텐츠 사이트는 규모가 작아 보여도, 시간이 지나며 글 수가 늘어나면 이런 기본 타입 정리가 유지보수 차이를 만든다고 느꼈다.
Tailwind CSS 4
스타일링은 Tailwind CSS 4를 사용했다.
이번 블로그에서는 화려한 컴포넌트 라이브러리보다는, 텍스트 중심 콘텐츠가 편하게 읽히는 레이아웃과 간격을 빠르게 다듬는 데 Tailwind가 잘 맞았다.
특히 좋았던 점은 아래와 같다.
- 페이지별 레이아웃 조정이 빠름
- 포스트 카드, 뱃지, 내비게이션 같은 반복 UI를 일관되게 유지하기 쉬움
- 마크다운 본문 스타일도 한 파일 안에서 비교적 명확하게 관리 가능
처음부터 디자인 시스템을 크게 만들기보다, 블로그의 읽기 경험에 집중하면서 필요한 만큼만 스타일을 쌓아 갈 수 있는 점이 좋았다.
shadcn/ui
이 프로젝트의 UI는 전부 직접 처음부터 짠 것이 아니라, shadcn/ui 스타일의 컴포넌트를 기반으로 정리했다.
버튼, 카드, 뱃지, 드롭다운, 입력 폼 같은 공통 UI를 일관된 톤으로 가져가기 좋았고, 필요할 때 코드 수준에서 직접 다듬을 수 있다는 점이 특히 마음에 들었다.
완전히 닫힌 UI 라이브러리를 쓰는 것보다, 내 코드베이스 안에 컴포넌트가 들어와 있는 구조가 개인 프로젝트에는 훨씬 잘 맞았다.
gray-matter
마크다운 파일의 frontmatter를 파싱하는 데 사용했다.
제목, 날짜, excerpt, 태그, 커버 이미지 같은 정보를 글 본문과 분리해서 관리할 수 있기 때문에, 블로그 구조에서는 사실상 핵심 도구에 가깝다.
이 프로젝트에서는 gray-matter로 메타데이터를 읽고, 그 값을 아래에 재사용한다.
- 홈 글 목록
- 포스트 상세 헤더
- Open Graph 메타데이터
- sitemap / RSS 피드
한 번 메타데이터 구조를 잡아 두니, 포스트를 추가할 때도 훨씬 단순해졌다.
remark / remark-gfm / remark-html
포스트 본문은 마크다운으로 작성하고, 렌더링은 remark 계열을 사용했다.
remark-gfm을 함께 붙여 GitHub Flavored Markdown 문법도 지원하도록 해 두었다.
이 조합을 선택한 이유는 단순했다.
블로그 글에서 필요한 수준의 마크다운 처리에는 충분히 안정적이고, 구조도 비교적 단순했기 때문이다.
현재는 아래 요소들을 자연스럽게 다룰 수 있다.
- 제목
- 리스트
- 코드 블록
- 링크
- 표
지금 단계에서는 MDX까지 확장하기보다, 마크다운 기반 글쓰기에 집중하는 편이 더 잘 맞았다.
Resend
문의 폼 메일 전송은 Resend로 처리하고 있다.
개인 블로그에서 Contact 기능을 넣고 싶을 때, 직접 메일 서버를 붙이거나 복잡한 외부 폼 서비스에 의존하지 않아도 된다는 점이 좋았다.
문의 폼에서는 다음 흐름으로 동작한다.
- 클라이언트에서 입력값 검증
- API 라우트에서 한 번 더 검증
- 스팸 방지용 hidden field 확인
- Resend를 통해 메일 발송
블로그가 단순히 읽는 공간이 아니라, 실제로 연락을 받을 수 있는 창구가 된다는 점에서 만족스러운 선택이었다.
기술을 고를 때 중요하게 본 기준
이번 블로그를 만들며 가장 중요하게 본 기준은 세 가지였다.
1. 글을 쓰고 관리하기 쉬울 것
포스트를 추가하는 작업이 복잡하면 결국 글을 덜 쓰게 된다.
그래서 데이터베이스보다 마크다운 파일 기반 구조를 택했고, 메타데이터도 frontmatter로 단순하게 유지했다.
2. 블로그와 포트폴리오를 함께 담을 수 있을 것
이 사이트는 글만 모아 둔 공간이 아니라, 내가 어떤 작업을 해 왔는지를 함께 보여주는 공간이기도 하다.
그래서 페이지 구조, 메타데이터, 포트폴리오 섹션, 문의 기능이 서로 따로 놀지 않도록 구성하는 데 신경을 썼다.
3. 나중에 확장하기 쉬울 것
지금은 비교적 단순한 블로그지만, 이후에는 글 구조를 더 다듬거나, 프로젝트 소개를 늘리거나, 포스트 표현을 더 개선할 가능성이 높다.
그래서 너무 무거운 구조보다는, 필요한 기능을 조금씩 붙여 갈 수 있는 조합을 선택했다.
마무리
아직 이 블로그는 계속 다듬어 가는 중이다.
하지만 이번에 한 번 구조를 제대로 정리해 두면서, 글을 쓰는 흐름과 사이트를 운영하는 흐름이 꽤 자연스럽게 이어지기 시작했다.
앞으로는 단순히 어떤 기술을 썼는지 나열하는 것보다, 이 구조 안에서 왜 이런 선택을 했는지 더 구체적으로 남겨 보려고 한다.
updated 2026-03-31