노션 워크스페이스 연동해서 노션 페이지를 로컬(md)로 다운로드해본 사례 🗂️

소개

스터디 과정 중 노션 워크스페이스 연동 실습이 포함되어 있어서, 미리 세팅하는 김에 노션에 정리해두었던 활동 기록들을 로컬 환경에 백업해보았다.

• 노션에 스터디 및 개인 활동 기록을 꾸준히 정리해둔 상태

• 추후를 대비해 로컬 폴더 구조 안에 md 파일 형태로 보관하면 좋겠다고 판단

• 단순 실습이 아니라, 실제로 끝까지 다운로드가 되는지 확인해보고 싶었음

진행 방법

사용한 도구 및 환경

• Notion (페이지 원본)

• Notion API (연동용)

• Claude Code (오류 원인 분석 & 코드 수정 도움)

• VS Code (작업용 에디터)

• Windows + PowerShell

• 결과물: Markdown (.md) 파일

1️⃣ Notion API 키 발급 & 페이지 ID 확인

• Notion → My integrations 에서 API 키 발급

• 다운로드하고 싶은 페이지를 노션에서 선택

• 페이지 URL에서 Page ID 추출

👉 여기까지는 비교적 수월하게 진행됨

2️⃣ .env 파일에서 첫 번째 막힘

• 워크스페이스 루트에 .env 파일을 직접 만들어야 했는데 여기서 잠깐 멈춤

• 제공받은 폴더 안에 .env.example 파일이 있어서:

  • 해당 내용을 복사

  • myenv.env 파일을 새로 생성해서 붙여넣기

이 과정에서 env 파일의 역할(환경 변수 관리)을 Claude Code가 설명해줘서 이해함

3️⃣ 패키지 설치 & 가상환경 이슈

PowerShell에서 패키지 설치를 시도하다가 오류 발생 → Claude Code에 아래 코드에 대해 질문

.\.venv\Scripts\Activate.ps1
python -m pip install -r .claude\skills\notion-down-lv2\requirements.txt

• 첫 줄: PowerShell에서 가상환경 활성화

• 두 번째 줄: Python 모듈 설치

• 문제: 가상환경(.venv)이 아직 생성되지 않은 상태

👉 VS Code 터미널에서 가상환경을 먼저 생성

python -m venv .venv

그 후 다시 활성화 시도했더니 보안 오류 발생

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

• 위 명령어 실행 후 가상환경 활성화 성공 🎉

4️⃣ SyntaxError와 환경 변수 이름 문제

페이지 다운로드 실행 시 다음 오류 발생:

SyntaxError: from __future__ imports must occur at the beginning of the file

• 오류가 난 .py 파일로 이동

• from __future__ import ... 구문을 파일 최상단으로 이동 → 해결

그 다음 발생한 오류:

• .env 파일에 NOTION_TOKEN 이 없다는 메시지

원인 분석:

• .py 파일에서는 .env 경로를 ".env"로 지정

• 실제 파일명은 myenv.env

• env 파일 안 변수명도 NOTION_API_TOKEN= 으로 되어 있었음

👉 수정한 내용

• env 경로를 myenv.env로 변경

• 변수명을 NOTION_TOKEN= 으로 통일

5️⃣ Notion AI 블록으로 인한 오류

다운로드 중 아주 긴 오류 메시지 발생

• Claude Code에 오류 로그를 그대로 전달

• 원인: 노션 페이지에 포함된 AI 블록

  • 해당 블록 타입은 Notion API에서 지원하지 않음

    Notion 페이지에 AI 블록(Notion AI가 생성한 콘텐츠)이 있어서 발생하는 오류입니다. Notion API가 ai_block 타입을 지원하지 않습니다.

    해결 방법

    스크립트에서 지원하지 않는 블록을 건너뛰도록 수정하면 됩니다. 해당 스크립트를 확인해볼게요.

    Read c:\Users\AI-WORKSPACE\.claude\skills\notion-down-lv2\scripts\notion_download_tree.py

    blocks_to_markdown 함수에서 ai_block을 처리하지 않아서 발생하는 오류입니다. 지원하지 않는 블록 타입을 건너뛰도록 수정할게요.

    Edit c:\Users\AI-WORKSPACE\.claude\skills\notion-down-lv2\scripts\notion_download_tree.py

    Added 8 lines

    Read c:\Users\AI-WORKSPACE\.claude\skills\notion-down-lv2\scripts\notion_download_tree.py (lines 107-166)

    중복된 줄이 있네요. 제거할게요.

    Edit c:\Users\AI-WORKSPACE\.claude\skills\notion-down-lv2\scripts\notion_download_tree.py

    Modified

    수정 완료했습니다. 이제 다시 실행해보세요.

👉 해결 방법

• ai_block 타입을 만나면:

  • 내용을 건너뛰고

  • md 파일에는 주석으로 표시하도록 코드 수정

# 지원하지 않는 블록 타입은 skip 처리

이후 다운로드 정상 완료 🎉

결과와 배운 점

결과

• 원래는 데이터베이스 + 하위 페이지 2개가 포함된 페이지를 다운로드할 계획이었음

• 실제로는 데이터베이스는 제외되고, 하위 페이지 2개만 md 파일로 다운로드됨

• 하위 페이지 내에서 Notion AI로 생성된 블록은 아래와 같이 표시됨

<!-- [Notion unsupported: API에서 지원하지 않음] -->

• AI 블록을 제외한 나머지 본문, 제목, 구조는 비교적 잘 유지됨

• 결과적으로 문서형 페이지 백업 용도로는 충분히 만족스러운 결과였음

배운 점 & 인사이트

• NOTION_DOWNLOAD_DEFAULT_PAGE_ID가 parent page로 인식되면서, 해당 페이지 하위에 있는 child page만 다운로드 대상이 된 것으로 보임

• 이 구조상 데이터베이스는 child page로 취급되지 않아 결과물에서 제외된 것으로 추정됨

• 즉, 어떤 ID를 기준으로 삼느냐에 따라 다운로드 결과가 크게 달라질 수 있음

• Notion API는 모든 블록 타입을 지원하지는 않음

• .env, 가상환경, PowerShell 보안 정책은 Windows 환경에서 특히 자주 막히는 포인트

• 오류 메시지를 그대로 AI에게 던져주고 하나씩 분해해서 해결하는 방식이 꽤 효과적이었음

다음에 한다면

• 대시보드처럼 사용하는 상위 집계용 페이지 ID를 NOTION_DOWNLOAD_DEFAULT_PAGE_ID로 지정하면,

  • 그 아래에 연결된 여러 페이지들이 연쇄적으로 다운로드되는지 확인해볼 계획

• 만약 이 방식이 통한다면:

  • 노션을 대시보드 중심으로 설계 →

  • 로컬 백업 시에는 하나의 진입점(Page ID)만 관리하는 구조가 가능할 것 같음

• 데이터베이스가 포함된 경우에는 여전히 별도 처리가 필요할 것으로 예상됨

• 스터디 시작 전에 미리 세팅해두면 훨씬 수월할 듯

• 자동화까지는 아니어도 정기 백업 용도로는 충분히 실용적

한 줄 정리 ✍️

노션 페이지 로컬 백업, 한 번 세팅은 빡세지만 해두면 마음이 편해진다 😅