노션에서 글을 다 써놓고, 워드프레스에 붙여넣기 하다가 이미지가 통째로 날아간 경험 있으신가요. 저는 그게 반복되면서 발행 한 편에 30분을 넘기고 있었습니다. 결국 Notion API와 GitHub Actions를 엮어 자동 발행 파이프라인을 직접 만들었고, 지금은 노션에서 상태 값 하나만 바꾸면 다음 날 블로그에 글이 올라옵니다.
Notion API로 '쓰는 도구'와 '보여주는 도구'를 분리하다
저도 처음에는 노션을 그냥 초안 메모장처럼 썼습니다. 글이 완성되면 워드프레스 편집기를 열고, 복사하고, 이미지를 다시 올리고, 서식을 맞추는 과정을 매번 반복했죠. 어느 날 발행 직전에 이미지 링크가 전부 깨진 걸 발견하고 나서야 "이건 사람이 할 일이 아니다"라는 생각이 들었습니다.
Notion API는 노션의 페이지와 블록 데이터를 JSON 형식으로 꺼내오는 공식 인터페이스입니다. 여기서 API(Application Programming Interface)란 서로 다른 프로그램이 데이터를 주고받을 수 있게 연결해주는 창구라고 보면 됩니다. 노션이 API를 공개하면서, 노션 데이터베이스를 외부 시스템의 콘텐츠 소스로 쓰는 것이 가능해졌습니다(출처: Notion 공식 API 문서).
제가 선택한 구조는 단순했습니다. 노션 데이터베이스에 '발행 준비'라는 상태 속성을 만들고, 그 상태인 글만 API로 가져오도록 필터를 걸었습니다. 이렇게 하면 초안이나 작업 중인 글은 건드리지 않고, 실제로 나갈 준비가 된 글만 파이프라인에 태울 수 있습니다. '쓰는 환경'과 '배포하는 환경'이 완전히 분리되는 순간이었습니다.
notion-to-md로 변환할 때 예상 못 했던 복병들
API로 JSON을 가져오는 것까지는 생각보다 순탄했습니다. 문제는 그 JSON을 사람이 읽을 수 있는 문서 형식으로 바꾸는 단계였습니다. 여기서 사용한 것이 notion-to-md라는 오픈소스 라이브러리입니다. 이 라이브러리는 노션 블록 구조를 마크다운(Markdown) 텍스트로 변환해주는 도구인데, 마크다운이란 #이나 **같은 간단한 기호로 제목과 강조를 표현하는 경량 문서 형식을 말합니다(출처: notion-to-md GitHub).
솔직히 이건 예상 밖이었습니다. 단순한 텍스트 블록은 잘 변환됐지만, 노션의 중첩 토글이나 데이터베이스 인라인 블록이 섞이면 변환 과정에서 정보가 조용히 사라지는 경우가 생겼습니다. 토글 안에 넣어둔 보충 설명이 통째로 날아간 걸 발행 후에야 발견했을 때는 꽤 당황했습니다.
결국 블록 타입별로 예외 처리 로직을 하나씩 손으로 추가하는 수밖에 없었습니다. 중첩 토글은 재귀적으로 내용을 펼쳐서 평탄화하고, 인라인 데이터베이스는 별도의 변환 규칙을 만들었습니다. 이 작업이 파이프라인 구축 전체에서 가장 손이 많이 가는 부분이었고, 지금도 노션에서 새로운 블록 타입을 쓸 때마다 변환이 제대로 되는지 확인하는 습관이 남아 있습니다.
변환 시 주로 문제가 됐던 블록 유형
- 중첩 토글(Nested Toggle): 하위 블록이 재귀적으로 포함되어 단순 변환 시 내용 소실
- 인라인 데이터베이스(Inline Database): 노션 전용 구조로 마크다운에 대응하는 형식이 없음
- 동기화 블록(Synced Block): 원본 블록 참조 방식이라 독립 변환이 불가능
- 노션 내부 이미지 링크: 만료 토큰이 포함되어 시간이 지나면 깨짐
GitHub Actions로 새벽마다 자동 빌드가 돌아가게 만들기
변환 스크립트가 어느 정도 안정되고 나서는, 이 스크립트를 사람 손 없이 정기적으로 실행할 방법이 필요했습니다. 선택한 도구는 GitHub Actions입니다. GitHub Actions란 코드 저장소에 이벤트가 발생하거나 정해진 시간이 되면 자동으로 스크립트를 실행해주는 CI/CD 도구입니다. 여기서 CI/CD(Continuous Integration/Continuous Deployment)란 코드 변경을 자동으로 테스트하고 배포하는 일련의 자동화 프로세스를 말합니다(출처: GitHub Actions 공식 문서).
저는 cron 스케줄러를 이용해 매일 새벽 3시에 워크플로우가 실행되도록 설정했습니다. 워크플로우가 시작되면 Notion API에서 '발행 준비' 상태 글을 가져오고, notion-to-md로 마크다운을 만들고, AI API에 넣어 문체를 다듬고 메타 디스크립션을 자동 생성한 뒤, 정적 사이트 생성기(SSG) 빌드를 트리거합니다. 정적 사이트 생성기란 마크다운이나 HTML 데이터를 미리 빌드해서 서버 부하 없이 빠르게 제공할 수 있는 사이트를 만들어주는 도구로, Astro나 Next.js, Hugo 등이 여기에 해당합니다.
파이프라인을 여러 단계로 쌓은 덕분에 자동화는 잘 돌아가고 있지만, 솔직히 말하면 디버깅이 까다로워진 것도 사실입니다. Notion API 응답이 달라졌는지, 변환 스크립트 로직에 문제가 생겼는지, AI 가공 단계에서 오류가 났는지, 아니면 빌드 자체가 실패했는지를 로그로 일일이 추적해야 할 때가 있습니다. 단계가 많을수록 장애 지점도 늘어난다는 건 미리 알고 있었지만, 막상 새벽 빌드가 조용히 실패해 있는 걸 아침에 발견하면 기분이 썩 좋지는 않습니다.
완전 자동화보다 '반자동'이 더 현실적인 이유
파이프라인을 완성하고 가장 먼저 욕심이 생긴 건 "사람이 전혀 개입하지 않는 완전 자동화"였습니다. 그런데 실제로 운영해보니 그 욕심을 내려놓게 된 이유가 두 가지 있었습니다.
하나는 AI가 문체를 다듬는 과정에서 원래 제가 의도했던 뉘앙스가 미묘하게 바뀌는 경우였습니다. 제가 직접 써봤는데, 농담처럼 쓴 문장이 진지하게 교정되거나, 의도적으로 짧게 끊은 문장이 길게 이어 붙여지는 일이 종종 있었습니다. 그래서 지금은 발행 직전에 diff, 즉 원본과 AI가 가공한 결과물의 차이를 사람이 한 번 눈으로 확인하는 단계를 파이프라인에 남겨뒀습니다.
다른 하나는 노션 자체의 안정성 문제입니다. 노션은 rate limit, 즉 일정 시간 안에 API를 호출할 수 있는 횟수 제한이 존재하고, 드물지만 플랫폼 자체가 다운되는 경우도 있습니다. 트래픽이 작은 개인 블로그라면 큰 문제가 되지 않지만, 콘텐츠 발행 타이밍이 중요한 미디어나 트래픽이 큰 서비스라면 노션을 CMS 핵심 의존성으로 두는 것은 리스크로 보입니다. 일반적으로 노션 CMS 방식이 요즘 유행처럼 번지고 있는데, 제 경험상 이건 규모와 목적에 따라 신중하게 판단해야 할 부분입니다.
결국 지금 제 파이프라인은 "노션에서 글 쓰고 상태 바꾸기 → 새벽 자동 변환 및 가공 → 아침에 diff 확인 후 최종 승인 → 정적 사이트 빌드 반영" 흐름으로 정착했습니다. 완전 무인이 아니라, 사람이 최소한으로 개입하는 반자동 구조입니다. 이 정도면 30분짜리 발행 작업이 5분 이내로 줄었으니, 저는 충분히 만족하고 있습니다.
자주 묻는 질문
Q. 노션 API 무료로 써도 되나요, 사용량 제한 있나요?
A. 노션 API는 무료로 사용할 수 있지만 rate limit이 존재합니다. 현재 기준으로 평균 초당 3회 요청 제한이 적용되며, 이를 초과하면 429 오류가 반환됩니다. 개인 블로그 수준의 호출 빈도라면 거의 문제가 되지 않지만, 대량 콘텐츠를 한 번에 처리할 때는 요청 사이에 딜레이를 넣는 로직이 필요합니다.
Q. notion-to-md 말고 노션 블록을 변환하는 다른 방법도 있나요?
A. 있습니다. Notion API의 블록 응답을 직접 파싱해서 커스텀 렌더러를 만드는 방법이 있고, 일부 정적 사이트 생성기는 노션 연동 플러그인을 별도로 제공하기도 합니다. 다만 notion-to-md는 커뮤니티가 활발하고 예외 처리 사례가 많이 공유되어 있어서, 시작 단계에서는 가장 빠르게 구축할 수 있는 선택지입니다.
Q. GitHub Actions 대신 다른 CI/CD 도구를 써도 되나요?
A. 네, 충분히 가능합니다. GitLab CI, CircleCI, Jenkins 같은 도구도 동일한 역할을 합니다. GitHub을 이미 코드 저장소로 쓰고 있다면 GitHub Actions가 별도 설정 없이 바로 연동되어 가장 편리하고, 무료 플랜에서도 월 2,000분의 실행 시간을 제공하므로 개인 블로그 자동화에는 충분합니다.
Q. 정적 사이트 생성기는 어떤 걸 선택하는 게 좋나요?
A. 목적에 따라 다릅니다. 빌드 속도와 유연성을 중시한다면 Astro, React 생태계에 익숙하다면 Next.js, 심플함을 원한다면 Hugo가 좋은 선택입니다. 노션 연동 파이프라인 관점에서는 마크다운 파일을 입력으로 받는 SSG라면 어떤 것이든 연결할 수 있으므로, 이미 익숙한 도구를 쓰는 것이 유지보수 면에서 유리합니다.
결론
Notion API, notion-to-md, GitHub Actions, 정적 사이트 생성기를 엮은 이 파이프라인은 "글 쓰는 환경"과 "글 보여주는 환경"을 깔끔하게 분리해준다는 점에서 저한테는 꽤 잘 맞는 구조입니다. 발행에 쓰던 시간을 글 쓰는 데 돌릴 수 있게 됐고, 이미지 깨짐 같은 반복 오류도 사라졌습니다.
다만 파이프라인 단계가 많아질수록 디버깅 비용도 늘어나고, 노션 플랫폼 의존도가 생긴다는 점은 염두에 둬야 합니다. 지금 노션으로 블로그 초안을 관리하고 있다면, 일단 Notion API와 notion-to-md 조합으로 작은 변환 스크립트 하나를 만들어보는 것부터 시작해보시길 권합니다. 완성된 파이프라인을 한 번에 쌓으려 하지 말고, 단계별로 검증하면서 쌓아 올리는 것이 결국 가장 빠른 길이었습니다.
참고: Notion 공식 API 문서 | notion-to-md GitHub | GitHub Actions 공식 문서 | Astro 공식 문서