Cloudflare Pages Deployment Guide
Hệ thống tài liệu hanoi-docs được thiết kế để triển khai (deploy) hoàn toàn tự động lên Cloudflare Pages thông qua luồng Git Integration. Mỗi khi bạn đẩy code lên nhánh chính (main), Cloudflare sẽ tự động build và cập nhật phiên bản mới nhất.
1. Preparation Steps on Cloudflare
- Truy cập vào dashboard của Cloudflare và đăng nhập.
- Chọn mục Workers & Pages trên thanh công cụ bên trái.
- Nhấp vào nút Create Application -> chọn tab Pages -> nhấp Connect to Git.
- Liên kết tài khoản GitHub của bạn và chọn repository chứa dự án
hackathon2026.
2. Build Configuration on Cloudflare Pages
Khi cấu hình dự án Pages, bạn cần thiết lập các thông số chính xác như sau để build thành công ứng dụng VitePress nằm trong thư mục con:
| Tên trường | Giá trị cấu hình | Giải thích |
|---|---|---|
| Project Name | hanoi-docs | Tên dự án (sẽ tạo URL dạng hanoi-docs.pages.dev) |
| Production Branch | main (hoặc master) | Nhánh kích hoạt deploy tự động |
| Framework Preset | None (hoặc chọn Vite / Vue nếu có) | Không sử dụng cài đặt sẵn mặc định |
| Root Directory | hanoi-docs | Quan trọng: Chỉ định thư mục con chứa dự án VitePress |
| Build Command | npm run docs:build | Lệnh để compile markdown sang HTML tĩnh |
| Build Output Directory | docs/.vitepress/dist | Quan trọng: Đường dẫn tương đối từ Root Directory đến folder dist |
3. Node.js Environment Configuration
VitePress yêu cầu Node.js phiên bản mới (khuyến nghị Node.js >= 18).
- Mặc định Cloudflare Pages sử dụng Node.js v18+.
- Nếu gặp lỗi liên quan đến phiên bản Node cũ hơn, hãy vào mục Settings -> Environment variables của dự án Pages trên Cloudflare và thêm biến môi trường sau:
- Key:
NODE_VERSION - Value:
20(hoặc phiên bản Node.js hiện tại của bạn).
- Key:
4. Post-Deployment Verification
Sau khi cấu hình xong, nhấn Save and Deploy. Cloudflare sẽ khởi chạy máy ảo build dự án:
- Quá trình build thường mất từ 1 - 2 phút.
- Sau khi hoàn tất, bạn sẽ nhận được một URL công khai miễn phí có dạng:
https://hanoi-docs.pages.dev. - Bạn có thể cấu hình tên miền tùy chỉnh (Custom Domain) hoàn toàn miễn phí tại tab Custom domains của dự án Cloudflare Pages.