Site tài liệu

Thư mục site/ là một site Hugo dùng theme Hextra. Nó biến tài liệu của repo, các bài học, lộ trình, các file giai đoạn, sơ đồ và nhật ký thành một site duyệt được, có trang chủ và tìm kiếm. Phần code không nằm trong site, nên repo GitHub vẫn có thể để private trong khi site được công khai.

Nội dung đến từ đâu

Không có gì được sao chép vào site/. site/hugo.toml mount các thư mục sẵn có, nên mỗi file chỉ có một nguồn.

Viết nội dung cho site

• Mở đầu mỗi tài liệu bằng YAML front matter có title và weight. weight quyết định thứ tự trong thanh bên. Bài học dùng số thứ tự giai đoạn nhân 10, nên docs/learning/01-foundation-and-observability-spine.md có weight: 10 và docs/learning/02.1-sqlc-store.md có weight: 21. Weight trong Hugo là số nguyên, và hai trang cùng weight được sắp theo title, nên một giai đoạn chèn thêm như 2.1 cần hệ số 10 để nằm giữa 2 và 3.
• Giữ dòng # Title bên dưới front matter để markdown lint và việc đọc thô đều ổn. site/layouts/_markup/render-heading.html ẩn H1 nếu nó lặp lại tiêu đề trang.
• File giai đoạn có weight bằng phase nhân 10, vì cùng lý do đó.
• Liên kết giữa các file bằng đường dẫn .md tương đối. Hugo tự viết lại các liên kết tới trang nó biết.

Ngôn ngữ

Site có tiếng Anh và tiếng Việt. Tiếng Anh là mặc định, nằm ở /. Tiếng Việt nằm ở /vi/, và thanh điều hướng có nút chuyển ngôn ngữ. site/hugo.toml chứa nhãn menu cho từng ngôn ngữ, còn theme Hextra tự cung cấp các chuỗi giao diện tiếng Việt. site/i18n/en.yaml và site/i18n/vi.yaml ghi đè hoặc bổ sung vài chuỗi giao diện mà Hextra thiếu, như close.

Một trang tiếng Việt là file <name>.vi.md đặt cạnh file tiếng Anh <name>.md. Các mount sẵn có tự nhận file này, nên khi thêm trang mới không cần sửa cấu hình.

• Dịch title trong front matter. Giữ weight và mọi khóa khác giống file tiếng Anh.
• Không dịch code block, inline code, lệnh, đường dẫn file, biến môi trường hay URL.
• Giữ các thuật ngữ kỹ thuật như agent, harness, tenant, middleware, provider, run, span, trace, query, escape hatch, revoke và rotate bằng tiếng Anh. Người đọc sẽ gặp lại những từ này trong code và công cụ.
• Giữ liên kết tương đối trỏ tới tên file tiếng Anh, ví dụ roadmap.md. Hugo tự dẫn tới trang cùng ngôn ngữ.
• Giữ cùng cấp heading và thứ tự heading để mục lục khớp nhau ở cả hai ngôn ngữ. Liên kết #anchor trong cùng trang của một file .vi.md phải dùng slug của heading đã dịch.

Khi một trang tiếng Anh thay đổi, cập nhật file .vi.md tương ứng trong cùng pull request. Mỗi bài học và bài nhật ký mới đều đi kèm một file .vi.md. ak journal create chỉ viết tiếng Anh, nên hãy tự viết file tiếng Việt sau đó. Các sơ đồ SVG chỉ có tiếng Anh và cả hai ngôn ngữ dùng chung các file đó.

Xem thử trên máy

brew install hugo   # needs Hugo extended 0.146 or later (the minimum Hextra v0.13.0 declares), plus Go for Hugo modules
cd site
hugo server         # http://localhost:1313

Deploy lên Cloudflare Pages

Build từ repo private bằng tích hợp Git của Cloudflare, dùng được trên gói miễn phí:

1. Trong dashboard của Cloudflare, mở Workers & Pages, tạo một dự án Pages và kết nối repo GitHub.
2. Đặt thư mục gốc là site, lệnh build là hugo --gc --minify, và thư mục output là public.
3. Thêm biến môi trường HUGO_VERSION=0.168.0 (phiên bản được ghim và đã kiểm thử) và GO_VERSION=1.27.2. Cần Go để tải theme module.
4. Mỗi lần push lên main sẽ deploy. Các branch khác nhận URL xem trước.

Để deploy mà không dùng tích hợp Git, build trên máy rồi tải output lên:

cd site
hugo --gc --minify
npx wrangler pages deploy public --project-name hango

Site đang chạy tại hango.phi.me, một tên miền riêng trên dự án Pages hango. Một bản ghi CNAME có proxy từ hango tới hango-9ju.pages.dev trong zone phi.me trỏ tên miền về đó. Cập nhật baseURL trong site/hugo.toml nếu đổi tên miền. Nếu sau này muốn giới hạn người đọc, đặt Cloudflare Access phía trước site. Gói Zero Trust miễn phí hỗ trợ tối đa 50 người dùng.