Chào mừng đến với Notice

Bài đầu tiên: vì sao Notice là một blog tĩnh, nó được dựng bằng gì, và cách mình viết mỗi bài.

Ảnh bìa bài Chào mừng đến với Notice với nền xanh đậm
Ảnh bìa bài Chào mừng đến với Notice với nền xanh đậm

Chào mừng đến với Notice

Notice là chỗ mình ghi lại những gì học được trong lúc làm sản phẩm: một chút Cloudflare, một chút Astro, vài ghi chép về cách viết tài liệu cho chính mình đọc lại sau sáu tháng. Không có thuật toán đề xuất, không có popup xin email, không có nút "đăng ký để xem tiếp". Chỉ có chữ và một vài tệp đính kèm nếu bài viết cần chúng.

Bài đầu tiên này vừa là lời chào, vừa là bản mô tả ngắn về cách trang web vận hành. Nếu bạn tò mò phần kỹ thuật, bài này sẽ nói đủ để bạn dựng lại một hệ thống tương tự vào cuối tuần. Nếu bạn chỉ ghé đọc, phần cuối có danh sách bài nên xem trước.

Vì sao lại là một blog tĩnh?

Mình đã thử ba kiểu blog khác nhau trong khoảng bảy năm. Kiểu đầu là WordPress, kiểu thứ hai là một app Next.js có cơ sở dữ liệu riêng, và kiểu thứ ba — kiểu đang chạy bây giờ — là HTML tĩnh được build sẵn rồi đẩy lên edge.

Bài học rút ra khá đơn giản:

  • Nội dung của một blog cá nhân thay đổi chậm. Vài bài một tháng là nhiều.
  • Thứ thay đổi nhanh là giao diện, và giao diện thì build lại lúc deploy được rồi.
  • Mỗi lớp động bạn thêm vào đều phải trả giá bằng thời gian bảo trì, vá bảo mật và tiền máy chủ.
  • Nếu trang chỉ có chữ, thì một tệp HTML 12 KB nhanh hơn mọi thứ bạn viết bằng JavaScript.

Nói cách khác: blog không cần cơ sở dữ liệu để phục vụ người đọc. Nó chỉ cần cơ sở dữ liệu để soạn bài. Tách hai việc đó ra là ý tưởng chính của Notice.

Notice có gì

Phần soạn thảo là một CMS headless chạy trên Cloudflare Workers, có API để tạo bài, upload ảnh bìa và tệp đính kèm. Phần hiển thị là Astro, build ra HTML tĩnh, deploy lên cùng hạ tầng đó. Không có server nào thức dậy lúc 3 giờ sáng vì một con bot crawl trang.

Thành phần Công nghệ Vai trò
Soạn bài SonicJS trên Workers, D1 Lưu bài, quản lý trạng thái nháp/xuất bản
Tệp đính kèm R2 + route /files/:key PDF, ghi chú markdown, ảnh bìa
Giao diện Astro, output tĩnh Render markdown thành HTML
Phân phối Workers static assets Cache ở edge, không cần máy chủ
Tìm kiếm Chưa có, và có thể không cần Một ô grep trên repo là đủ

Một bài viết trông như thế nào

Mỗi bài là một document với các trường cố định: tiêu đề, slug, tóm tắt, nội dung markdown, ảnh bìa, danh sách tệp đính kèm, tag, tác giả, ngôn ngữ. Bài tiếng Việt và tiếng Anh là hai document riêng, liên kết với nhau bằng trường translationOf. Cách này hơi thủ công nhưng rất dễ hiểu khi bạn mở API ra xem.

Ví dụ, một bài tối giản gửi lên API trông như sau:

{
  "title": "Chào mừng đến với Notice",
  "slug": "chao-mung-den-voi-notice",
  "status": "published",
  "data": {
    "excerpt": "Một bài ngắn về lý do Notice tồn tại.",
    "locale": "vi",
    "tags": ["gioi-thieu", "huong-dan"],
    "author": "lq-khoi"
  }
}

Trường content bị cắt bớt cho dễ đọc. Trong thực tế nó là markdown thuần, đúng như tệp bạn đang đọc.

Tệp đính kèm

Mình thích để tài liệu dài ở dạng PDF hoặc markdown rời thay vì nhồi hết vào bài. Bài này có hai tệp:

  1. huong-dan-tom-tat.pdf — bản một trang, in ra dán lên tường được.
  2. nguon-tham-kieu.md — danh sách nguồn và ghi chú còn dang dở.

Cả hai đều nằm trong R2 và được phục vụ qua /files/. Không có iframe nhúng từ dịch vụ thứ ba, không có trình đọc PDF của bên khác.

Cách mình viết

Quy trình hiện tại gồm bốn bước, và bước thứ ba là bước quan trọng nhất:

  1. Viết nháp trong một tệp markdown, không mở trình soạn thảo web.
  2. Đọc lại sau ít nhất một ngày. Thường sẽ xoá được một phần ba.
  3. Nhờ một người đọc thật, hoặc một mô hình ngôn ngữ đóng vai người đọc thật.
  4. Xuất bản, rồi sửa lỗi chính tả qua API khi phát hiện.

Viết là để hiểu, không phải để được đọc. Nếu một đoạn không giúp bạn hiểu thêm điều gì, nó cũng không giúp người đọc.

Bước 3 hay bị bỏ qua nhất. Mình từng đăng một bài về D1 migration mà không ai đọc thử, và mất hai tuần mới biết câu lệnh trong bài sai thứ tự tham số. Từ đó, mọi bài đều có ít nhất một vòng đọc lại bởi người khác.

Đọc tiếp

Nếu bạn mới đến, ba bài này là điểm bắt đầu hợp lý:

Còn nếu bạn chỉ muốn đọc một bài rồi đi, bài này là đủ. Cảm ơn bạn đã ghé.

Tệp đính kèm

Tải xuống