Notion은 차기 Notion-Version에서 Notion-flavored Markdown(markdown_version: "v2")을 markdown 엔드포인트의 기본값으로 설정한다고 발표했습니다. 아울러, 기존의
**enhanced markdown(v1)는 비권장(deprecated)**되며, 다음 버전 릴리스 약 3개월 후에
모든 Notion-Version에서 폐지될 예정입니다.
📌 영향을 받는 사람
- Notion API를 사용하여 페이지를 생성/조회/업데이트하는 경우 Markdown을 사용하는 개발자
- 댓글 API(
POST /v1/comments 등)에서 Markdown을 다루는 경우의 사용자
- Notion과 연동되는 사내 툴, 동기화 배치(sync batch), AI 에이전트를 운영하는 개발자
@notionhq/client를 사용하는 JavaScript / TypeScript 개발자
지금 당장 동작이 바뀌는 것은 아닙니다. 하지만 폐지까지의 유예 기간은 제한적이므로, 지금 v2로 테스트해 보는 것이 안전합니다. 아울러 SDK 대응 및 Notion MCP의 새로운 툴도 소개합니다.
중요한 점은 'Notion-Version을 올리는 시점'과 'v1이 폐지되는 시점'이 다르다는 것입니다. 현재 사용 중인 Notion-Version을 계속 보내는 요청은 당분간 아무 변화가 없습니다. 하지만 v1 자체는 약 3개월 후에 전 버전에서 폐지될 예정이므로, Notion-Version을 고정하더라도 피할 수 없습니다.
⚠️ Breaking Change
차기 Notion-Version에서는 markdown_version을 생략한 요청은 v2로 처리됩니다. 만약 `
자세한 내용은 「Get version changes」 문서를 참조하십시오.
대상 코드 재고 조사: 상기 5개 엔드포인트를 호출하는 부분을 파악합니다. 출력 및 입력 Markdown이 예상대로인지 확인하며 markdown_version: "v2"를 명시하여 테스트합니다.
SDK 업데이트: @notionhq/client을 v5.29.0 이상으로 업데이트합니다. 다음 Notion-Version에서는 400이 됩니다. "v1"에 대한 하드코딩을 제거합니다.
변경 로그(changelog) 모니터링: 차기 버전명, 출시일, 폐지일 공지를 놓치지 마십시오.
사내 문서 업데이트: AI 에이전트의 지침서 (CLAUDE.md 등)에도 반영하십시오.
💡 팁
v2를 명시해 두면 Notion-Version을 올렸을 때도 기본값 변경의 영향을 받지 않습니다. "생략에 의존하지 않고 명시하는 것"이 가장 안전합니다.
Notion-Version을 고정했다고 안심할 수 없습니다: 기본값 적용은 차기 버전부터이지만, v1의 폐지는 전반에 걸쳐 대상입니다.
가져온 Markdown을 후속 처리에서 파싱하는 경우: v1과 v2에서 구문이 다를 수 있으므로, 파서 및 테스트 확인이 필요합니다 (구문은 공식 리퍼런스에서 확인하십시오).
AI 에이전트가 Markdown을 작성하게 하는 경우: 프롬프트나 지침서에 v1 구문의 전제가 들어있지 않은지 검토하십시오.
아래는 변경의 사고방식을 보여주는 예시입니다. 요청 형태는 문서의 「Markdown versions」에서 확인해 주십시오.
// 생략 = 현재는 v1입니다. 차기 Notion-Version에서는 v2로 처리됩니다.
const res = await fetch(`https://api.notion.com/v1/pages/${pageId}/markdown`, {
headers: {
...
// markdown_version을 명시하여 기본값 변경의 영향을 받지 않도록 합니다.
// ※ 지정 위치(쿼리/바디)는 공식 문서 「Markdown versions」를 참조하십시오.
const res = await fetch(
...
위의 markdown_version 전달 방식(쿼리인지 바디인지)은 입력 정보만으로는 확정할 수 없으므로 예시입니다. 구현 시에는 반드시 공식 문서를 확인하십시오.
npm install @notionhq/client@^5.29.0
## Notion API / Markdown 연동
- markdown 엔드포인트에서는 `markdown_version: "v2"`를 명시합니다.
- enhanced markdown(v1)은 비권장입니다. 신규 구현에서는 사용하지 말고, 기존 코드도 v2로 마이그레이션하여 테스트하십시오.
...
| 항목 | 내용 |
|---|
| 기본값 적용 | 차기 Notion-Version에서 markdown_version 생략 시 v2 |
| v1 지정 | 차기 Notion-Version에서는 400 validation_error |
| v1 폐지 | 차기 버전 출시 약 3개월 후 전반에 걸쳐 폐지 예정 (3개월 전에 공지) |
| 현행 버전 | 당분간 변경 없음 (기본값은 v1) |
| SDK | @notionhq/client v5.29.0 이상에서 markdown_version 지원 |
| MCP | notion-get-version-changes로 변경 이력 및 변경자 획득 가능 |
지금 당장 해야 할 일은 " markdown_version: "v2"를 명시하여 테스트하는 것", "SDK를 v5.29.0 이상으로 올리는 것", "변경 로그(changelog)를 추적하는 것"의 세 가지입니다. v1 폐지일이 적어도 3개월 전에 공지된다고는 하지만, Markdown을 다루는 코드는 영향 범위가 넓으므로 빠른 검증을 권장합니다.
![Notion API: Markdown v2가 기본값화되고 v1은 폐지 예정 [마이그레이션 가이드] 대표 이미지](/api/thumb?u=https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fqiita-user-contents.imgix.net%252Fhttps%25253A%25252F%25252Fcdn.qiita.com%25252Fassets%25252Fpublic%25252Farticle-ogp-background-afbab5eb44e0b055cce1258705637a91.png%253Fixlib%253Drb-4.1.1%2526w%253D1200%2526blend64%253DaHR0cHM6Ly9xaWl0YS11c2VyLXByb2ZpbGUtaW1hZ2VzLmltZ2l4Lm5ldC9odHRwcyUzQSUyRiUyRmxoMy5nb29nbGV1c2VyY29udGVudC5jb20lMkZhJTJGQUNnOG9jS0oza2lJamRVZjd6UHZDUHNqTGhkcHFzbDlYU2MweGJscHRZRzgwOWd5dlhYWWh2UTElM0RzOTYtYz9peGxpYj1yYi00LjEuMSZhcj0xJTNBMSZmaXQ9Y3JvcCZtYXNrPWVsbGlwc2UmYmc9RkZGRkZGJmZtPXBuZzMyJnM9OGM4MDU5ODEyMzY3Y2ZlNmIzMDVkYTMzMjAwNjcwMDE%2526blend-x%253D120%2526blend-y%253D467%2526blend-w%253D82%2526blend-h%253D82%2526blend-mode%253Dnormal%2526s%253Dfd6ab3c0ea5267b0e6bf5b2f6bc36ab2%3Fixlib%3Drb-4.1.1%26w%3D1200%26fm%3Djpg%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjEuMSZ3PTk2MCZoPTMyNCZ0eHQ9Tm90aW9uJTIwQVBJJTNBJTIwTWFya2Rvd24lMjB2MiVFMyU4MSU4QyVFMyU4MyU4NyVFMyU4MyU5NSVFMyU4MiVBOSVFMyU4MyVBQiVFMyU4MyU4OCVFNSU4QyU5NiVFMyU4MCU4MXYxJUUzJTgxJUFGJUU1JUJCJTgzJUU2JUFEJUEyJUU0JUJBJTg4JUU1JUFFJTlBJUUzJTgwJTkwJUU3JUE3JUJCJUU4JUExJThDJUUzJTgyJUFDJUUzJTgyJUE0JUUzJTgzJTg5JUUzJTgwJTkxJnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnR4dC1jb2xvcj0lMjMxRTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9NTYmdHh0LXBhZD0wJnM9ZTRmM2JjY2I3ZTcxOWQyYTEzMDM2ODM3ODdkYjg1YWI%26mark-x%3D120%26mark-y%3D112%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjEuMSZ3PTgzOCZoPTU4JnR4dD0lNDBwaWNuaWMmdHh0LWNvbG9yPSUyMzFFMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT0zNiZ0eHQtcGFkPTAmcz1iZTllNDg4YzE3YjgzYzFmZGE3MTQ2MjU5MjlkYzU1ZQ%26blend-x%3D242%26blend-y%3D480%26blend-w%3D838%26blend-h%3D46%26blend-fit%3Dcrop%26blend-crop%3Dleft%252Cbottom%26blend-mode%3Dnormal%26s%3D477d45a8e1383244f1a8ba4a0379a410&w=640&s=xoDsjxs3oYmBgZs2izE5fDoQ)