AI로 블로그 만들기 — Next.js + 마크다운 정적 사이트 30분 완성

이 튜토리얼은 Claude Code / Next.js 16 / gray-matter 기준입니다 (2026-04). 도구 업데이트 시 검토 필요.

마크다운 파일을 폴더에 넣으면 자동으로 블로그 글이 된다. 데이터베이스도 CMS도 필요 없고, 글을 쓰는 것만큼 단순하다. Claude Code와 Next.js로 30분 안에 이 구조를 완성할 수 있다.

준비물

• Node.js 20+: node -v로 확인
• Claude Code (claude.ai/code 또는 VS Code 확장)
• Vercel 계정 (무료, 배포용)
• 예상 시간: 30분

1. 프로젝트 생성

npx create-next-app@latest my-blog \
  --typescript \
  --tailwind \
  --app \
  --no-src-dir
cd my-blog
npm install gray-matter react-markdown

gray-matter는 마크다운 파일의 frontmatter(제목·날짜 등 메타데이터)를 파싱하는 라이브러리다. react-markdown은 마크다운 본문을 HTML로 렌더링한다.

2. 마크다운 파일 구조 설정

Claude Code에 요청한다.

posts/ 폴더를 만들고 샘플 마크다운 파일 2개를 만들어줘.
각 파일 상단 frontmatter에 title, date, description 필드를 포함해야 해.

생성된 파일 예시:

---
title: "첫 번째 글"
date: "2026-04-30"
description: "블로그 첫 글입니다."
---

여기에 본문을 씁니다.

3. 글 목록 유틸리티 작성

Claude Code에 요청한다.

lib/posts.ts 파일을 만들어줘.
posts/ 폴더의 .md 파일을 모두 읽어서
{ slug, title, date, description } 배열을 반환하는 getAllPosts() 함수를 구현해줘.
gray-matter로 frontmatter를 파싱하고, date 기준 내림차순 정렬해줘.

서버 사이드에서만 동작하는 코드임을 확인한다. fs, path 모듈은 서버에서만 사용 가능하며 클라이언트 컴포넌트에서 import하면 에러가 발생한다.

4. 글 목록·개별 글 페이지 구현

목록 페이지를 요청한다.

app/blog/page.tsx 에 getAllPosts()로 글 목록을 보여주는 페이지를 만들어줘.
각 글 제목은 /blog/[slug] 링크로 연결해줘.
Tailwind로 깔끔하게 스타일링해줘.

개별 글 페이지를 요청한다.

app/blog/[slug]/page.tsx 를 만들어줘.
slug에 해당하는 .md 파일을 읽어 본문을 react-markdown으로 렌더링해줘.
generateStaticParams()도 구현해서 정적 생성을 활용해줘.

5. Vercel 배포

# Vercel CLI 설치 (처음 한 번만)
npm install -g vercel

# 배포
vercel deploy --prod

GitHub 저장소에 push 후 Vercel 대시보드에서 Import Project를 선택하는 방법도 동일하게 동작한다. 환경변수 설정이 없으므로 별도 설정 없이 배포가 완료된다.

결과

완성된 구조:

my-blog/
├── posts/
│   ├── hello-world.md
│   └── second-post.md
├── app/
│   ├── blog/
│   │   ├── page.tsx            ← 글 목록
│   │   └── [slug]/page.tsx     ← 개별 글
│   └── page.tsx                ← 홈
└── lib/posts.ts                ← 파일 읽기 유틸

새 글은 posts/ 폴더에 .md 파일을 추가하고 git push하면 Vercel이 자동으로 재빌드해 배포한다.

다음 단계

• seo — Next.js에서 메타 태그로 검색 최적화하는 방법
• rss — RSS 피드를 추가해 구독자를 모으는 방법
• nextjs — Next.js App Router 전체 구조 이해