TL;DR

  • Publish from Notion은 공식 Notion API를 사용해 데이터베이스를 공개하지 않고도 Notion 콘텐츠를 기존 사이트의 디자인·URL·호스팅을 유지한 채 게시하는 키트임.
  • Git과 Node.js 22.18 이상으로 로컬 데모를 실행할 수 있으며, 데모 단계에는 Notion 계정이나 토큰이 필요하지 않음.
  • 연결 웹훅(connection webhook)이 페이지 수정 이벤트를 전달하고 캐시를 무효화해, 재빌드 없이 다음 요청에서 변경 내용을 반영함.
  • 기사 메타데이터와 구조화 데이터 외에도 사이트맵, RSS, llms.txt 텍스트 색인을 생성하며 업로드 이미지는 자체 도메인의 서명된 경로로 제공함.
  • 공개 블로그용 자체 호스팅 키트로, 접근 제어 문서 포털이 아니며 검색·댓글·관리자 대시보드와 고정된 웹훅 전달 시간은 제공하지 않음.

Notion에서 게시

  • Notion에서 작성하고 편집하면서 사이트 디자인, URL, 호스팅은 그대로 유지하는 구성임.
  • 공식 Notion API로 사이트와 데이터베이스를 연결하며, 데이터베이스를 공개 상태로 만들 필요가 없음.
  • 데모 녹화는 Notion 무료 플랜에서 연결 웹훅을 사용해 39초 동안 진행되며, GIF에서는 대기 시간이 빠르게 재생되고 실제 전달 시간은 달라질 수 있음.
  • ‘Every block’ 데모에서 제목, 목록, 표, 토글, 이미지를 포함한 문서를 확인할 수 있으며, 자신의 데이터베이스를 연결해 게시를 시험할 수 있음.

시작하기

  • Git과 Node.js 22.18 이상이 필요하며, 먼저 로컬 데모를 실행하는 단계에는 Notion 계정이나 토큰이 필요하지 않음.
  • 저장소를 복제하고 프로젝트 디렉터리에서 의존성을 설치한 뒤 개발 서버를 실행하는 절차임: https://github.com/loriscomba97/publish-from-notion.git 저장소를 복제하고 npm ci, npm run dev를 실행함.
  • localhost:3000을 열어 ‘All posts’를 선택하고 문서를 열면, 지원 블록을 보여주는 페이지를 포함한 내장 샘플 콘텐츠를 확인할 수 있음.

Notion 연결

  • Name(제목), Slug(텍스트), Published(체크박스) 속성을 포함한 데이터베이스를 만들고, Notion에서 읽기 전용 내부 연결을 생성해 해당 데이터베이스에 접근 권한을 부여함.
  • .env.example을 .env.local로 복사하고 NOTION_TOKEN과 NOTION_DATA_SOURCE를 입력하며, 개발 중에는 로컬 SITE_URL을 유지한 뒤 서버를 다시 시작함.
  • 제목과 hello-from-notion 같은 슬러그, 텍스트를 포함한 페이지를 만들고 Published를 선택하면 사이트의 /blog/hello-from-notion 경로에서 확인할 수 있음.
  • 설정 가이드에는 각 필드와 권한, 선택 사항인 데이터베이스 설정 명령이 설명되어 있으며, 배포 시 비밀 정보를 둘 위치도 안내함.

기능

  • Notion을 편집기로 사용하며, 웹사이트가 게시된 행을 선택해 블록을 HTML로 렌더링함. 데이터베이스는 비공개로 유지할 수 있고 API 토큰은 서버에 보관됨.
  • 재빌드 없이 업데이트함. 서명된 연결 웹훅이 페이지 편집을 웹사이트에 알리고, 수신 경로가 캐시 데이터를 무효화해 이후 요청에서 변경 내용을 렌더링함.
  • 완전한 블로그 구성을 제공함. 문서 페이지에는 메타데이터와 구조화 데이터가 포함되며, 템플릿은 사이트맵, RSS, llms.txt 텍스트 색인을 생성함. 업로드 이미지는 자체 도메인의 서명된 경로로 제공됨.

즉시 게시

  • 개발 중 시험한 무료 Notion 플랜에서도 연결 웹훅을 사용할 수 있으며, 텍스트 편집을 포함한 이벤트는 비동기 방식으로 전달됨.
  • 유료 플랜에서는 데이터베이스 자동화도 사용할 수 있음. 어느 경로도 고정된 전달 시간을 보장하지 않음.
  • 게시 가이드에서 한 가지 경로를 설정하고 확인할 수 있음. 웹훅을 사용하지 않으면 1시간 캐시 간격에 따라 이후 요청에서 새로고침되며, 매시간 실행되는 백그라운드 작업은 아님.

작동 방식

  • TypeScript 코어가 공식 API에서 데이터를 읽어 블록을 HTML로 변환하고, Next.js가 해당 데이터를 캐시함.
  • 페이지 이벤트는 게시물 목록과 변경된 페이지의 캐시를 무효화하며, 더 넓은 범위의 데이터베이스 이벤트는 더 많은 데이터를 무효화할 수 있음.
  • 코어에는 런타임 의존성이 없음. 포함된 템플릿은 Next.js와 React에 의존함.

기존 Next.js 사이트에 추가

  • 통합 가이드에 따라 코어, 설정, 컴포넌트, 경로를 App Router 프로젝트에 복사하는 방식임.
  • 바로 실행 가능한 템플릿의 대상은 Next.js 16이며, 이전 버전은 조정이 필요함.

제공하지 않는 기능

  • 접근 제어 문서 포털이 아닌 자체 호스팅 공개 블로그임. 게시를 취소해도 다운로드된 콘텐츠나 캐시된 이미지를 지울 수 없음.
  • Notion 호스팅 동영상, 오디오, PDF는 렌더링되지 않으며, 수식은 원본 텍스트로 표시됨. 콘텐츠를 이전하기 전에 렌더링 제한을 확인해야 함.
  • 호스팅과 Notion은 외부 서비스로 유지됨. 검색 순위 보장은 없으며 댓글, 검색, 관리자 대시보드는 제공하지 않음.

기여 및 라이선스

  • 재현 가능한 예시가 포함된 버그 보고가 유용함. CONTRIBUTING.md에는 개발 및 테스트가 설명되어 있으며, 보안 문제는 SECURITY.md를 통해 보고할 수 있음.
  • MIT 라이선스, © 2026 Loris Comba. Notion Labs, Inc.와 제휴 관계가 아님.