NotionNext 프로젝트 작동 원리

이전 문서: NotionNext 프로젝트 작동 원리 게시일: 2024-11-18 마지막 수정: 2025-10-15 원래 분류: 🚀 설치 및 배포 태그: NotionNext 요약: Vercel, Notion, NotionNext 세 가지의 관계를 간단히 소개합니다.

이 글에 대해

이 글에서는 NotionNext 프로젝트의 작동 원리와 Notion, Vercel, NotionNext 세 가지의 관계를 간단히 설명합니다.

해결 방식에 대해

전통적인 웹사이트 구축에서는 보통 다음과 같은 방식이 사용됩니다.

• 먼저 클라우드 서버를 임대합니다.

• 다음으로 WordPress나 직접 개발한 웹페이지 같은 사이트 코드를 서버에 업로드합니다.

• 그다음 서버에 직접 데이터베이스를 배포하거나 클라우드 서비스 제공자에게 데이터베이스를 구매합니다.

• 이어서 서버를 중심으로 코드를 실행하고 데이터베이스에서 웹페이지 데이터를 읽습니다.

• 마지막으로 도메인을 구매하고, 도메인을 이 서버의 IP 주소에 연결합니다.

비교

NotionNext 사이트의 본질도 같습니다. 다만 구성 요소를 다른 대안으로 바꿨을 뿐입니다. 즉 서버, 코드, 데이터베이스를 각각 다른 서비스로 대체합니다.

1. 먼저 Vercel 클라우드 플랫폼에 가입합니다. Vercel은 주로 CPU 연산 능력, 메모리 공간, 운영체제, 실행 환경을 제공합니다.

2. 다음으로 GitHub 플랫폼에 가입합니다. GitHub는 협업 개발, 코드 저장, 버전 관리를 제공합니다. NotionNext의 코드는 이 플랫폼에 호스팅해 유지보수할 수 있습니다.

3. 그다음 Notion 노트를 준비합니다. 글, 이미지 같은 콘텐츠를 Notion에 저장합니다.

4. 이어서 Vercel을 중심으로 GitHub에서 최신 코드를 가져오고, 컴파일하고 실행한 뒤, Notion에서 웹페이지 데이터를 읽어 NotionNext의 규칙에 따라 웹페이지를 표시합니다.

5. 마지막으로 구매한 도메인을 Vercel 클라우드 플랫폼이 제공하는 서버 주소로 해석합니다. Vercel은 다시 해당 도메인을 프로젝트에 연결합니다.

요약

여기서 볼 수 있듯이 Vercel은 서버 개념을 대체하고, Notion은 데이터베이스 역할을 하며, NotionNext는 핵심 코드가 됩니다.

제 개인적인 사용 습관을 기준으로 이런 대체 방식을 선택한 이유는 세 가지 문제 때문입니다.

1. 글쓰기: Notion에 노트를 쓰는 방식으로 글을 작성하는 것이 더 편하고 오래 지속하기 쉽습니다. 공식 계정 편집기, WordPress 관리자 화면, 서드파티 블로그 플랫폼의 발행 페이지로 글을 쓰는 습관을 들이기는 어렵습니다. 자신에게 편한 노트 도구에서 글을 써야 부담 없이 오래 할 수 있고, 오래 해야 잘할 가능성도 높아집니다.

2. 유지보수: 서버 보안과 업그레이드, 데이터베이스 백업과 유지보수에는 에너지가 듭니다. 더 큰 문제는 서버를 만지는 성취감이 습관이 될 수 있다는 점입니다. 서버와 웹사이트를 구축하는 과정에서 계속 재미를 느끼다 보면, 글쓰기보다 기술 설정에 빠지기 쉽습니다.

3. 비용: 블로그 글만 발행하려는데 서버와 도메인에 큰 비용을 들여 1년짜리 서버를 빌릴 필요가 있을까요?

작업 흐름

이제 이 프로젝트를 처음 설치하고 실행할 때, 그리고 업데이트와 설정 업그레이드 과정에서 어떤 일이 일어나는지 살펴보겠습니다.

최초 설치

Vercel로 NotionNext 배포하기 튜토리얼에는 배포 방법이 자세히 소개되어 있습니다. 배포 과정에서는 어떤 일이 일어날까요?

1. 사용자는 먼저 제 Notion 데이터베이스를 템플릿으로 복제해야 합니다.

Notion은 데이터베이스 역할을 합니다. 지원되는 모든 표 머리글과 필드는 NotionNext 코드 안에 이미 고정되어 있습니다. 표 머리글과 필드가 일치하지 않으면 데이터를 정상적으로 읽을 수 없습니다. 사용자가 템플릿을 복제하는 과정은 Notion 안에 자신만의, NotionNext가 인식할 수 있는 데이터베이스를 만드는 과정과 같습니다.

1. 사용자는 GitHub 플랫폼에 가입하고 NotionNext 코드를 복제합니다.

코드는 핵심입니다. 그런데 모든 사용자가 코드를 공개적으로 가져갈 수 있고, 언제든 업데이트할 수 있으며, 함께 코드 개발에 참여할 수 있게 하려면 어떻게 해야 할까요? GitHub는 개발자들이 가장 많이 사용하는 코드 협업 관리 플랫폼입니다. 여러 사람이 온라인 문서를 함께 편집하고 버전 관리를 통해 원하는 시점으로 되돌릴 수 있는 도구와 비슷합니다.

1. Vercel 플랫폼에 가입합니다.

앞에서 코드와 데이터베이스 문제를 해결했습니다. 마지막으로 서버 문제를 해결해야 합니다.

Vercel에 로그인한 뒤 코드를 Vercel 플랫폼에 업로드해 배포할 수도 있습니다. 하지만 Vercel은 더 강력한 기능을 지원합니다. 바로 GitHub 저장소와 실시간으로 연결하는 기능입니다.

Vercel은 24시간 GitHub 저장소 코드를 감시합니다. 업데이트나 변경이 발생하면 저장소에서 최신 코드를 가져와 패키징하고 컴파일합니다.

이를 통해 사용자는 서버와 배포에 신경 쓰지 않고 GitHub의 코드만 잘 관리하면 됩니다. 비유하자면 사용자는 회사의 개발자로서 코드 규칙만 담당하고, 서버 운영 작업은 24시간 온라인인 운영 팀에 맡기는 셈입니다.

새 버전의 NotionNext에서는 대부분의 코드 설정을 Notion에서 직접 구성할 수 있습니다. 즉 코드에는 신경 쓰지 않고 Notion에서 사이트 설정과 글 콘텐츠 유지보수에 집중할 수 있습니다.

NotionNext의 작동 과정

Vercel 클라우드 컴퓨팅 환경이 NotionNext 코드를 실행하고, 사용자의 Notion 데이터베이스에서 글을 계속 가져와 웹사이트로 배치합니다. Notion 데이터가 변경되면 사이트 데이터도 함께 바뀝니다. 순수 기술 언어로 설명하면 다소 어렵게 느껴질 수 있으므로, 아래에서는 비유를 통해 프로젝트 작동 원리를 설명합니다.

NotionNext 작은 가게

NotionNext로 만든 사이트는 작은 식당과 비슷합니다. 가게에는 간판이 있고, 인터넷에서 손님이 들어옵니다. 손님은 가게 입구를 보고 들어와 메뉴를 확인한 뒤 원하는 메뉴를 선택합니다.

이 가게는 전통적인 식당과 다릅니다. 안에는 요리할 주방도 없고 전문 요리사도 없습니다. 모든 메뉴는 Notion 쪽에서 공급받는 미리 준비된 메뉴입니다. Notion은 NotionNext 가게의 유일한 공급업체이자 중앙 주방이라고 볼 수 있습니다.

가게에는 많은 직원이 있습니다. 이 직원들은 Vercel 클라우드 플랫폼이 제공하는 CPU, 디스크, 메모리 같은 자원으로 구성됩니다. 직원들은 매장의 지시에 따라, 코드로 설계된 운영 규칙에 맞춰 일합니다.

직원들은 주로 다음 일을 합니다.

1. Notion에서 콘텐츠를 가져옵니다. 코드에는 어느 Notion 페이지에서 콘텐츠를 가져와야 하는지 지정되어 있습니다. 이 값이 NOTION_PAGE_ID입니다.

2. 손님을 맞이합니다. 손님이 메뉴를 고르면 미리 준비된 콘텐츠를 데워 제공합니다.

3. 콘텐츠를 접시에 담아 손님에게 제공합니다. NotionNext는 Hexo, Gitbook 같은 여러 접시, 즉 테마를 제공합니다. 운영자는 어떤 표현 방식으로 사용자에게 보여 줄지 테마를 설정할 수 있습니다.

에너지를 절약하는 NotionNext

NotionNext는 에너지 절약을 지향하는 가게와 같습니다.

가게가 처음 문을 열 때는 Notion에서 모든 메뉴를 한 번씩 가져와 이 콘텐츠를 창고에 저장합니다. 여기서 창고는 Vercel의 디스크와 메모리를 뜻합니다.

가게에 손님이 없을 때 직원들은 움직이지 않습니다. 직원들은 먼저 콘텐츠를 데우거나 새 콘텐츠를 가지러 가지 않고, 손님을 맞이하지도 않습니다. 전기를 아끼기 위해 불도 켜지 않는 셈입니다.

Vercel 직원에게는 한 가지 특징이 있습니다. 이들은 외부 인력 또는 공유 인력과 비슷합니다. 가게에 할 일이 없을 때는 Vercel의 자원 스케줄링에 따라 다른 프로젝트에서 일합니다.

사용자가 웹사이트 주소로 접속해 일이 필요해지면, Vercel은 즉시 인력을 배정해 요청을 처리합니다.

콘텐츠 제공 흐름

가게에 손님이 들어오면 어떤 일이 일어날까요?

손님이 가게 문으로 들어오면 직원 한 명이 응대 역할을 맡습니다. 직원은 손님의 행동을 관찰합니다. 예를 들어 손님의 시선이 어떤 메뉴를 향하는지, 손가락이 어떤 메뉴를 가리키는지 확인하고, 이를 바탕으로 주방에 재고 확인과 예열을 요청합니다. 동시에 운영자가 지정한 규칙에 따라 계절별 인기 메뉴를 손님에게 추천하기도 합니다.

손님이 메뉴를 주문한 뒤 제공 흐름은 어떻게 되나요?

손님이 곧바로 가게에 들어와 홈의 대표 메뉴 하나를 주문했다고 가정합니다. 응대 직원은 다른 직원에게 창고에서 이 메뉴를 찾아보라고 알립니다. 지난번에 가져온 재고가 있는지 확인하는 것입니다.

재고가 있으면 먼저 해당 재고를 가져와 상태를 확인합니다. 보관 기한 안이라면 데운 뒤 접시에 담아 사용자에게 제공합니다. 동시에 백그라운드에서 다른 직원이 Notion에 가서 최신 콘텐츠를 가져오고, 가져온 콘텐츠는 창고에 보관합니다.

주문한 메뉴의 재고가 가게에 없다면, 가게는 사용자에게 잠시 기다리게 하고 직원이 우선순위로 콘텐츠를 가져오게 합니다. 콘텐츠를 가져오는 즉시 데워 사용자에게 제공합니다.

그러면 사용자 경험이 나빠지지 않을까요? 어떤 메뉴는 느리고, 어떤 메뉴는 식었거나 최신이 아닐 수도 있습니다.

제공 속도 문제의 경우, 손님이 주문할 때 직원은 여러 메뉴를 한 번에 준비해 둡니다. 그리고 콘텐츠가 오래되거나 다시 갱신되어야 하는 시간을 설정합니다. 예를 들어 30초 안에 새 손님이 같은 메뉴를 요청하면 다시 데우지 않고 바로 제공할 수 있습니다. 시간이 지난 콘텐츠는 다시 생성합니다.

콘텐츠가 최신이 아닌 문제의 경우, 직원은 평소에 Notion에서 새 콘텐츠를 먼저 가져오지는 않습니다. 하지만 이전 손님이 주문했을 때 동시에 새 콘텐츠가 있는지 확인해 준비해 둡니다. 그러면 이후 손님은 때맞춰 최신 콘텐츠를 볼 수 있습니다.

이 설계의 특징은 사용자가 자주 요청하는 콘텐츠일수록 더 자주 업데이트된다는 점입니다. 반대로 사용자가 거의 보지 않는 콘텐츠가 아무리 최신이어도 실질적인 가치는 낮습니다. 사이트에서는 보통 20%의 콘텐츠가 80%의 방문 가치를 만들고, 나머지 80%는 보조 역할을 합니다.

또 다른 관점에서 보면, 전문 사용자가 아니라면 대부분의 방문자는 콘텐츠가 아주 최신인지 아닌지 체감하지 못합니다. 운영자는 평판도 고려해야 하지만 비용과 효율도 함께 고려해야 합니다. 사용자가 받아들일 수 있는 범위 안에서 비용을 낮추는 것이 중요합니다.

여기서 볼 수 있듯 NotionNext의 철학은 100점짜리 완벽함을 추구하는 것이 아닙니다. 제한된 에너지와 자원의 80%를 실제로 일어날 가능성이 높고 실용 가치가 큰 일에 투입해, 전체 사이트 경험을 80점 수준으로 안정적으로 만드는 것입니다.

Notion에서 새 글을 만들었고, NotionNext 사이트 방문자가 첫 순간부터 볼 수 있게 하려면 어떻게 해야 할까요?

쉽습니다. 직접 한 번 접속하면 됩니다. 운영자 자신이 사용자로서 사이트에 들어가 해당 글을 요청하면, 직원이 그 콘텐츠를 준비합니다. 또 하나의 단순한 방법은 사이트를 다시 배포하는 것입니다. Vercel 관리자 화면에서 redeploy를 실행하면 직원이 콘텐츠를 다시 가져오게 됩니다.

사이트 업데이트

앞에서는 NotionNext 가게의 콘텐츠 제공 흐름을 설명했습니다. 이제 Vercel, Notion과의 협업 관계, 즉 사이트 업그레이드와 반복 개선 과정을 설명하겠습니다. 가게를 오래 운영하다 보면 매장을 새로 꾸미거나 직원 교육으로 효율을 높이고 싶어질 수 있습니다. 이때 어떤 일이 일어날까요?

NotionNext 가맹점

저는 직접 운영하는 지점보다 여러 사람이 함께 운영하는 가맹 모델을 더 좋아합니다. 혼자 가게를 여는 것보다 함께 열어 가는 쪽이 더 재미있습니다.

NotionNext는 사실상 하나의 가맹 브랜드와 같습니다.

브랜드 유지보수와 운영 센터는 tangly의 중앙 저장소에 있습니다. tangly는 NotionNext의 작업 흐름을 계획하고 설계하며, NotionNext 대표 매장의 인테리어 샘플을 만듭니다. 그리고 검증된 흐름을 운영 매뉴얼, 즉 코드에 기록합니다.

⚠️

NotionNext 가게의 운영 매뉴얼은 프로젝트 코드를 뜻합니다.

누구나 이 매뉴얼을 복사해 무료로 참여할 수 있습니다.

NotionNext 가게의 새 운영 매뉴얼 버전이 나오면, 다른 운영자들은 최신 인테리어 방안과 직원 교육 매뉴얼을 가져가 자신의 사이트 운영 효율을 높일 수 있습니다.

운영자는 자신의 사이트를 어떻게 업그레이드해야 할까요?

먼저 최신 운영 매뉴얼을 가져와야 합니다. 매뉴얼은 tangly의 GitHub 저장소에 있으며, 코드 동기화를 통해 최신 매뉴얼을 받을 수 있습니다.

모든 운영자는 매뉴얼을 평생 무료로 업데이트할 수 있습니다.

매뉴얼 업데이트 문제

주의할 점은 일부 운영자가 매뉴얼 업데이트에 실패할 수 있다는 것입니다. 자신의 사이트를 운영하면서 매뉴얼을 개인화해 수정했기 때문입니다. 운영 전략과 사용 습관에 맞추기 위한 변경이지만, 새 매뉴얼을 병합하는 과정에서 충돌이 생길 수 있습니다.

이런 현상은 흔합니다. 지역과 취향이 다르면 같은 방식이 모든 사용자에게 맞을 수는 없습니다.

보통 몇 가지 처리 방법이 있습니다.

⚠️

여기서 말하는 매뉴얼은 사용자의 GitHub 코드를 비유한 것입니다.

1. 운영자가 자신의 매뉴얼을 백업한 뒤, 먼저 Tangly의 매뉴얼을 그대로 가져와 현재 매뉴얼을 덮어써 사이트가 정상 운영되는지 확인합니다. 이후 백업해 둔 개인화 매뉴얼을 참고해 새 매뉴얼을 조금씩 조정합니다.

2. 숙련된 개발자는 매뉴얼을 병합하면서 조항 충돌을 직접 확인하고 최종 버전으로 합칠 수 있습니다.

3. 본부에 도움을 요청합니다. tangly는 운영자가 사용자 정의한 매뉴얼 방식을 참고해 가장 적합한 버전을 맞춤으로 만들 수 있습니다.

💡

운영자는 매뉴얼 업데이트만 잘 처리하면 됩니다. Vercel은 자동으로 직원을 배정해 매뉴얼에 따라 사이트를 꾸미고 실행합니다.

더 나은 운영 경험

어떤 운영자는 매뉴얼 업데이트 때 충돌이 많아 번거롭지만, 그래도 커스터마이징은 하고 싶어 합니다. 어떻게 해야 할까요?

NotionNext는 사용자가 자신의 Notion 데이터베이스에서 직접 매뉴얼을 커스터마이징하는 방식을 지원합니다. 이것이 NOTION_CONFIG입니다.

직원은 NotionNext 가게의 규칙만 따르는 것이 아니라, Notion에서 NOTION_CONFIG를 가져와 로컬 규칙으로 사용합니다. 이 규칙은 본점 규칙보다 우선순위가 높습니다.

NOTION_CONFIG에서는 사용자가 자신의 스타일과 실행 규칙을 설정할 수 있습니다. 사이트를 업그레이드할 때 로컬 매뉴얼과 본점 매뉴얼이 충돌하는 것을 피하고 싶다면 이 방식을 시도해 볼 수 있습니다.

또한 어떤 사이트는 자체적으로 화면 구성과 매장 스타일을 설계하고 싶을 수 있습니다. 이 경우 기존 매뉴얼 내용을 직접 수정하기보다, 매뉴얼 안에 별도의 부속 파일을 만들고 그 안에서 자신의 내용을 편집하는 것을 권장합니다.

여기서 말하는 부속 파일은 운영자가 자신만의 테마 폴더를 만드는 것을 뜻합니다. 기존 테마 내용을 수정하는 대신, 예를 들어 hexo 테마를 복사해 new 테마로 이름을 바꾸고 new 테마 안에서만 수정하세요. 또는 새 코드 브랜치를 만들어 모든 변경을 자신의 브랜치에서 진행하면, 메인 브랜치의 자동 업그레이드에 영향을 주지 않습니다.

마지막

읽어 주셔서 감사합니다. 이 글은 여기까지이며, 이후 새로 떠오르는 내용이 있으면 계속 업데이트하겠습니다.

원문 링크

https://docs.tangly1024.com/article/vercel-notionnext-notion