Next.js 블로그에 Notion 연동하기

블로그를 운영하다 보면 글 작성을 더 편하게 하고 싶은 마음이 생깁니다. 기존에는 로컬에서 마크다운 파일을 작성하고 Git에 커밋하는 방식이었는데, Notion의 편리한 에디터를 활용하고 싶어졌습니다. 이번 글에서는 Next.js 블로그에 Notion을 연동하면서 겪은 문제들과 해결 방법을 공유합니다.

왜 Notion을 선택했나

기존 블로그는 MDX 파일을 data/blog/ 폴더에 저장하는 방식이었습니다. 이 방식의 장점은 명확하지만, 몇 가지 불편한 점이 있었습니다:

• 로컬 환경에서만 글을 작성할 수 있음
• 이미지 업로드가 번거로움
• 에디터 기능이 제한적
• 여러 기기에서 작업하기 어려움

Notion을 사용하면 이런 문제들을 해결할 수 있습니다. 특히 Notion의 강력한 에디터와 협업 기능은 블로그 운영을 훨씬 편하게 만들어줍니다.

구현 계획

Notion 연동을 위해 다음과 같은 기능이 필요했습니다:

1. Notion → MDX 동기화: Notion에서 작성한 글을 MDX 파일로 변환
2. MDX → Notion 업로드: 기존 MDX 파일을 Notion으로 업로드
3. 자동 빌드 통합: 빌드 시 자동으로 최신 글 동기화

Notion API 설정

먼저 Notion Integration을 생성하고 데이터베이스를 설정해야 합니다.

Integration 생성

1. Notion Integrations 페이지에서 새 Integration 생성
2. Internal Integration Token 복사
3. 데이터베이스에 Integration 연결

데이터베이스 속성 구성

블로그 포스트에 필요한 속성들을 데이터베이스에 추가했습니다:

• Title (Title): 포스트 제목
• Date (Date): 발행일
• Tags (Multi-select): 태그 목록
• Summary (Text): 요약
• Draft (Checkbox): 초안 여부
• Authors (Multi-select): 작성자

첫 번째 문제: databases.query가 없다?

Notion API 클라이언트를 사용해서 데이터베이스를 쿼리하려고 했는데, notion.databases.query() 메서드가 존재하지 않았습니다. 확인해보니 @notionhq/client 패키지의 databases 객체에는 retrieve, create, update 메서드만 있었습니다.

해결 방법

Notion API의 공식 엔드포인트는 존재하지만 클라이언트 라이브러리에 구현되어 있지 않았습니다. 직접 HTTP 요청을 보내는 방식으로 해결했습니다:

const queryResponse = await fetch(
  `https://api.notion.com/v1/databases/${NOTION_DATABASE_ID}/query`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${NOTION_TOKEN}`,
      'Notion-Version': '2022-06-28',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(queryOptions),
  }
)

이렇게 하면 데이터베이스에서 페이지를 쿼리할 수 있습니다.

두 번째 문제: properties가 undefined

데이터베이스를 조회했을 때 properties 필드가 undefined로 나오는 경우가 있었습니다. 이는 Integration이 데이터베이스에 제대로 연결되지 않았거나, 권한이 부족할 때 발생합니다.

해결 방법

properties가 없을 때도 동작하도록 예외 처리를 추가했습니다:

if (!database.properties) {
  console.warn('⚠️  데이터베이스 속성을 가져올 수 없습니다.')
  // 기본 속성만 사용하여 계속 진행
  availableProperties = ['Title', 'Date']
} else {
  availableProperties = Object.keys(database.properties)
}

이렇게 하면 Integration 연결이 완료되지 않아도 기본적인 동기화는 가능합니다.

세 번째 문제: 코드 블록 언어 형식

MDX 파일의 코드 블록을 Notion으로 변환할 때 언어 코드가 Notion이 지원하는 형식과 맞지 않았습니다. 예를 들어:

• js → javascript로 변환 필요
• ts:file.ts → 파일명 제거하고 typescript로 변환
• tex → latex로 변환
• 지원하지 않는 언어 → plain text로 폴백

해결 방법

언어 코드를 정규화하는 함수를 만들었습니다:

function normalizeLanguage(lang) {
  if (!lang) return 'plain text'

  // 파일명 형식 제거
  lang = lang.split(':')[0].split('.')[0].toLowerCase().trim()

  // 언어 매핑
  const languageMap = {
    'js': 'javascript',
    'ts': 'typescript',
    'py': 'python',
    'tex': 'latex',
    // ... 더 많은 매핑
  }

  const normalized = languageMap[lang] || lang

  // Notion이 지원하는 언어인지 확인
  const supportedLanguages = ['javascript', 'typescript', 'python', ...]

  return supportedLanguages.includes(normalized) ? normalized : 'plain text'
}

네 번째 문제: 블록 개수 제한

Notion API는 한 번에 최대 100개의 블록만 생성할 수 있습니다. 긴 글의 경우 이 제한을 초과할 수 있습니다.

해결 방법

블록을 100개씩 나눠서 처리했습니다:

const maxBlocksPerRequest = 100
const blockChunks = []
for (let i = 0; i < allBlocks.length; i += maxBlocksPerRequest) {
  blockChunks.push(allBlocks.slice(i, i + maxBlocksPerRequest))
}

// 첫 번째 청크는 페이지 생성 시
const response = await fetch(`https://api.notion.com/v1/pages`, {
  // ... 첫 번째 청크 포함
})

// 나머지 청크는 append_block_children API로 추가
for (let i = 1; i < blockChunks.length; i++) {
  await fetch(`https://api.notion.com/v1/blocks/${pageId}/children`, {
    method: 'PATCH',
    // ... 나머지 청크 추가
  })
}

다섯 번째 문제: 중복 업로드 방지

기존 MDX 파일을 Notion으로 업로드할 때, 같은 제목의 포스트가 이미 존재하면 중복으로 생성되는 문제가 있었습니다.

해결 방법

업로드 전에 기존 포스트의 제목을 미리 조회해서 중복을 체크했습니다:

// 기존 포스트 제목 목록 가져오기
const existingPagesResponse = await fetch(/* ... */)
const existingTitles = new Set()

for (const page of existingPages.results) {
  const title = page.properties?.Title?.title?.[0]?.plain_text || ''
  if (title) {
    existingTitles.add(title.toLowerCase().trim())
  }
}

// 업로드 전 중복 체크
if (existingTitles.has(titleKey)) {
  console.log(`⏭️  "${title}" 제목이 이미 존재하여 건너뜁니다.`)
  continue
}

최종 구현 결과

양방향 동기화가 완성되었습니다:

Notion → MDX (다운로드)

yarn sync-notion

Notion 데이터베이스에서 포스트를 가져와서 MDX 파일로 변환합니다. 빌드 시 자동으로 실행되도록 설정했습니다.

MDX → Notion (업로드)

yarn upload-to-notion

기존 MDX 파일을 Notion 데이터베이스로 업로드합니다. 중복 체크와 성공/실패 통계를 제공합니다.

사용 팁

1. Integration 연결 확인: 데이터베이스 속성을 제대로 가져오려면 Integration이 데이터베이스에 연결되어 있어야 합니다.

2. 속성명 일치: 스크립트에서 사용하는 속성명이 Notion 데이터베이스의 실제 속성명과 정확히 일치해야 합니다.

3. 블록 개수 제한: 매우 긴 글의 경우 여러 번의 API 호출이 필요하므로 시간이 걸릴 수 있습니다.

4. 에러 처리: 업로드 실패 시 상세한 에러 메시지를 확인하여 문제를 해결할 수 있습니다.

마무리

Notion을 블로그의 콘텐츠 소스로 사용하면서 글 작성이 훨씬 편해졌습니다. 특히 여러 기기에서 작업하거나 협업이 필요할 때 Notion의 장점이 빛을 발합니다.

물론 몇 가지 제약사항도 있었지만, 대부분은 API의 특성을 이해하고 적절히 우회하는 방법으로 해결할 수 있었습니다. Notion API가 계속 발전하고 있으니, 앞으로 더 많은 기능이 추가될 것으로 기대합니다.

이번 작업을 통해 배운 점은 API 문서만으로는 알 수 없는 실제 사용 시의 문제점들이 있다는 것입니다. 직접 구현해보면서 겪은 경험들이 이 글의 핵심 내용입니다.