📝 [웹사이트 제작 3편] 노션(Notion)을 웹사이트 데이터베이스(CMS)로 쓰는 법

🤔 MySQL, 백엔드? 비개발자는 그런 거 모릅니다

📌 한 줄 요약: 별도의 데이터베이스 서버를 구축하지 않고, 노션(Notion)을 웹사이트의 콘텐츠 관리 시스템(CMS)으로 활용하는 방법을 알아본다.

2편에서는 오픈소스 템플릿과 AI 바이브코딩을 활용해 웹사이트의 기본 뼈대를 만들었다. 그런데 여기서 한 가지 문제가 생긴다.

"그럼 웹사이트에 들어갈 글은 어디에서 작성하지?"

웹사이트의 모든 글을 HTML 파일에 직접 작성하는 방법도 있지만, 글 하나를 수정할 때마다 코드를 열어 직접 수정해야 한다면 콘텐츠를 꾸준히 발행하기가 어렵다.

일반적인 웹서비스라면 MySQL 같은 데이터베이스를 구축하고 관리자 페이지를 만들어 콘텐츠를 관리할 수도 있다. 하지만 콘텐츠 중심의 블로그를 만들기 위해 굳이 복잡한 데이터베이스 서버와 관리자 페이지까지 직접 구축할 필요가 있을까?

그래서 Pixoas에서는 노션(Notion)을 콘텐츠 관리 시스템(CMS)처럼 활용하는 방법을 선택했다. 평소 글을 작성하듯 노션에서 콘텐츠를 관리하고, 필요한 시점에 Notion API를 통해 웹사이트에 데이터를 전달하는 방식이다.

즉, 노션 = 콘텐츠를 작성하고 관리하는 공간, 웹사이트 = 방문자에게 콘텐츠를 보여주는 공간으로 역할을 분리하는 것이다.

이번 편에서는 이 구조가 어떻게 작동하는지 살펴보고, 노션을 웹사이트와 연결하기 위해 필요한 기본 준비 과정까지 알아보자.

💡 노션 데이터베이스를 CMS처럼 사용하는 이유

📌 한 줄 요약: Notion에서 콘텐츠를 관리하고 웹사이트에서는 그 데이터를 가져와 보여주는 방식으로 콘텐츠 관리와 화면 구성을 분리할 수 있다.

처음 웹사이트를 만들 때는 데이터베이스를 직접 구축해야 하나 고민했다.

하지만 내가 만들고 싶은 것은 복잡한 웹서비스가 아니라 글을 작성하고 방문자에게 보여주는 콘텐츠 중심의 블로그였다. 그렇다면 이미 익숙한 도구를 활용하는 편이 훨씬 간단하다.

노션의 데이터베이스는 제목, 작성일, 카테고리, 태그, 상태 등의 속성을 이용해 콘텐츠를 체계적으로 관리할 수 있다.

그리고 Notion API를 이용하면 외부 프로그램에서 이러한 콘텐츠를 읽어올 수 있다. 이렇게 가져온 데이터를 우리가 2편에서 만든 웹사이트에 연결하면 된다.

쉽게 표현하면 다음과 같은 구조다.

• Notion: 콘텐츠 작성 및 관리 (원본 저장소)
• GitHub Actions: 노션 데이터 가져오기 및 웹사이트 빌드 (작업자)
• Cloudflare Pages: 생성된 정적 파일 배포 (방문자에게 보여주는 공간)

여기서 중요한 것은 방문자가 노션에 직접 접속하는 것이 아니라는 점이다. 콘텐츠를 작성하는 사람은 노션을 사용하고, 방문자는 쾌적하게 렌더링된 Pixoas 웹사이트를 이용하게 된다.

📊 Notion은 '헤드리스 CMS'처럼 사용할 수 있다

📌 한 줄 요약: 콘텐츠를 관리하는 Notion과 방문자에게 보여주는 웹사이트를 분리하면 각각의 역할을 독립적으로 관리할 수 있다.

이런 구조를 흔히 헤드리스 CMS(Headless CMS)라는 개념으로 설명할 수 있다. 쉽게 말하면 콘텐츠를 관리하는 부분(머리)과 콘텐츠를 보여주는 화면(몸통)을 분리하는 방식이다.

일반적인 CMS에서는 관리자 페이지와 웹사이트가 하나의 시스템 안에서 함께 동작하는 경우가 많다. 반면 지금 우리가 만드는 구조에서는 역할이 나뉜다.

즉, 콘텐츠와 웹사이트를 분리해 관리하는 것이다.

나는 웹사이트의 모든 글을 직접 HTML로 작성하지 않는다.

Notion에서 글을 작성하고 → 필요한 데이터를 가져오고 → 웹사이트를 다시 빌드한 뒤 → 완성된 페이지를 배포한다.

이렇게 만들어두면 이후에는 새로운 글을 작성할 때마다 웹사이트 코드를 직접 수정할 필요가 없다.

🔑 Notion API 연동에 필요한 핵심 정보

📌 한 줄 요약: 노션과 외부 프로그램을 연결하려면 'API 인증 토큰'과 연결할 '데이터베이스 ID' 두 가지 정보를 정확하게 준비해야 한다.

그렇다면 GitHub Actions 같은 외부 환경에서는 어떻게 Notion의 글을 가져올 수 있을까?

핵심은 Notion API를 이용하는 것이다.

이를 위해서는 크게 두 가지를 준비해야 한다.

1. Notion Integration 인증 정보
2. 연결할 Database ID

여기서 초보자가 가장 많이 헷갈리는 부분이 바로 인증 토큰(API 키)이다.

이 토큰은 웹사이트 코드에 일반 텍스트로 공개해서는 절대 안 된다. GitHub Actions에서 사용할 때는 GitHub Secrets와 같은 안전한 환경변수 저장소에 넣어 사용하는 것이 좋다.

🔐 ① Notion Integration (인증 토큰) 만들기

Notion API를 사용하려면 먼저 노션 개발자 페이지에서 Integration을 만들어야 한다. 이는 쉽게 말해 "외부 프로그램이 내 Notion 콘텐츠에 접근할 수 있도록 허용하는 연결 통로"라고 생각하면 된다.

Integration을 만든 뒤 발급되는 '시크릿 토큰'을 나중에 깃허브 액션에서 사용하게 된다.

거듭 강조하지만, 이 토큰을 공개된 인터넷 게시판이나 깃허브 코드상에 'NOTION_TOKEN=실제_토큰값'처럼 날것으로 노출해서는 안 된다.

⚠️ 중요: Notion 인증 토큰은 비밀번호와 비슷하게 취급해야 한다. 다른 사람에게 공유하거나 공개 저장소에 올리지 않도록 주의하자.

🗂️ ② 연결할 데이터베이스(Database ID) 준비하기

다음으로 웹사이트에서 사용할 콘텐츠를 관리할 Notion 데이터베이스(표)를 준비한다. 처음부터 복잡한 속성을 만들 필요는 없으며, 아래와 같은 구성으로 시작해도 충분하다.

• 제목: 게시글 제목
• 작성일: 게시 날짜 (Date)
• 카테고리: 콘텐츠 분류 (Select)
• 태그: 관련 키워드 (Multi-select)
• 상태: 발행 여부 관리 (Checkbox 또는 Status)

이 데이터베이스 페이지를 전체 화면으로 연 뒤, 웹 브라우저 상단의 주소창(URL)을 확인해 보자. 주소는 대략 아래와 같은 형태를 띤다.

'https://www.notion.so/워크스페이스이름/1234567890abcdef1234567890abcdef?v=어쩌고저쩌고'

여기서 우리가 찾아야 할 **'Database ID'**는 워크스페이스 이름 슬래시(/) 뒤부터 물음표(?v=) 앞까지 이어지는 32자리의 영문과 숫자 조합이다.

위 예시에서는 굵게 표시된 '1234567890abcdef1234567890abcdef' 부분만 복사하면 된다.

이 ID를 통해 템플릿은 수많은 문서 중에서 딱 이 표에 있는 글만 정확히 타겟으로 인식하게 된다.

⚠️ 가장 많이 발생하는 오류: 권한 부여 잊지 않기

📌 한 줄 요약: Integration을 만들고 토큰을 발급하는 것으로 끝나는 것이 아니라, 실제로 사용할 노션 데이터베이스 페이지에서 권한을 직접 부여해야 한다.

처음 설정할 때 API도 만들었고 토큰도 제대로 넣었는데 데이터를 가져오지 못하는 오류(403 에러)를 겪는 경우가 많다.

이유는 간단하다. Integration을 만들었다고 해서 자동으로 내 모든 노션 페이지를 읽을 수 있는 것은 아니기 때문이다.

반드시 글을 모아둔 노션 데이터베이스 페이지로 들어가서, 권한 부여를 해야 한다.

우측 상단의 점 3개(···) 메뉴를 눌러 '연결(Connections)' 또는 '연결 추가' 메뉴를 찾은 뒤, 앞서 1번 단계에서 내가 만든 Integration의 이름을 검색해 추가해 주어야 한다.

이 작업을 거쳐야만 비로소 외부 시스템이 해당 노션 데이터베이스의 내용을 합법적으로 읽어갈 수 있다.

(💡 3편에서는 이 개념만 확실히 이해하고 넘어가면 된다. 실제 토큰과 ID를 어디서 확인하고 깃허브에 어떻게 입력하는지는 5편에서 단계별로 따라 하게 될 것이다.)

🚀 실전 꿀팁: '상태' 속성으로 발행 여부 관리하기

📌 한 줄 요약: Notion 데이터베이스에 발행 상태를 관리하는 속성을 만들어 원하는 콘텐츠만 웹사이트에 반영할 수 있다.

블로그를 운영하다 보면 작성 중인 글을 웹사이트에 바로 공개하고 싶지 않은 경우가 많다.

예를 들어,

• 작성 중인 글
• 검수 중인 글
• 발행 준비가 끝난 글

을 모두 같은 데이터베이스에서 관리할 수 있다.

그래서 나는 Notion 데이터베이스에 상태(Status) 또는 체크박스(Checkbox) 속성을 만들어 발행 여부를 관리하는 방식을 추천한다.

예를 들어,

이렇게 만들어두면 나중에 자동화 로직에서 “발행 상태인 콘텐츠만 가져오기”와 같은 조건을 적용할 수 있다.

다만 실제로 어떤 속성명을 사용하고 어떤 값을 기준으로 발행할지는 5편에서 GitHub Actions 자동화 설정을 다룰 때 구체적으로 설정할 예정이다.

🙋‍♂️ 데이터베이스 셋업, 궁금했던 점 (Q&A)

(👉 질문을 클릭하면 자세한 답변이 펼쳐집니다)

📚 웹사이트 제작 9부작 시리즈 전체 목차

Pixoas에서는 웹사이트 제작을 쉽게 따라 할 수 있도록 9편의 튜토리얼로 쪼개어 연재한다.
차근차근 따라오면 어느새 나만의 개인 웹사이트가 완성되어 있을 것이다.

• 💡 [웹사이트 제작 1편] 유지비 0원? 워드프레스 대신 노션 택한 이유
• 🎨 [웹사이트 제작 2편] AI로 코딩 없이 웹사이트 뼈대 구축하기
• 📝 [웹사이트 제작 3편] 노션을 웹사이트 CMS로 쓰는 법 (현재 글)
• ☁️ [웹사이트 제작 4편] Cloudflare Pages로 웹사이트 배포하기
• ⚙️ [웹사이트 제작 5편] 노션 글 자동 반영! 깃허브 액션 연동법
• 🚨 [웹사이트 제작 6편] 노션 이미지 엑스박스 오류 해결
• 📈 [웹사이트 제작 7편] 검색엔진 등록 & 도메인 연결
• 💰 [웹사이트 제작 8편] 애드센스 승인, 가치 없는 콘텐츠 피하기
• 🤖 [웹사이트 제작 9편] AI로 블로그 방문자 늘리기

이 시리즈는 특정 서비스를 무조건 추천하기 위한 글이 아니다. 내가 직접 여러 방법을 비교하고 운영하면서 선택한 구조를 공유하는 기록에 가깝다. 3편에서는 Notion을 콘텐츠 관리 시스템으로 연결하는 기본 구조를 살펴봤다. 이어지는 4편에서는 완성된 웹사이트를 Cloudflare Pages에 배포하고 실제 인터넷에서 접속할 수 있도록 만드는 과정을 알아볼 예정이다.

✅ 마무리 정리

1. 콘텐츠 중심의 웹사이트라면 별도의 데이터베이스 서버를 구축하지 않고도 노션을 강력한 헤드리스 CMS처럼 활용할 수 있다.
2. 노션과 웹사이트를 연결하기 위해서는 'Integration 인증 토큰'과 사용할 'Database ID'가 필요하다.
3. 인증 토큰을 만들었다면, 반드시 노션 데이터베이스 페이지 우측 상단 메뉴를 통해 해당 Integration을 '연결 추가' 해주어야 권한 오류를 막을 수 있다.