Di cư từ Notion API sang Markdown & Cloudflare Pages

May 30, 2026 • @aethery
Di cư từ Notion API sang Markdown & Cloudflare Pages

Hey, lại là hắn đây, và dạo này hắn đã quyết định làm một cuộc đại di cư cho blog của mình: dọn nhà từ Notion API sang Markdown files đặt tại local và deploy lên Cloudflare Pages.

Trước đây hắn từng rất thích dùng Notion làm CMS vì nó tiện, viết lách trực quan và giao diện kéo thả mượt mà. Tuy nhiên, sau một thời gian, Notion API bắt đầu bộc lộ những giới hạn khó chịu: tốc độ query chậm, thi thoảng dính rate limit, và mỗi lần rebuild blog là lại phải đợi kéo data qua mạng rất mất thời gian.

Vì thế, hắn đã quyết định chuyển sang giải pháp thuần túy SSG (Static Site Generation) truyền thống: viết Markdown và lưu tại repo GitHub tam-pham-alpha/xaolonist.eth. Một phần là để tiết kiệm chi phí subscription hàng tháng của Notion, nhưng lý do lớn hơn chính là sự linh hoạt và khả năng tận dụng sức mạnh của AI trong việc xuất bản các bài viết mới, tiện lợi và linh hoạt hơn rất nhiều so với quy trình dùng Notion truyền thống. Dưới đây là tóm tắt các bước hắn đã làm để hoàn tất cuộc di cư này.

Bước 1: Export dữ liệu từ Notion

Đầu tiên, hắn export toàn bộ database bài viết từ Notion dưới dạng Markdown & CSV. Notion sẽ nén toàn bộ bài viết thành một file .zip chứa các file .md cùng thư mục ảnh đi kèm.

Bước 2: Viết script convert và chuẩn hóa cấu trúc

File Markdown xuất ra từ Notion có format frontmatter khá lộn xộn và không tương thích ngay với Gatsby. Hắn đã viết một script Node.js ngắn để:

  1. Đọc tất cả các file .md được xuất ra.
  2. Parse lại Metadata (slug, title, date, category, status…) và ghi đè thành frontmatter chuẩn của blog.
  3. Di chuyển các hình ảnh đính kèm vào đúng thư mục content/blog/<slug>/images/ hoặc lưu làm cover.jpg tại thư mục bài viết.
  4. Đổi lại đường dẫn ảnh trong nội dung bài viết thành relative path tương ứng.

Bước 3: Cấu hình build với Gatsby

Sau khi toàn bộ bài viết đã nằm gọn gàng tại local dưới dạng cấu trúc:

content/blog/<slug>/
├── index.md
└── cover.jpg

Hắn dùng gatsby-source-filesystem kết hợp với gatsby-transformer-remark để Gatsby tự động scan và tạo node cho các file Markdown này. Việc truy vấn qua GraphQL giờ đây diễn ra hoàn toàn ở local, tốc độ build giảm từ gần 1 phút xuống còn chưa đầy 7 giây.

Bước 4: Deploy lên Cloudflare Pages & Workers Static Assets

Cuối cùng, hắn chuyển hẳn sang dùng Cloudflare Workers Static Assets kết hợp với Wrangler để triển khai nhanh nhất:

  1. Cấu hình file wrangler.jsonc để định nghĩa thư mục assets trỏ thẳng vào thư mục public sau khi build
  2. Thay thế lệnh deploy cũ bằng wrangler deploy trong file package.json
  3. Thực hiện quá trình đóng gói và upload trực tiếp từ máy cá nhân hoặc qua CI/CD của GitHub Actions

Giờ đây, quá trình build ứng dụng chỉ mất vỏn vẹn 20 giây và thời gian deploy lên mạng lưới toàn cầu của Cloudflare chỉ tốn 16 giây. Toàn bộ quy trình diễn ra nhanh chóng, nhẹ nhàng và hoàn toàn tự động

Cuộc di cư này giúp hắn nhận ra đôi khi sự phức tạp của API hay database đám mây không mang lại nhiều giá trị bằng sự đơn giản, tin cậy của các file tĩnh (plain text). Cảm giác sở hữu hoàn toàn nội dung của mình dưới dạng file vật lý nằm trên máy tính cá nhân thật sự rất yên tâm.

❤️ cowriter aethery