Cách đóng góp nội dung

Trang này thuộc loại cách làm (how-to): làm theo từng bước để thêm hoặc sửa một trang.

Điều kiện tiên quyết

Node.js 20 trở lên và pnpm.
Đã cài phụ thuộc: pnpm install.

1. Chạy wiki ở máy

pnpm dev

Mở http://localhost:4321. Sửa file trong src/content/docs/ là trình duyệt tự nạp lại.

2. Tạo file mới

Mỗi file .md / .mdx trong src/content/docs/ thành một trang, đường dẫn lấy theo đường dẫn file:

src/content/docs/ky-thuat/git-workflow.md   ->   /ky-thuat/git-workflow/

Quy ước đặt tên:

Chữ thường, không dấu, nối bằng dấu gạch ngang: xu-ly-su-co.md.
Đặt file vào thư mục nhóm đã có; chỉ tạo nhóm mới khi có từ ba trang trở lên.
Dùng .md cho nội dung thường; chỉ dùng .mdx khi cần component (Tabs, Steps, Card…).

3. Khai báo frontmatter

---
title: Tiêu đề trang
description: Một câu mô tả — hiện trong kết quả tìm kiếm và thẻ chia sẻ.
sidebar:
  order: 3           # thứ tự trong nhóm, số nhỏ lên trước
  label: Tên ngắn    # tuỳ chọn, khi title quá dài cho sidebar
---

Frontmatter hay dùng thêm:

Trường	Tác dụng
`template: splash`	Trang giới thiệu, ẩn sidebar và mục lục.
`sidebar.badge`	Gắn nhãn cạnh mục, ví dụ `{ text: Mới, variant: tip }`.
`tableOfContents: false`	Ẩn mục lục bên phải với trang ngắn.
`draft: true`	Bản nháp: hiện khi chạy `pnpm dev`, không xuất hiện trong bản build.

Các nhóm ky-thuat, quy-trinh, wiki dùng autogenerate — file mới tự lên sidebar, thứ tự theo sidebar.order. Riêng nhóm AWS được liệt kê tay trong astro.config.mjs; thêm chương mới thì bổ sung slug vào đúng mục con.

5. Kiểm tra trước khi commit

pnpm build

Checklist:

pnpm build chạy sạch, không lỗi frontmatter hay component.
Có title và description; description viết thành câu hoàn chỉnh.
Trang thuộc đúng một loại tài liệu, không trộn hướng dẫn với tra cứu.
Liên kết nội bộ dùng đường dẫn tuyệt đối, có dấu / cuối: /ky-thuat/code-review/.
Khối mã có tên ngôn ngữ và đã chạy thử.

6. Commit

Dùng Conventional Commits, phạm vi là tên nhóm tài liệu:

git commit -m "docs(ky-thuat): them ghi chu ve git rebase"