Astro Notes

概述

astro-notes 是一个 Astro 集成，把 Notion 数据库里的页面同步成本地 Markdown，然后走 Astro 原生的 Content Collections 流程。

为什么做这个

我试过 notion-next、notion-blog，但都有同样的问题：

• 同步逻辑和站点代码耦合，难调试
• Notion 改了字段 schema 就崩
• 没有 Astro 类型安全

astro-notes 用 Astro 5 引入的 Content Layer API，把 Notion 当成一个 loader。本地 dev 时实时拉取，构建时缓存。

安装

npm install astro-notes

// astro.config.mjs
import notes from 'astro-notes';

export default defineConfig({
  integrations: [
    notes({
      databaseId: process.env.NOTION_DB_ID,
      token: process.env.NOTION_TOKEN,
      outputDir: 'src/content/blog',
    }),
  ],
});

工作原理

1. 调 Notion API 拉取数据库
2. 把每个 block 转换成 Markdown（基于 notion-to-md）
3. 写到本地 outputDir
4. Astro Content Collections 接管后续

这样的好处：

• Notion 只是「写作工具」，不是「数据源」
• 站点本身仍然是纯静态的
• 切换到 MDX 或其他工具时，导出的文件可以直接用

已知限制

• Notion API 速率限制（每秒 3 次），大数据库首次同步慢
• 嵌入式 block（如 YouTube）支持有限
• 不支持 Notion 的「评论」字段