Astro와 Notion을 활용한 블로그 시스템 구축하기 - Jeplin 블로그

Astro와 Notion을 활용한 블로그 시스템 구축기

정적 사이트 생성기(SSG)인 Astro와 생산성 툴인 Notion을 활용해 나만의 커스텀 블로그를 구축해보았습니다. 이 글에서는 구축 과정, 핵심 기능, 기술 선택 이유, 실전 코드 예제까지 소개합니다.

왜 Astro + Notion인가?

Astro의 장점

빠른 빌드 속도와 최적화된 번들링
React, Vue, Svelte 등 다양한 프레임워크와 통합 가능
HTML 중심 구조 → SEO에 유리

Notion의 장점

직관적인 마크다운 기반 에디터
협업 및 데이터 관리 용이
API를 통한 콘텐츠 자동 연동 가능

이 둘을 조합하면 노션에서 글만 작성하면, 자동으로 Astro 기반 블로그에 반영되는 시스템을 구축할 수 있습니다.

시스템 구조 개요

시스템 흐름:
[Notion] → [Notion API + SDK] → [Astro 프로젝트] → [정적 사이트]

Notion에 글 작성
Astro에서 API를 통해 콘텐츠 가져오기
Markdown 또는 HTML로 변환해 렌더링
astro build 후 정적 페이지 배포

사용 기술 스택

구현 단계

✅ 1) Notion API 연동

npm install @notionhq/client notion-to-md

기본 구조:

// lib/notion.ts
import { Client } from '@notionhq/client';
import { NotionToMarkdown } from 'notion-to-md';

const notion = new Client({ auth: process.env.NOTION_API_KEY });
const n2m = new NotionToMarkdown({ notionClient: notion });

export const fetchPosts = async () => {
  const dbId = process.env.NOTION_DATABASE_ID;
  const response = await notion.databases.query({ database_id: dbId });

  const posts = await Promise.all(response.results.map(async (page) => {
    const mdBlocks = await n2m.pageToMarkdown(page.id);
    const mdString = n2m.toMarkdownString(mdBlocks);
    return {
      title: page.properties.Name.title[0].plain_text,
      content: mdString,
      slug: page.properties.slug.rich_text[0].plain_text,
    };
  }));

  return posts;
};

✅ 2) Astro에 마크다운 콘텐츠 렌더링

// src/pages/blog/[slug].astro
import { fetchPosts } from '@/lib/notion';
const posts = await fetchPosts();
const post = posts.find((p) => p.slug === Astro.params.slug);

<html>
<head><title>{post.title}</title></head>
	<body>
		<article>
			<h1>{post.title}</h1>
			<Markdown content={post.content} />
		</article>
	</body>
</html>

✅ 3) 환경 변수 설정

NOTION_API_KEY=your-secret-api-key NOTION_DATABASE_ID=your-database-id

주의: Notion API 키가 접근하려는 데이터베이스와 공유되어 있어야 합니다.
Notion 페이지 오른쪽 상단 → "공유" → "통합 추가"에서 연동하세요.

배포 및 결과

Vercel 또는 Netlify로 정적 배포
astro build → astro preview로 확인
Notion에서 글만 쓰면 블로그에 자동 반영됨

느낀 점

Astro와 Notion을 결합한 시스템은 블로그뿐만 아니라 문서 사이트, 포트폴리오, 위키에도 유용합니다.
Notion의 쉬운 콘텐츠 작성과 Astro의 빠른 빌드 성능이 잘 어우러졌습니다.

다음 단계

태그별 필터링 기능 추가
검색 기능 (Algolia 예정)
다국어 블로그 지원 (예: 영문/한글 동시)

마치며

Astro + Notion 조합은 간단하고 빠르게 콘텐츠 기반 웹사이트를 만들 수 있는 훌륭한 선택입니다.
CMS를 직접 관리하지 않고도 자동화된 퍼블리싱이 가능한 이 구조는, 특히 개발자 블로그를 시작하려는 분들에게 적극 추천드립니다.

💬 더 자세한 구축 과정이나 템플릿이 필요하신 분은 Jeplin에 문의 주세요!

더 많은 기술 인사이트가 필요하신가요?