Notion Blog Project

한국어 · English

• ✏️ Notion으로 포스트 작성
• ⚙️ 코드 수정 없이 다양한 사이트 옵션 설정
• 🎨 vanilla-extract 기반 테마 커스터마이징
• 📊 Google Analytics 지원
• 🤖 Sentry 지원

🚀 시작하기

이 저장소를 fork해서 작업 공간에 clone합니다.

Notion 템플릿을 자기 워크스페이스로 복제합니다.

자기 페이지의 NOTION_BLOG_PAGE_ID와 NOTION_VIEW_ID를 확인합니다.

Vercel Environment Variables에 위 값들을 입력합니다.

Sentry로 에러를 추적하려면 다음 4개 env를 모두 설정해야 합니다.

• SENTRY_ORG
• SENTRY_PROJECT
• SENTRY_AUTH_TOKEN
• SENTRY_DSN

4개가 모두 있어야 Sentry.init()이 활성화됩니다.

Vercel에 배포하면 끝입니다.

💻 개발

cp .env.example .env

로컬 개발은 .env.example을 .env로 복사한 뒤 다음을 실행합니다.

yarn && yarn dev
# 또는
npm install && npm dev

🎨 커스터마이징

import type { Config } from "@/types";

const CONFIG: Config = {
  profile: {
    // 댓글(utterances) 연동용 owner/repo. 미설정 시 댓글 비활성
    repo: "im-ian/notion-blog",
    github: "im-ian",
  },
  // ...
};

site.config.ts에서 다음 그룹을 조정할 수 있습니다 (자세한 옵션은 아래 표 참고).

• profile
• notion
• meta (SEO)
• site
• theme
• search
• posts
• comments
• rss
• footer

profile

키	타입	설명
name	string	표시 이름
profileImage	string | undefined	아바타 URL
bio	string | undefined	한 줄 소개
repo	string | undefined	utterances 연동용 GitHub 레포 (owner/repo). 미설정 시 댓글 비활성
github	string | undefined	GitHub username
linkedin	string | undefined	LinkedIn URL
instagram	string | undefined	Instagram URL
twitter	string | undefined	Twitter/X URL
threads	string | undefined	Threads URL

notion

키	타입	설명
blogPageId	string	Notion DB 페이지 ID. NOTION_BLOG_PAGE_ID env로 주입
viewId	string	Notion view ID. NOTION_VIEW_ID env로 주입. URL의 ?v=... 부분
useViewIdFilter	boolean	true로 두면 Notion view의 필터/정렬을 그대로 사용. 코드 측 posts.useScheduled 및 status==Public 필터는 비활성 (view에 위임). 기본 false

useViewIdFilter 동작

값	동작
false (기본)	모든 포스트를 가져온 뒤 코드의 posts.useScheduled, status==Public 등으로 필터
true	Notion에서 만든 view의 결과만 사용. 정렬·필터·hidden 컬럼 모두 view에 따름. viewId가 잘못되면 자동으로 기본 동작으로 fallback (콘솔 경고 출력)

view를 직접 만들고 싶다면:

1. Notion에서 블로그 DB 우상단 + → 새 view 추가 (필터/정렬 자유 설정)
2. 해당 view를 연 상태에서 URL의 ?v=<viewId> 부분 복사
3. NOTION_VIEW_ID env에 저장
4. notion.useViewIdFilter를 true로 토글

meta

Next.js Metadata를 그대로 받으며 다음 키가 추가됩니다.

키	타입	설명
siteUrl	string | undefined	카논컬 도메인. sitemap, RSS, layout metadataBase에 사용. 미설정 시 process.env.SITE_URL fallback (production에선 둘 중 하나 필수)
ogImage	string | undefined	기본 OG 이미지. 포스트 썸네일이 없을 때 fallback으로도 사용

site

키	타입	기본값	설명
lang	string	"ko"	<html lang> 값
title	string	—	사이트 타이틀, 헤더에 표시
stickyProfile	boolean	false	데스크탑 좌측 프로필 섹션 스크롤 추종

theme

키	타입	기본값	설명
mode	"auto" | "light" | "dark"	"auto"	첫 방문 기본 테마. auto는 OS 설정 추종. 사용자가 토글로 바꾸면 localStorage가 우선
showToggle	boolean	true	헤더의 다크모드 토글 버튼 노출. mode를 강제하고 싶을 때 false

search

키	타입	기본값	설명
shortcut	boolean	true	검색 단축키(⌘/Ctrl+K) 활성화
scope	"title" | "title+summary" | "all"	"all"	검색 매칭 범위. all은 title + summary + tags
showInHeader	boolean	true	헤더 검색 아이콘 노출 (단축키만 쓰고 싶다면 false)

posts

키	타입	기본값	설명
perPage	number	10	페이지당 포스트 개수 (1 미만이면 1로 보정)
paginationMode	"infinite" | "numbered"	"infinite"	infinite는 인피니티 스크롤(뒤로가기 시 노출 개수·스크롤 위치 복원). numbered는 숫자 페이지 + Prev/Next 버튼, URL은 ?page=N
useScheduled	boolean	true	true일 때 Public 포스트가 작성일을 넘어야 리스트에 노출 (예약 게시)
showSummary	boolean	true	포스트 카드의 summary 노출
showPrevNext	boolean	true	포스트 페이지 하단 인접(이전/다음) 포스트 네비게이션
dateFormat	string	"YYYY년 MM월 DD일"	dayjs 토큰 (예: "YYYY-MM-DD", "YYYY/MM/DD HH:mm")
showScrollProgress	boolean	true	포스트 페이지 상단 스크롤 진행바

comments

키	타입	기본값	설명
use	boolean	true	utterances 댓글 영역 노출 (profile.repo 필수)

rss

키	타입	기본값	설명
use	boolean	true	/rss.xml 활성화. meta.siteUrl (또는 SITE_URL env) 필요. false면 404

footer

키	타입	기본값	설명
show	boolean	true	사이트 전역 footer 영역 노출
text	string	"© ..."	표시할 텍스트

export const vars = createGlobalTheme(":root", {
  // ...
  color: {
    white: "#fff",
    black: "#333",
    darkgray: "#2f3437",

    "gray-50": "#f9fafb",
    "gray-100": "#f3f4f6",
    "gray-200": "#e5e7eb",
    "gray-300": "#d1d5db",
    "gray-400": "#9ca3af",
    "gray-500": "#6b7280",
    "gray-600": "#4b5563",
    "gray-700": "#374151",
    // ...
  },
});

색상이나 사이즈를 바꾸려면 sprinkles.css.ts 또는 vars.css.ts를 수정하세요.

📄 라이선스

MIT 라이선스 하에 공개되었습니다. 자유롭게 fork해서 자기 블로그로 사용 가능합니다.