Notion에서 "Markdown & CSV로 내보내기"를 실행했더니 파일명 끝마다 32자리의 페이지 ID가 붙고, 콜아웃 블록은 가공되지 않은 raw HTML로 빠져나오며, 토글은 접기 기능이 풀려 일반 문단으로 나열된 ZIP 파일이 내려받아진 경험이 있을 것입니다. 혹은 Notion 페이지를 에디터에 그대로 복사해 붙여넣었다가 스타일 속성이 덕지덕지 붙은 span 태그로 가득 찬 텍스트를 마주하기도 합니다. Notion에서 깔끔한 마크다운(Markdown)을 추출하는 작업은 단 하나의 방식만 있는 것이 아니라 2가지 경로가 있으며, 상황에 맞는 경로를 선택하는 것만으로도 수작업 정리 시간을 크게 줄일 수 있습니다.
대외비 문서를 포함해 몇 개의 페이지만 즉시 깔끔한 마크다운으로 바꾸고 싶다면, Notion에서 "•••" → "내보내기" → "HTML"을 선택한 뒤 출력된 HTML을 HTML to Markdown에 붙여넣고 실행하면 됩니다. 변환은 브라우저 안에서만 완결되며 외부 서버로 업로드되지 않습니다. ZIP 파일 일괄 이전의 정리 절차와 API 자동화를 포함한 전체적인 내용은 아래에서 자세히 설명합니다.
어떤 경로를 선택해야 할까
두 경로 모두 최종적으로 도달하는 결과물은 같습니다. Obsidian이나 정적 사이트 생성기(SSG), README, LLM 프롬프트에 곧바로 넣을 수 있는 이식성 높은 마크다운입니다. 차이점은 출발 지점과 사후 정리 작업의 범위입니다.
- 경로 A — Markdown & CSV ZIP 내보내기: 워크스페이스 전체 또는 특정 페이지 트리를 통째로 이전하고 싶을 때 사용합니다. UUID가 섞인 파일명, 콜아웃의 HTML, 동기화 블록의 중복을 일괄 스크립트로 정리할 수 있는 환경이라면 아래의 경로 A를 참고하세요.
- 경로 B — HTML로 내보내 브라우저에서 변환하기: 대상이 1페이지 또는 소수의 페이지이고, 기획서나 계약서 같은 대외비 내용이 포함되어 외부 서버에 업로드하고 싶지 않을 때 사용합니다. 처음부터 군더더기 없는 마크다운을 얻고 싶다면 브라우저 기반 HTML to Markdown에 붙여넣기만 하면 됩니다. 이 경우 아래의 경로 B를 참고하세요.
자동화 파이프라인을 구축하고 싶다면 2026년 3월에 공식 출시된 Notion의 Markdown Content API라는 세 번째 선택지도 있습니다. 이는 두 경로를 설명한 뒤 소개합니다.
Notion은 어떻게 마크다운을 생성하는가
Notion은 블록 기반 에디터입니다. 한 페이지는 단락, 제목, 목록, 데이터베이스, 콜아웃, 토글, 동기화 블록, 수식, 임베드 등 다양한 블록의 트리 구조로 이루어져 있으며, 이 중 표준 마크다운 문법과 1:1로 대응하는 것은 일부에 불과합니다. "Markdown으로 내보내기"를 실행하면 Notion은 이 트리를 순회하면서 마크다운으로 표현 가능한 가장 가까운 형태로 변환합니다. 마크다운에 대응 구문이 없는 블록은 누락되거나, 단순 텍스트로 평탄화되거나, 순수 HTML 태그 그대로 남게 됩니다.
Notion 공식 도움말 센터는 콜아웃(Callout) 블록에 대해 "마크다운에 해당하는 구문이 없으므로 HTML로 내보내진다"새 탭에서 열립니다고 명시하고 있습니다. 또한 해당 문서에는 Windows 파일 시스템의 기본 MAX_PATH 260자 경로 길이 제한에 걸릴 수 있다는 경고와 함께 7-Zip 압축 해제 프로그램 사용 권장 사항도 안내되어 있습니다. 그 밖의 고유한 동작들은 명시되어 있지 않아 ZIP 파일을 열어본 뒤에야 알게 되는 경우가 많습니다.
기본 Markdown & CSV 내보내기 절차
어느 경로를 선택하든 Notion 내에서의 내보내기 기본 조작은 동일합니다. 페이지 우측 상단의 "•••" 메뉴를 누르고 "내보내기"를 선택한 뒤 형식을 "Markdown & CSV"로 지정합니다. Business 및 Enterprise 플랜에서는 "하위 페이지 포함" 옵션을 켜서 해당 페이지 하위의 모든 페이지 트리를 단일 ZIP 파일에 묶을 수 있습니다. 워크스페이스 전체 내보내기는 "Settings → Workspace → General" 메뉴에서 실행할 수 있으며, 규모가 큰 워크스페이스의 경우 생성에 수 시간이 걸리기도 합니다.
경로 A — Markdown & CSV ZIP 내보내기 정리하기
내려받은 ZIP 파일의 압축을 풀면 반복해서 마주치는 8가지 특성이 나타납니다. 각 항목의 원인과 실무적인 정리 방법을 소개합니다.
파일명과 페이지 링크에 32자리 페이지 ID가 붙는 문제
내보내진 .md 파일명의 끝에는 대부분 "문서 제목 + 공백 + 32자리 16진수 페이지 ID"가 붙으며, 마크다운 내부의 [페이지 멘션] 링크 역시 이 ID가 포함된 파일명을 가리킵니다. 파일명을 손으로 직접 수정하면 내부 링크가 전부 깨져 버립니다. 정석적인 해결법은 2단계(2-Pass) 스크립트 처리입니다. 먼저 전체 파일명에서 "페이지 ID → 깔끔한 제목" 대응표를 만든 뒤, 전체 마크다운 파일 내부의 링크 주소를 치환하고, 마지막으로 파일명 자체를 깔끔한 제목으로 변경합니다. 커뮤니티의 Notion's Markdown Export Quirks새 탭에서 열립니다에서도 동일한 패턴을 다루고 있습니다.
Windows의 260자 경로 길이 제한
Notion의 깊은 중첩 페이지 구조는 My Team's Handbook a1b2c3.../Onboarding e4f5g6.../Week 1 tasks h7i8j9....md와 같이 매우 긴 파일 경로를 만들어냅니다. Windows에서는 기본 MAX_PATH 260자 제한을 쉽게 초과하므로, Notion 공식 도움말은 "폴더 생성 옵션을 끄거나" "긴 경로를 지원하는 7-Zip으로 압축을 해제할 것"을 권장합니다. macOS와 대부분의 Linux 파일 시스템에는 동일한 260자 제한이 없습니다.
콜아웃 블록이 순수 HTML로 출력됨
이모지와 배경색이 들어간 Notion의 콜아웃 블록은 마크다운의 인용문이 아니라 인라인 HTML로 내보내집니다. 많은 마크다운 렌더러는 인라인 HTML을 별도 스타일 없이 그대로 통과시키므로, Notion에서 보던 배경색 상자가 사라지고 밋밋한 텍스트로 표시됩니다. 실무적인 수정 방법은 두 가지입니다. 콜아웃을 > 마크다운 인용문으로 치환(이모지와 배경색은 제거됨)하거나, 결과물을 표시할 렌더러가 GFM Admonition(> [!NOTE])을 지원한다면 해당 문법으로 변환하는 것입니다.
토글이 접기 속성을 잃는 경우
Notion의 토글은 제목 아래에 접히는 콘텐츠를 두는 구조이지만, Markdown & CSV 내보내기에서는 접기 래퍼가 사라지고 제목과 본문 내용이 일반 문단으로 나란히 배치되는 경우가 있습니다. GitHub이나 정적 사이트에서 접기 기능을 유지하고 싶다면 마크다운이 지원하는 표준 인라인 HTML인 <details><summary>제목</summary>본문</details> 형태로 감싸주어야 합니다.
동기화 블록이 여러 파일에 복제됨
동기화 블록(Synced block)은 Notion 안에서는 단 하나의 원본을 여러 페이지가 공유하는 방식이지만, 내보내기 시점에는 각 페이지 파일마다 내용이 개별적으로 복제되어 기록됩니다. 이 상태 그대로 RAG 파이프라인이나 검색 인덱스에 입력하면 거의 동일한 청크가 중복 생성되어 검색 품질을 떨어뜨립니다. 따라서 동기화 블록마다 기준(canonical)이 되는 대표 페이지를 하나 정하고, 다른 파일의 중복 내용은 수동이나 스크립트로 제거해 주어야 합니다.
수식과 임베드가 일반 텍스트로 변환됨
Notion의 LaTeX 수식은 $...$ 또는 $$...$$ 형태의 순수 텍스트로 출력됩니다. Obsidian은 이를 수식으로 렌더링하며, GitHub도 2022년부터 $…$와 $$…$$ 수식 렌더링을 공식 지원새 탭에서 열립니다합니다. 그 외의 렌더러에서는 일반 텍스트로 보일 수 있습니다. 동영상, Figma, X(구 Twitter) 임베드는 마크다운 이미지나 <iframe>이 아닌 단순한 URL 1줄로 출력됩니다.
이미지 경로가 내보내기 폴더 구조에 의존함
이미지 파일은 각 .md 파일과 같은 위치에 생성되는 첨부 폴더 안에 저장되며, 마크다운 내부 링크는 해당 폴더를 가리키는 상대 경로로 작성됩니다. .md 파일 하나만 다른 디렉터리로 이동하면 인접한 첨부 폴더가 함께 이동하지 않아 모든 이미지 링크가 깨집니다. 파일을 첨부 폴더와 항상 함께 이동시키거나, 이미지 링크를 /assets/ 같은 중앙 디렉터리 경로로 일괄 치환하고 이미지 파일들도 해당 위치로 모아주어야 합니다.
데이터베이스가 CSV로 출력되고 마크다운 표가 되지 않음
전체 페이지 데이터베이스는 CSV 파일로 내보내지며, 각 행의 하위 페이지는 동일한 이름의 폴더 안에 개별 .md 파일로 저장됩니다. 마크다운 표 형태의 텍스트는 생성되지 않으며 필터, 정렬, 그룹화 등 데이터베이스 뷰 설정과 관계형(Relation), 롤업(Rollup), 수식(Formula) 속성도 유지되지 않습니다. 데이터베이스 내용을 마크다운 표로 사용하고 싶다면 해당 CSV 파일을 CSV to Markdown에 붙여넣어 파이프 표로 즉시 변환할 수 있습니다. 데이터베이스를 많이 사용하는 워크스페이스라면 이 방법으로 이전 시간을 크게 아낄 수 있습니다.
경로 B — HTML로 내보내 브라우저에서 변환하기
페이지 수가 몇 개 되지 않고 기획서, 계약서, 사내 지식 베이스처럼 외부 서버 업로드가 엄격히 금지된 문서라면 HTML 내보내기를 거치는 것이 가장 빠르고 안전한 경로입니다.
Notion의 내보내기 옵션에는 Markdown & CSV, HTML, PDF의 3가지가 있습니다. 이 중 HTML은 서식을 가장 풍부하게 보존합니다. 콜아웃의 HTML 구조와 토글 래퍼, 내부 링크 등이 잘 유지됩니다.
변환 절차는 다음과 같습니다.
- Notion에서 대상 페이지를 열고 우측 상단 "•••" → "내보내기" → "HTML"을 선택합니다(필요 시 하위 페이지 포함).
- 생성된
.html파일을 열거나 텍스트 에디터로 내용을 복사합니다. - HTML to Markdown 변환기에 붙여넣고 실행 버튼을 누릅니다.
- 출력된 깔끔한 마크다운을 복사하여 Obsidian, CMS, 또는 LLM 프롬프트에 붙여넣습니다.
모든 변환 처리는 사용자의 웹 브라우저 내에서 자바스크립트로 실행되며, 데이터가 외부 서버로 전송되지 않습니다. 계정 생성이나 OAuth 인증, 워크스페이스 토큰 발급 같은 번거로운 절차도 필요하지 않습니다. 일반적인 서버 업로드형 온라인 변환 도구는 파일을 전송하는 순간 문서의 제어권이 외부로 넘어가지만, 브라우저 로컬 변환은 네트워크 요청 자체가 발생하지 않아 안전합니다. 서버 전송형 도구의 보안 위험과 로컬 검증 방법은 온라인 변환 사이트 보안 검증을 참고하세요.
변환 시 유지되는 요소: 제목, 목록, 링크, 표, 코드 블록, 굵게, 기울임 서식. 제거되는 요소: 인라인 style 속성, 클래스명, 불필요한 래퍼 <div> 태그, data-* 속성 등 마크다운에 대응하지 않는 시각용 마크업. Notion 콜아웃 태그는 인라인 HTML 구조로 유지되지만 Notion 앱 전용 배경색이나 스타일은 제거됩니다. LLM에 프롬프트로 전달할 때도 불필요한 HTML 태그를 제거한 마크다운이 토큰을 절약하는 데 훨씬 유리하며, 자세한 토큰 절감 비교는 LLM 입력엔 Markdown vs HTML을 참고하세요. 웹 문서나 서식 복사 시의 일반적인 HTML 정리 패턴은 HTML 붙여넣기로 마크다운 변환을 참고하세요.
경로 C — Notion Markdown Content API (API 버전 2026-03-11)
Notion은 2026년에 공식 마크다운 콘텐츠 엔드포인트를 새롭게 추가했습니다. 공식 개발자 문서새 탭에서 열립니다에 사양이 설명되어 있으며, 요청 시 API 버전 헤더 2026-03-11을 반드시 지정해야 합니다. 블록 트리를 일일이 조회하고 변환할 필요 없이 다음 엔드포인트 요청으로 페이지를 마크다운으로 다룰 수 있습니다.
GET /v1/pages/{id}/markdown— 페이지 내용을 마크다운으로 가져오기POST /v1/pages(markdown본문 포함) — 마크다운으로 새 페이지 생성하기PATCH /v1/pages/{id}/markdown— 마크다운으로 기존 페이지 본문 수정하기
Notion은 이 형식을 Enhanced Markdown이라고 부릅니다. 일반 제목, 목록, 링크, 강조 서식은 표준 마크다운 문법을 따르며, CommonMark에 대응물이 없는 블록은 XML 형태의 태그(콜아웃은 <callout>...</callout>, 토글은 <details><summary>...</summary>...</details>, 데이터베이스는 참조 태그 <database>)로 표현됩니다. 다운스트림 도구가 이 태그들을 해석할 수 있다면 정보 유실 없이 전달할 수 있으며, 지원하지 않는다면 스크립트에서 정규식 등으로 태그를 제거하거나 변환할 수 있습니다. Public Integration뿐만 아니라 Internal 및 Personal 토큰에서도 사용할 수 있습니다.
API 사용 시 유의할 점 2가지:
- 파일 블록(이미지, PDF)은 유효 기간이 제한된 서명된 URL(pre-signed URL)로 반환됩니다. 마크다운 텍스트만 저장해 두면 추후 이미지 링크가 만료되므로, 동일한 작업 파이프라인 내에서 파일 원본을 다운로드해야 합니다.
- 약 20,000개 블록을 초과하는 방대한 문서는 응답이 잘리며(truncate)
unknown_block_ids목록이 반환됩니다. 추가 내용은 후속 요청으로 나누어 조회해야 합니다.
단발성 문서나 사내 대외비 문서라면 HTML 내보내기 후 브라우저에서 변환하는 경로 B가 가장 빠릅니다. API는 Notion과 사내 CMS 연동, Notion 문서를 RAG 색인에 자동 동기화하는 파이프라인 등 자동화 시스템 구축 시 진가를 발휘합니다.
비교 — Notion에서 마크다운을 추출하는 4가지 방법
| 방식 | 추천 상황 | 콜아웃 / 토글 | UUID 포함 여부 | 브라우저 내 완결 |
|---|---|---|---|---|
| 기본 Markdown & CSV 내보내기 | 워크스페이스 전체 일괄 이전, 대량 스크립트 정리 | 콜아웃은 raw HTML, 토글 래퍼 유실 가능 | 포함됨 (파일명 및 링크) | Yes (ZIP 로컬 저장) |
| Notion HTML 내보내기 → HTML to Markdown | 대외비 단일 및 소수 페이지 빠른 변환 | 콜아웃 인라인 HTML 유지, 토글 <details> 유지 | 포함 안 됨 | Yes |
| notion-to-md새 탭에서 열립니다 npm 라이브러리 | 블록 단위 변환 규칙 커스터마이징 | 블록별 커스텀 설정 가능 | 설정 가능 | Yes (Node / CLI) |
Notion Markdown Content API (버전 2026-03-11) | API 토큰 기반의 정기 자동화 파이프라인 | <callout> / <details> Enhanced Markdown 태그 | 포함 안 됨 (파일 생성 없음) | No (서버 API 호출) |
자주 묻는 질문
Notion은 왜 파일명 끝에 32자리 페이지 ID를 붙이나요?
Notion 내부에서는 모든 블록과 페이지가 고유한 ID로 관리됩니다. 내보내기 시 동일한 제목의 페이지(예: "회의록"이라는 이름의 페이지가 여러 개 존재하는 경우)가 같은 폴더 내에서 충돌하는 것을 방지하기 위해 파일명 끝에 32자리 16진수 페이지 ID를 붙입니다. 다만 이로 인해 파일 가독성이 떨어지고 Windows의 파일 경로 길이 제한을 초과하는 원인이 됩니다. HTML 내보내기나 Markdown Content API는 단일 파일 또는 API 응답으로 처리되므로 이 문제가 발생하지 않습니다.
온라인 변환 도구에 대외비 문서를 붙여넣어도 안전한가요?
사용하는 도구가 브라우저 로컬 방식인지 서버 처리 방식인지에 따라 다릅니다. FormatArc의 HTML to Markdown과 같은 브라우저 완결형 도구는 모든 변환 처리가 사용자 PC의 자바스크립트 엔진에서 이루어지며 외부로 데이터가 전송되지 않습니다. 반면 서버 처리형 SaaS 도구는 파일이나 텍스트가 서버로 전송됩니다. 기획서, 계약서, 미공개 기술 문서 등을 다룰 때는 브라우저 개발자 도구의 네트워크 탭에서 실제 요청 발생 여부를 확인하여 데이터가 안전하게 보호되는지 검증하는 것이 좋습니다.
API와 내보내기 중 무엇을 써야 하나요?
정기적이고 반복적인 자동화 작업(Notion 페이지를 정적 사이트 빌드에 연동, RAG 검색 인덱스 자동 동기화, 대규모 정기 백업 등)에는 API가 적합합니다. 일회성 대량 이전이며 사후 스크립트 정리를 감당할 수 있다면 Markdown & CSV 내보내기로 충분합니다. 서버에 데이터를 보내지 않고 소수의 대외비 문서를 즉시 깔끔한 마크다운으로 바꾸고 싶다면 HTML 내보내기 후 브라우저 변환 도구를 사용하는 것이 가장 효율적입니다.
Notion Markdown Content API는 콜아웃과 토글을 유지하나요?
네, Enhanced Markdown 태그 형태로 유지됩니다. 콜아웃은 <callout>...</callout>, 토글은 <details><summary>...</summary>...</details> 태그로 변환됩니다. 두 태그 모두 CommonMark에서 허용하는 인라인 HTML이며, GitHub 등 주요 플랫폼은 <details>를 접기 블록으로 정상 렌더링합니다. 콜아웃 태그는 Notion 외부 플랫폼에서는 기본 스타일이 없으므로 직접 CSS를 적용하거나 일반 인용문(> )으로 변환해 사용해야 합니다.
내보낼 때 데이터베이스는 어떻게 처리되나요?
기본 Markdown & CSV 내보내기 시 각 데이터베이스는 ZIP 최상위에 CSV 파일로 추출되고, 각 행에 속한 상세 페이지는 같은 이름의 폴더 안에 .md 파일로 저장됩니다. 데이터베이스의 필터, 정렬, 그룹화 뷰나 수식, 관계형 속성은 보존되지 않습니다. 데이터베이스 본문을 마크다운 표로 사용하고 싶다면 해당 CSV 파일을 CSV to Markdown 변환기에 넣어 마크다운 파이프 표로 즉시 변환할 수 있습니다.
정리
Notion의 마크다운 내보내기는 완전히 깨진 것이 아니라, 블록 구조를 텍스트로 변환하는 과정에서 정보가 축약되는 손실성(lossy) 변환입니다. 경로 A는 워크스페이스 전체를 한 번에 가져올 수 있는 대신 8가지 고유한 서식 문제를 일괄 정리해야 합니다. 경로 B는 HTML to Markdown을 활용하여 대외비 문서도 브라우저 안에서 안전하고 깔끔하게 마크다운으로 변환할 수 있으며, 별도의 계정 등록이나 권한 부여가 필요하지 않습니다. 자동화 파이프라인이 필요하다면 Notion Markdown Content API(API 버전 2026-03-11)가 유용한 선택지입니다. 데이터베이스 테이블을 마크다운 표로 바꾸고자 할 때는 CSV to Markdown도 함께 활용해 보세요. HTML을 마크다운으로 변환하는 일반적인 문법 대응과 도구 비교는 HTML 마크다운 변환 가이드를 참고하세요.