Notion · 2026.06.09 · 4 min read
Notion API 匯出頁面教學：Markdown、PDF 與自動化備份怎麼做（2026）
Notion API 匯出頁面教學：Markdown、PDF 與自動化備份怎麼做（2026）
解答先行
Notion API 目前最直接的匯出路線不是 PDF，而是 Markdown。
2026 年官方已經提供：
GET /v1/pages/{page_id}/markdown
你可以用它把 Notion page 取成 enhanced markdown。至於 PDF，實務上通常是：
Notion API 取 Markdown → 轉 HTML → 用瀏覽器或工具輸出 PDF。
如果你還沒拿到 token，先看：Notion API Key 怎麼拿。如果你還沒測過 endpoint，先看：Notion API 用 curl 測試教學。
Notion API 可以直接匯出 PDF 嗎？
短答：不要把 Notion API 當成官方 PDF 匯出 API。
比較務實的選擇是：
| 目的 | 建議路徑 |
|---|---|
| 文章同步 | GET /v1/pages/{id}/markdown |
| AI 摘要 / 寫作流程 | Markdown |
| 網站發布 | Markdown → HTML |
| PDF 報告 | Markdown → HTML → PDF |
| 完整備份 | API + Markdown + 圖片轉存 |
如果你只是偶爾要 PDF，Notion App 內建匯出就夠。
如果你要自動化、排程、批次處理，才需要 API。
用 API 取 Notion page markdown
先設定：
export NOTION_API_KEY="ntn_xxxxxxxxx"
export PAGE_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
呼叫：
curl "https://api.notion.com/v1/pages/$PAGE_ID/markdown" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
回傳大概會有：
{
"object": "page_markdown",
"id": "page-uuid",
"markdown": "# 標題\n\n內文...",
"truncated": false,
"unknown_block_ids": []
}
你要注意兩個欄位：
| 欄位 | 意思 |
|---|---|
truncated |
內容是否因限制被截斷 |
unknown_block_ids |
沒完整取出的 block，需要再查 |
如果你的頁面很大，不要假設第一次就拿完。
Markdown 和 blocks API 怎麼選？
以前要匯出 Notion 內容，通常要走 block API：
GET /v1/blocks/{block_id}/children
現在如果你的目標是文章、摘要、備份，Markdown endpoint 會更直接。
| 方法 | 優點 | 缺點 |
|---|---|---|
| Markdown endpoint | 快、適合文章與 AI | 對部分特殊 block 仍要處理 |
| Blocks API | 控制力高 | 要自己組文章結構 |
| Notion App 匯出 | 不用寫程式 | 不適合自動化 |
我的建議：
| 你要做什麼 | 選哪個 |
|---|---|
| 寫作同步網站 | Markdown endpoint |
| AI 讀文章 | Markdown endpoint |
| 精準處理 checkbox / column / database | Blocks API |
| 批次備份 | Markdown + blocks fallback |
Markdown 轉 PDF 的實務流程
API 拿到 markdown 後，你可以走這條路：
- API 取得 markdown
- 存成
.md - 用 markdown-it / remark / pandoc 轉 HTML
- 用 Playwright / Puppeteer 轉 PDF
- 把 PDF 存到 R2、雲端硬碟或本地備份資料夾
最小 Node.js 概念：
import fs from "fs";
import { chromium } from "playwright";
const markdown = fs.readFileSync("page.md", "utf8");
const html = `
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
body { font-family: system-ui, sans-serif; line-height: 1.7; max-width: 760px; margin: 48px auto; }
</style>
</head>
<body>
<pre>${markdown.replaceAll("<", "<")}</pre>
</body>
</html>`;
const browser = await chromium.launch();
const page = await browser.newPage();
await page.setContent(html);
await page.pdf({ path: "notion-page.pdf", format: "A4" });
await browser.close();
正式使用時，不要直接把 markdown 放進 <pre> 就結束。你會需要把 markdown 轉 HTML，再做排版。
自動化備份該怎麼設計？
如果你的目標是備份 Notion，不要只備份 PDF。
比較好的組合是：
| 檔案 | 用途 |
|---|---|
.md |
可讀、可重新發布、AI 可處理 |
.json |
保留 properties、page id、狀態 |
| 圖片檔 | 避免 Notion 暫時網址過期 |
.pdf |
給人閱讀或交付 |
也就是說，PDF 是輸出，不是唯一備份。
我會把備份分成三層：
| 層級 | 內容 |
|---|---|
| 原始資料 | page properties JSON |
| 可讀內容 | markdown |
| 交付版本 | PDF / HTML |
常見限制
| 問題 | 說明 |
|---|---|
| 權限 | connection 需要 read content capability |
| 大頁面 | 可能出現 truncated |
| 特殊 block | 可能需要 blocks API 補抓 |
| 圖片 | Notion file URL 可能過期，建議轉存 R2 |
| 不是官方 API 直接輸出的主路徑 |
如果你是內容網站，最重要的是圖片。
Notion 內的圖片連結常有時效性。正式發布到網站前，應該把圖片下載並轉存到 R2 或自己的 CDN。
實戰：文章發布流程
一個比較完整的流程會是：
- Query data source 找
Status = Ready - 讀 page properties
- 取 page markdown
- 抓 markdown 裡的圖片
- 圖片上傳 R2
- markdown 圖片網址改成 R2
- 產生網站文章
- 必要時再輸出 PDF
這就是為什麼 Notion API 不只是拿 token。
它真正的價值，是把 Notion 變成內容系統的起點。
FAQ
Notion API 可以直接匯出 PDF 嗎？
不建議這樣理解。Notion API 更適合先取得 markdown 或 blocks，再由你的系統轉成 HTML / PDF。
Notion API 的 markdown endpoint 是什麼？
GET /v1/pages/{page_id}/markdown，會回傳 enhanced markdown、是否截斷、以及未知 block id。
什麼時候還需要 blocks API？
當你需要精準處理特殊 block、巢狀內容、database、欄位或自訂轉換規則時，blocks API 仍然有用。
Notion 圖片可以直接留原網址嗎？
不建議。Notion file URL 可能過期。正式網站或長期備份應轉存到 R2、S3 或自己的 CDN。
資料來源
資料最後查核日期：2026-06-09
