Next.js 블로그 구축한 과정 정리

왜 이 글을 쓰는가

이 글은 "결과 화면"보다 "어떻게 만들었는지"를 남기기 위한 기록이다.

나중에 블로그를 다시 손볼 때 가장 자주 헷갈리는 지점은 보통 세 가지다.

그래서 실제로 구축하면서 했던 선택과 이유를 순서대로 정리했다.

먼저 App Router 기준으로 Next.js 프로젝트를 구성하고, UI 일관성을 위해 Tailwind를 붙였다.

핵심 포인트는 "정적 사이트로 배포 가능해야 한다"는 점이었다. 그래서 Next 설정을 아래처럼 정적 export 중심으로 맞췄다.

// next.config.mjs
const nextConfig = {
  output: 'export',
  trailingSlash: true,
  images: { unoptimized: true }
};

이렇게 해두면 npm run build 시 out/ 폴더를 기준으로 GitHub Pages에 바로 올릴 수 있다.

글은 DB가 아니라 파일로 관리하도록 결정했다. 이유는 단순하다.

콘텐츠 위치는 content/articles/*.mdx로 통일했고, app/lib/articles.ts에서 frontmatter 파싱, 정렬, slug 처리, 목차 추출을 담당하게 분리했다.

frontmatter는 아래 필드를 기본 규약으로 잡았다.

구성은 단순하게 세 축으로 나눴다.

이 구조를 먼저 고정해두니, 콘텐츠가 늘어나도 라우팅 규칙을 건드릴 일이 거의 없었다.

공통 프레임은 SiteHeader, SiteFooter, ArticleLayout로 분리했다. 색상 토큰은 app/globals.css에 CSS 변수로 정의해 라이트/다크를 한 곳에서 제어했다.

예를 들어 본문 텍스트는 직접 색 코드를 박기보다 아래 토큰을 사용한다.

이 방식의 장점은 "화면 전체 톤을 바꿀 때 변경 지점이 적다"는 것이다.

다크모드 토글 자체는 어렵지 않았다. html.dark 클래스를 기준으로 스위칭하면 된다.

문제는 Typography 플러그인(prose)이었다. prose-invert를 항상 적용하면 라이트 모드에서도 본문이 밝게 렌더링되어 가독성이 깨질 수 있다.

실제 수정은 아래처럼 했다.

<article className="prose max-w-none dark:prose-invert ...">
  {children}
</article>

핵심은 "반전은 다크일 때만" 적용하는 것이다.

반복 입력을 줄이기 위해 scripts/create-post.mjs를 추가했다.

npm run new:post -- --title "My New Post"

이 스크립트가 파일명(slug), 날짜, 기본 frontmatter를 잡아주기 때문에, 실제로는 본문 작성에만 집중할 수 있다.

배포는 .github/workflows/deploy.yml로 자동화했다. main에 push 하면 build -> artifact upload -> deploy 순서로 진행된다.

여기서 중요한 포인트는 basePath 자동 처리다.

이 설정을 next.config.mjs에서 조건 분기해두면, 로컬과 배포 환경 차이 때문에 링크가 깨지는 문제를 줄일 수 있다.

이번 구축에서 가장 크게 느낀 건 "처음에 규칙을 조금만 명확히 잡아도 이후 유지보수 비용이 크게 줄어든다"는 점이다.

특히 아래 세 가지는 계속 유지할 계획이다.

다음 개선 후보는 코드 블록 스타일 커스터마이징과 아티클 메타(태그/시리즈) 확장이다.