Kết nối Cloudflare Pages — APMATHS (đợt 0)
Trạng thái: Cloudflare Pages đã kết nối và Jekyll có bản chạy tốt; PR #2 Preview gặp lỗi Ruby/SCSS ngày 11/10/2026. Cấu hình mã nguồn được đề xuất trên nhánh PR #2, chưa merge.
Mục tiêu
Triển khai repository Private APMatHS/apmaths.io.vn lên dự án Cloudflare Pages mới, để kiểm tra giao diện Đợt 0 qua branch preview. Không chạm repo Public APMatHS/apmaths.github.io hoặc DNS của apmaths.io.vn.
Điều kiện đã xác nhận
- Mã nguồn Jekyll có
Gemfilevớigithub-pages. - GitHub Actions đã build Jekyll trên Ruby 3.1 thành công ở PR #1.
- PR #1 đã merge vào
main; PR #2 (feature/learning-practice-ai-clo-hubs) đang chờ preview và nghiệm thu. - Các trang con
/ai-clo/và/tools/của website Public cũ phải giữ nguyên.
Hướng dẫn tạo Pages project
- Vào https://dash.cloudflare.com → Workers & Pages → Create application → Pages → Connect to Git (hoặc Import an existing Git repository).
- Kết nối GitHub, chỉ cấp quyền repository
APMatHS/apmaths.io.vnnếu có thể. - Chọn repository Private
APMatHS/apmaths.io.vnvà đặt project name ví dụapmaths-io-vnnếu chưa bị sử dụng. - Cấu hình:
| Cloudflare Pages option | Giá trị |
|---|---|
| Framework preset | Jekyll |
| Production branch | main |
| Root directory | / |
| Build command | bundle exec jekyll build |
| Build output directory | _site |
| Ruby version | 3.1.3 qua file .ruby-version trong repo; nếu dashboard đặt RUBY_VERSION, phải khớp 3.1.3 ở Production và Preview |
| Preview branches | All non-production branches (mặc định) |
- Lưu và deploy. Xem bản production
*.pages.devdo Cloudflare cấp (đây vẫn là giao diệnmain, không phải Đợt 0). - Mở Deployments/PR #1 tìm preview của branch
design/phase-0-modern-education. Nếu chưa sinh ra khi kết nối do PR đã mở sẵn, hãy tạo một commit mới trên branch đó để kích hoạt build preview. - Khi preview thành công, kiểm tra giao diện desktop/mobile, menu, light/dark, links đến các công cụ.
Quy tắc an toàn
- Không thêm custom domain
apmaths.io.vnvà không chỉnh DNS trước khi bản preview được duyệt. - Không đụng project Pages cũ nếu đang tồn tại; tạo project riêng và kiểm tra tên/URL thực tế.
- Cloudflare Pages preview mặc định có thể truy cập công khai. Nếu cần riêng tư, bật Settings → General → Enable access policy (Cloudflare Access) cho preview. Private GitHub repo không đồng nghĩa website preview riêng tư.
- Không dán Cloudflare API token, service-role key, GitHub token hoặc credential lên chat/repo. Kết nối GitHub bằng giao diện OAuth.
_config.ymlhiện cònurl: https://apmaths.github.io. Không đổi khi chỉ preview; trước khi xuất bản tên miền chính cần chỉnh canonical, sitemap và cấu hình domain ở đợt chuyển tên miền.
Xác minh
- Build logs kết thúc
Success, file_site/index.htmlvà các trang chính có mặt. - Preview URL trỏ đúng commit của branch Đợt 0, không phải
main. - Truy cập
/tools/,/ai-clo/practice/,/tools/z3/, thử CSS/script hiện có và MathJax. - Giữ
https://apmaths.github.io/tools/vàhttps://apmaths.github.io/ai-clo/như cũ.
Tài liệu tham khảo
- https://developers.cloudflare.com/pages/framework-guides/deploy-a-jekyll-site/
- https://developers.cloudflare.com/pages/configuration/git-integration/
- https://developers.cloudflare.com/pages/configuration/preview-deployments/
Khắc phục Cloudflare Preview PR #2: lỗi Ruby 3.4 / Sass
Build log 11/10/2026 trên commit 0e955dd cho thấy Cloudflare sử dụng Ruby 3.4.4 (mặc định môi trường Pages) và thất bại khi Jekyll 3.10.0 biên dịch stylesheet của jekyll-theme-primer:
Conversion error: Jekyll::Converters::Scss encountered an error
Invalid US-ASCII character "\\xE2" on line 5
Tệp assets/css/style.scss xuất hiện ở build nhưng không có trong source tree repo: đây là asset được theme gem cung cấp. Không nên sửa thủ công nội dung gem hay xóa CSS chức năng của website.
Sửa trong repo: thêm .ruby-version với nội dung 3.1.3, đồng thời đồng bộ Ruby CI về phiên bản đó.
Đối chiếu Dashboard: Cloudflare Pages → apmaths-io-vn → Settings → Environment variables: nếu có đặt RUBY_VERSION cho Preview hoặc Production, giá trị phải thống nhất với .ruby-version; đặc biệt không để Preview ở 3.4.4. Dùng bundle exec jekyll build và output _site như trước.
Sau commit: build preview mới và kiểm tra phần đầu log thực sự chạy Ruby 3.1.3; xác nhận kết quả deploy và ba trang /courses/, /practice/, /ai-clo/. Nếu vẫn lỗi cần xem log mới, không báo thành công trước khi Cloudflare xác nhận.