목차
처음에는 블로그를 꼭 직접 만들 필요가 있나 싶었다. 글만 쓰면 된다면 티스토리나 브런치, 노션도 충분하다.
그런데 키움디지털 아카데미 강사분께서 블로그 글을 적는 걸 추천한다는 말을 들었다. 이전부터 내 프로젝트를 보여줄 수 있는 포트폴리오 사이트를 만들고 싶었고, 친구들과 스터디한 경험도 있었다. 그래서 크게 고민하지 않고 블로그 겸 포트폴리오 사이트를 만들기로 했다. 바로 실행에 옮겼고, 블로그의 기본 뼈대를 만드는 과정은 하루면 충분했다.
블로그(겸 포트폴리오) 웹 사이트에서 무엇을 보여줄지가 중요하다고 느꼈다.
나는 아래 3가지를 보여주고 싶었고, 그러려면 Next.js로 직접 만드는 게 제일 적합하다고 생각했다.
- AI 경험
- UX 프로젝트
- 디자인 능력
내가 원했던 구조
이 블로그에서 초반에 중요하게 생각했던 건 세 가지였다.
- 기능을 쉽게 확장할 수 있는 코드베이스
- 기존 서비스 구조 따라하기
- 디자인은 추후 원하는 대로 바꿀 수 있게 만들기
아래는 내가 실제로 넣었던 프롬프트다. (개인적으로 “소크라테스처럼 역질문해줘” 라는 프롬프트를 매우 좋아한다.)
💬 내가 넣은 프롬프트 (펼쳐보기)
너는 시니어 프론트엔드 개발자이자 제품 디자이너야. 나는 포트폴리오 겸 블로그 사이트를 만들고 싶고, 이미 GitHub 레포는 만들어둔 상태야.
목표는 네이버 블로그, 티스토리, 브런치처럼 글을 읽기 좋게 보여주는 개인 블로그 사이트를 만드는 것이야. 디자인은 나중에 디자인 md를 줄거라서 크게 중요하지 않고, 우선 기능 구조와 확장 가능한 코드베이스를 잘 만드는 것이 중요해.
현재 상황
- 우선 블로그 기능만 먼저 개발
- 나중에 포트폴리오, 프로젝트 소개, About 페이지 등을 추가할 예정
기술 스택 제안 현재 레포 상태를 먼저 확인한 뒤, 가장 적절한 방식으로 제안해줘.
중요한 요청
- 한 번에 너무 복잡하게 만들지 말고, 궁금한 점·확실하지 않은 점들은 무조건 물어봐줘. 지금은 기획을 중심으로 하고 나하고 plan을 질문하면서 만들자, 소크라테스처럼 나한테 역질문을 던지면서 plan 파일을 만들어줘.
- 무슨 핵심 기능을 만들지부터 고민해줘.
- 나중에 확장할 수 있도록 구조를 많이 고려해줘.
- 작업이 끝나면 변경된 파일 목록과 각 파일의 역할을 설명해줘.
내가 만들려던 사이트에는 디자이너가 개인적으로 운영하는 포트폴리오와 개발자가 운영하는 블로그의 성격이 함께 있기를 바랐다. 그러려면 디자인 적용보다 초반 프레임워크를 먼저 봐야겠다고 생각했다. 나중에 디자인을 바꾸는 것보다 프레임워크를 바꾸는 일이 더 어려울 것 같다고 생각했기 때문이다. 아래는 Claude가 준 역질문을 바탕으로 나눈 대화 요약본이다.
💬 Claude와 나눈 대화 요약
Q. 글을 쓸 때는 어떤 방식으로 할까?
A. 마크다운 파일로 작성Q. 네이버 블로그와 티스토리 중 어느 쪽 레이아웃을 기본으로 삼을까요? 둘은 구조가 꽤 달라요.
A. 티스토리 기본 스킨 스타일Q. 기술 스택은 Next.js(App router) + 마크다운 처리 조합을 추천하려는데 괜찮을까요? Vercel 배포와 궁합이 가장 좋고, 나중에 조회수 같은 서버 기능도 붙일 수 있어요.
A. Next.jsQ. 조회수/공감은 유일하게 DB(무료 티어 Redis 등)가 필요한 기능이에요. 언제 구현할까요?
A. 2단계로 미루기
기술 스택
처음 버전의 스택은 단순하게 잡았다.
| 영역 | 선택 |
|---|---|
| 프레임워크 | Next.js 16 / App Router |
| 콘텐츠 | Markdown + gray-matter |
| 마크다운 처리 | unified / remark / rehype |
| 코드 하이라이팅 | Shiki 기반 rehype-pretty-code |
| 스타일 | CSS Modules + CSS 변수 토큰 |
CMS는 넣지 않았다. 지금 단계에서는 글을 빨리 고치고 구조를 바꾸는 게 더 중요했다. CMS를 먼저 붙이면 편해지는 부분도 있지만, 반대로 데이터 모델을 너무 빨리 고정할 수 있다.
그래서 일단 파일 기반으로 시작했다.
코드를 쓰기 전에 배포 경로부터 만들었다
블로그의 뼈대를 만들기 전에 먼저 GitHub 레포와 Vercel 프로젝트를 연결했다. 순서는 단순했다.
- GitHub에
portfolio-blog레포를 만들고, 로컬 Next.js 프로젝트를 첫 커밋으로 push했다. - Vercel에서 이 레포를 Import하고 첫 배포를 실행했다. 이때 Vercel 기본 주소가 먼저 생긴다.
- Production Branch를
main으로 두었다. 그래서mainpush는 실제 사이트 배포, 다른 브랜치 작업은 Preview 배포로 분리된다. - 기본 주소에서 화면과 빌드가 정상인지 확인한 다음, 커스텀 도메인
dotorian.kro.kr을 내도메인.한국에서 연결했다.
Vercel과 GitHub를 연동해 두면 글을 하나 쓰거나 컴포넌트를 고친 뒤 따로 배포 명령을 칠 필요가 없다. 커밋이 곧 배포였다. 처음부터 이 경로를 붙여둔 이유는, "로컬에선 됐는데 실제 사이트에선 깨지는" 상황을 최대한 늦게가 아니라 최대한 일찍 만나기 위해서였다.
도메인을 고르고 DNS를 연결한 과정은 별도로 정리할 예정이다. 대신 이 블로그에 실제로 붙인 기능들은 한 글에 몰아넣지 않고, 아래처럼 기능별 기록으로 나눴다.
- 다람쥐와 도토리로 사이트의 반응을 만든 과정
- GitHub 커밋으로 발행하는 웹 관리자
- GitHub Discussions를 댓글 UI로 연결한 방법
- Upstash Redis로 조회수와 공감을 나눈 방법
Markdown 파이프라인
핵심은 unified 체인이다. 빌드 타임에 Markdown을 HTML로 바꾸고, 런타임에서는 이미 만들어진 글을 보여준다.
const processor = unified()
.use(remarkParse)
.use(remarkGfm)
.use(remarkRehype, { allowDangerousHtml: true })
.use(rehypeSlug)
.use(rehypePrettyCode, { theme: { light: 'github-light', dark: 'github-dark' } })
.use(rehypeStringify);처음에는 이 부분이 단순해 보였는데, 실제로는 꽤 중요했다. 글 본문, 목차, 코드 블록, slug가 여기서 결정된다.
목차는 같은 트리에서 뽑았다
목차는 별도 규칙으로 만들지 않았다. rehype-slug가 heading에 붙인 id를 같은 hast 트리에서 읽는다.
이렇게 하면 앵커와 목차가 따로 놀 가능성이 줄어든다. 나중에 제목을 바꿔도 같은 파이프라인 안에서 다시 계산된다.
frontmatter는 느슨하게 두지 않았다
글은 자유롭게 쓰고 싶지만, 메타데이터까지 자유로우면 빌드가 불안해진다. 그래서 frontmatter는 zod로 검증했다.
const frontmatterSchema = z.object({
title: z.string().min(1),
date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
category: z.string().min(1),
});특히 날짜는 문자열로 강제했다. YAML이 날짜를 Date 객체로 해석하면 타임존 때문에 하루가 밀릴 수 있다. 작은 문제처럼 보이지만, 글 목록 정렬이나 timeline에서는 바로 티가 난다.
디자인은 나중에 바뀔 수 있게 했다
이 블로그는 처음부터 완성된 디자인을 목표로 하지 않았다. 오히려 나중에 DESIGN.md 기준을 가져와도 CSS 전체를 다시 쓰지 않도록 만드는 게 중요했다.
그래서 스타일은 CSS 변수 토큰을 기준으로 잡았다. 컴포넌트는 실제 색상값보다 --color-surface, --color-border, --color-fg 같은 역할 이름을 참조한다.
이 덕분에 디자인을 바꿀 때 손대야 하는 범위가 줄어든다.
그래서 Vercel이 공개한 design.md를 참고 자료로 삼고, 그 기준을 토대로 디자인을 만들어 달라고 AI에 요청했다.
이 문서는 색·타이포·간격·컴포넌트 규칙을 Markdown으로 정리한 Vercel의 디자인 기준이다. 열어 보면 색 토큰과 타이포, 간격 규칙이 텍스트로 정리돼 있어 사람과 AI가 같은 기준을 확인하기 좋다.
크게 기대하지 않았지만 디자인 결과는 만족스러웠다. 큰 이유가 없다면 앞으로도 이대로 유지할 생각이다.
1차 결과물 사진들
지금 남은 한계
아직 완성된 블로그라고 보기는 어렵다.
- 글쓰기 경험은 아직 파일 편집 중심이다.
- 관리자 화면은 더 다듬어야 한다.
- 프로젝트 글이 많아졌을 때 탐색 구조도 다시 봐야 한다.
- 디자인 토큰도 실제 글이 쌓이면서 더 정리해야 한다.
그래도 지금 구조는 마음에 든다. 글, 프로젝트, 디자인 기준이 한 저장소 안에서 함께 움직일 수 있게 만들었다.
내가 원했던 건 거창한 블로그도 포트폴리오 페이지도 아닌 나만의 프로젝트를 만들고 그 과정을 글로 남길 수 있는 작업대였다. 지금 버전은 그 출발점에 가깝다. 다음 글에서는 plan.md와 design.md를 가지고 블로그를 만들어간 과정, 블로그 이름이 왜 Dotorian인지, 그리고 메인 홈 화면에 넣은 다람쥐/도토리 애니메이션을 Claude로 만들고 다듬은 과정부터, 여기에 하나씩 얹은 기능들 — giscus로 붙인 댓글, Upstash Redis로 센 조회수, Supabase를 연동해 만든 방명록, 그리고 NextAuth + GitHub 로그인으로 나만 들어가는 admin 페이지까지 — 을 어떻게 붙였는지 차례로 적어보겠다.