📝 KitSubStack by Kitmodule

Lấy bài viết từ Substack, chuyển sang Markdown kèm front matter, thay thế nội dung, và xuất ra ZIP — nhẹ, không phụ thuộc, dễ sử dụng.

English | Tiếng Việt

✨ Tính năng

• 📬 Lấy bài viết từ bất kỳ người dùng Substack nào.
• 🏷️ Tạo Markdown kèm front matter cho Hashnode, Hugo, Jekyll, Astro, hoặc định dạng tùy chỉnh.
• 🔄 Thay thế nhiều chuỗi trong nội dung Markdown (replaces giống Golang strings.NewReplacer).
• ⚡ Hỗ trợ lấy bài viết tuần tự hoặc đồng thời với giới hạn tùy chọn.
• 💨 API chainable: offset, limit, đánh số file, callback tiến trình, callback hoàn thành.
• 📦 Xuất nhiều bài viết ra file ZIP tự động.

🚀 Cài đặt

Sử dụng npm

npm install @kitmodule/kitsubstack

Sử dụng CDN

<script src="https://unpkg.com/@kitmodule/kitsubstack/dist/kitsubstack.min.js"></script>

hoặc

<script src="https://cdn.jsdelivr.net/npm/kitsubstack/dist/kitsubstack.min.js"></script>

💡 Cách dùng

Trình duyệt (CDN)

<script src="https://unpkg.com/@kitmodule/kitsubstack-js/dist/kitsubstack.min.js"></script>
<script>
  const kit = new KitSubStack("example.substack.com");

  kit.offset(0)
     .limit(5)
     .numbering(true)
     .frontMatter("hashnode")
     .replaces("Substack", "Hashnode")
     .progress(fetch => {
         if (fetch.success) console.log("✅ Đã lấy:", fetch.post.slug);
         else console.error("❌ Lỗi:", fetch.slug ?? "unknown");
     })
     .completed(filename => console.log("✅ ZIP sẵn sàng:", filename))
     .zip();
</script>

Node.js / CommonJS

const { KitSubStack, zipSubstackToHashnode } = require("kitsubstack-js");

// Sử dụng cơ bản
const kit = new KitSubStack("example.substack.com");

await kit.offset(0)
         .limit(10)
         .frontMatter("hashnode")
         .zip();

// Shortcut helper
await zipSubstackToHashnode("example.substack.com", 0, 5, true);

🧩 Tham khảo API

new KitSubStack(input)

| Tham số | Loại | Mô tả | | ------- | --------------- | ------------------------------------ | | input | string | object | Username, hostname hoặc URL Substack |

Các phương thức chainable

| Phương thức | Mô tả | | | ---------------------- | ----------------------------------------------------------------------- | ------------------------------------------------ | | .offset(n) | Bắt đầu từ bài viết thứ n | | | .limit(n) | Lấy tối đa n bài viết | | | .numbering(true | false) | Thêm số thứ tự vào tên file | | .progress(callback) | Callback khi mỗi bài được lấy | | | .completed(callback) | Callback khi ZIP đã tạo xong | | | .concurrent(n) | Lấy nhiều bài cùng lúc, tối đa n | | | .replaces(...args) | Thay thế nhiều chuỗi trong nội dung, ví dụ .replaces("0","1","2","3") | | | .frontMatter(type | callback) | Chọn preset front matter hoặc function tùy chỉnh | | .zip() | Lấy bài, tạo Markdown + front matter, và xuất ZIP | |

Preset Front Matter

| Preset | Trường dữ liệu | | -------- | --------------------------------------------------------- | | hashnode | title, slug, tags, date, image | | hugo | title, slug, date, draft, tags, description, cover | | jekyll | layout, title, slug, date, categories, description, image | | astro | title, pubDate, description, tags, heroImage | | default | title, slug, date, description, image |

Hỗ trợ async custom function:

kit.frontMatter(async post => ({
    title: post.title.toUpperCase(),
    date: post.post_date,
    tags: post.postTags?.map(t => t.name) ?? [],
}));

Thay thế nhiều chuỗi

kit.replaces(
    "Substack", "Hashnode",
    "2025", "2026"
);

• Hoạt động giống strings.NewReplacer trong Golang.
• Thay thế tất cả các xuất hiện trong nội dung bài viết.

📦 Các gói đã tích hợp / gợi ý sử dụng

KitSubStack là không phụ thuộc vào thư viện ngoài và đã tích hợp sẵn các gói Kit sau:

| Gói | Mục đích | Tích hợp trong KitSubStack? | | ------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------- | | KitZip JS | Tạo file ZIP từ Markdown hoặc các tệp khác; nhẹ, chuỗi (chainable). | ✅ Đã tích hợp sẵn | | KitYAML JS | Chuyển đổi JavaScript object thành YAML front matter cho Markdown. | ✅ Đã tích hợp sẵn | | KitMarkdown JS | Chuyển HTML sang Markdown, nhẹ và không phụ thuộc thư viện ngoài. | ✅ Đã tích hợp sẵn |

⚡ Lưu ý: Bạn không cần cài thêm gì để sử dụng KitSubStack. Các gói này được tích hợp sẵn và hoạt động trực tiếp. Tuy nhiên, nếu muốn, bạn vẫn có thể sử dụng riêng từng module trong các dự án khác, hoặc tích hợp vào workflow tùy chỉnh như: fetch bài → chuyển HTML sang Markdown → tạo YAML front matter → xuất ZIP.

☕ Ủng hộ tác giả

Nếu bạn thấy thư viện hữu ích, bạn có thể ủng hộ:

🧾 License

Phát hành theo MIT License © 2025 Huỳnh Nhân Quốc · Open Source @Kit Module