Obsidian + Tailwind Nextjs Starter Blog로 개발 블로그 빠르게 만들기

개발자 블로그를 만들기로 마음먹으면 흔히 두 가지 함정에 빠진다. 플랫폼(Velog, Tistory)에 올리면 내 통제권이 없고, 직접 만들면 기능 개발에 시간을 다 써서 정작 글은 못 쓴다. 이 글은 그 사이를 빠르게 가로지른 기록이다 — 검증된 템플릿을 고르고, Obsidian 글쓰기 흐름을 연결하고, AI로 글쓰기 환경까지 세팅하는 과정.

처음부터 만들지 않는다 — Tailwind Nextjs Starter Blog

처음에는 Next.js로 직접 만들까 Astro를 쓸까 고민했다. Astro는 정적 사이트에 특화되어 퍼포먼스가 좋고, Next.js는 이미 익숙하고 확장성이 좋다. 고민 끝에 Next.js를 선택했지만, 더 중요한 결정은 그다음이었다.

처음부터 만들지 않기로 했다.

Tailwind Nextjs Starter Blog는 블로그에 필요한 것들이 이미 다 들어 있다.

SEO, OG 태그, sitemap.xml 자동 생성
코드 하이라이팅, 수식 렌더링, 다크 모드
태그 필터, 다중 레이아웃, RSS
Contentlayer 기반 마크다운 파싱

직접 구현하면 몇 주 걸릴 것들이다. 이걸 직접 만드는 건 블로그를 만드는 게 아니라 블로그 엔진을 만드는 것이다. 목표는 글을 쓰는 것이었으니, 기능은 가져다 쓰고 내 글쓰기 방식만 연결하는 데 집중했다.

Obsidian 폴더를 심볼릭 링크로 연결하기

이미 Obsidian으로 글을 쓰고 있다면 CMS를 따로 세팅할 필요가 없다. 심볼릭 링크 하나로 Obsidian 볼트의 글 폴더를 블로그의 데이터 소스로 연결하면 된다.

# 블로그 레포 루트에서
ln -s ~/obsidian-vault/posts ./data/blog

이렇게 하면 Obsidian에서 평소처럼 글을 쓰고, 블로그는 data/blog/**/*.md를 읽기만 한다. Next.js와 Contentlayer 입장에서는 그냥 로컬 파일을 읽는 것이고, 실제 편집은 Obsidian에서 이루어진다.

글쓰는 곳과 보여주는 곳이 분리되는 구조다. 이 분리가 핵심이다.

Contentlayer 설정을 Obsidian 스타일에 맞추기

이 템플릿은 기본적으로 MDX(.mdx)를 전제로 한다. Obsidian 글은 순수 마크다운(.md)에 가깝기 때문에 파일 패턴 하나만 바꿔준다.

// contentlayer.config.ts
export const Blog = defineDocumentType(() => ({
  name: 'Blog',
  filePathPattern: 'blog/**/*.md', // .mdx → .md
  // 나머지 필드는 그대로
}))

frontmatter 구조도 템플릿 기본값을 그대로 쓴다. Obsidian에서 글을 쓸 때 아래 형식을 맞춰주면 된다.

---
title: 글 제목
date: 2026-02-27
lastmod: 2026-02-27
tags:
  - nextjs
  - obsidian
draft: true
summary: 글 목록과 SEO에 표시될 요약 (1~2문장)
images: []
authors:
  - default
---

draft: true인 글은 빌드에서 제외된다. Obsidian에서 작성 중인 글은 이 상태로 두고, 올릴 준비가 됐을 때 false로 바꾸면 된다.

배포는 GitHub Pages + 전용 스크립트로

템플릿 기본값은 Vercel이지만, GitHub Pages + 정적 빌드로도 잘 동작한다. 매번 Vercel 대시보드를 열 필요 없이, 로컬에서 직접 빌드해서 올리는 흐름이 더 단순하다.

scripts/deploy-gh-pages.sh 스크립트 하나로 세 단계를 처리한다.

#!/bin/bash

# 1. 브랜치 확인 (main이 아니면 경고)
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" != "main" ]; then
  echo "⚠️  현재 브랜치: $CURRENT_BRANCH (main이 아님)"
  read -p "계속 진행하시겠습니까? (y/N): " confirm
  [[ "$confirm" != "y" ]] && exit 1
fi

# 2. GitHub Pages용 정적 빌드
EXPORT=1 UNOPTIMIZED=1 npm run build

# 3. gh-pages 브랜치로 배포
npx gh-pages -d out --dotfiles

실행은 한 줄이다.

./scripts/deploy-gh-pages.sh

빌드 → gh-pages 브랜치로 푸시 → GitHub Pages가 정적 파일 서빙. CI 설정 없이도 이 흐름으로 충분하다.

글쓰기 환경도 세팅한다 — Claude Skills로 블로그 글쓰기 룰 만들기

블로그를 잘 만드는 것과 글을 잘 쓰는 것은 다른 문제다. 기술적으로 완성된 블로그도 글을 못 쓰면 의미가 없다.

개발자 독자는 바쁘다. 글을 열었을 때 처음 몇 문장에서 "이게 나한테 필요한 글인지" 판단하고, 아니면 탭을 닫는다. 독자는 두 가지를 확인한다.

이 글은 나 같은 사람을 위한 글인가?
이 글을 읽으면 무엇을 얻는가?

이 답이 제목과 첫 3문장 안에 없으면 이탈이다.

이 원칙을 글 쓸 때마다 의식하기 위해, Claude Skills로 블로그 글쓰기 룰을 별도 파일로 만들었다. .claude/skills/blog-writing/SKILL.md에 제목 작성법, 도입부 원칙, 섹션 구성법, 발행 전 체크리스트를 정리해 두었다.

.claude/
└── skills/
    └── blog-writing/
        └── SKILL.md   ← 글쓰기 원칙 + 체크리스트
_templates/
└── blog_template.md   ← 새 글 시작할 때 복사하는 템플릿

새 글을 쓸 때는 템플릿을 복사해서 시작하고, Claude에게 초안 작성을 요청하면 이 스킬을 참고해서 원칙에 맞는 글을 써준다. 글쓰기 룰을 머릿속에만 두지 않고 파일로 관리하는 것이다.

정리: 세팅보다 빠르게, 글쓰기에 더 집중하기

결국 이 세팅의 핵심은 마찰을 줄이는 것이다.

Tailwind Nextjs Starter Blog: 기능 개발 시간을 아낀다
심볼릭 링크: Obsidian에서 쓴 글이 그대로 블로그로 간다
배포 스크립트: 명령어 한 줄로 올린다
Claude Skills: 글쓰기 원칙을 매번 떠올리지 않아도 된다

각각은 작은 선택이지만, 합쳐지면 "글을 쓰고 싶을 때 바로 쓸 수 있는" 환경이 된다. 앞으로는 이 구조 위에 태그 전략, 검색, 댓글 같은 것들을 천천히 쌓아갈 계획이다.