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.

4. Thêm vào sidebar

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"

Đừng commit thư mục build

dist/ và .astro/ là sản phẩm sinh ra khi build, không đưa vào git.