pos-system/apps/web-docs/SIDEBAR_ORDERING.md

Hướng dẫn sắp xếp Documentation Sidebar

📋 Tổng quan

Sidebar navigation có 2 cấp độ sắp xếp:

1. Categories (Guides, Architecture, Skills, v.v.)
2. Items trong mỗi category (các file docs)

🎯 Cách sắp xếp

1. Sắp xếp Categories

Chỉnh sửa trong file: apps/web-docs/src/lib/docs-generator.ts

const CATEGORY_CONFIG = {
    'guides': { order: 1, label: { en: 'Guides', vi: 'Hướng dẫn' } },
    'architecture': { order: 2, label: { en: 'Architecture', vi: 'Kiến trúc' } },
    'skills': { order: 3, label: { en: 'Skills', vi: 'Kỹ năng' } },
    // ...
};

Cách thay đổi:

• Thay đổi order để điều chỉnh vị trí (số nhỏ hơn = cao hơn)
• Thêm category mới với order tương ứng
• Categories không có trong config sẽ có order: 999 (xuất hiện cuối)

2. Sắp xếp Items trong Category

Có 2 loại sắp xếp:

A. Custom Order (Ưu tiên)

Định nghĩa thứ tự cố định cho items quan trọng:

const ITEM_ORDER = {
    'guides': [
        'getting-started',      // Xuất hiện đầu tiên
        'local-development',    // Thứ hai
        'deployment',           // Thứ ba
        // Các file khác sẽ được sắp xếp alphabetically
    ],
    'architecture': [
        'system-design',
        'service-communication',
    ],
    'skills': [
        'project-rules',
        'comment-code',
        'api-design',
    ],
};

Lưu ý:

• Dùng filename (không có extension .md)
• Chỉ liệt kê các file quan trọng cần ưu tiên
• Các file không có trong danh sách sẽ tự động sắp xếp alphabetically ở cuối

B. Alphabetical (Mặc định)

Items không được liệt kê trong ITEM_ORDER sẽ tự động sắp xếp theo alphabet (A-Z).

📝 Ví dụ thực tế

Ví dụ 1: Thêm doc mới "Quick Start"

1. Tạo file: docs/en/guides/quick-start.md
2. Muốn nó xuất hiện đầu tiên? Thêm vào ITEM_ORDER:

const ITEM_ORDER = {
    'guides': [
        'quick-start',          // ← Thêm dòng này
        'getting-started',
        'local-development',
        'deployment',
    ],
};

Ví dụ 2: Thay đổi thứ tự categories

Muốn Skills xuất hiện trước Architecture:

const CATEGORY_CONFIG = {
    'guides': { order: 1, ... },
    'skills': { order: 2, ... },      // ← Từ 3 → 2
    'architecture': { order: 3, ... }, // ← Từ 2 → 3
};

Ví dụ 3: Category mới "Tutorials"

const CATEGORY_CONFIG = {
    // ... existing categories
    'tutorials': { 
        order: 8, 
        label: { en: 'Tutorials', vi: 'Hướng dẫn chi tiết' } 
    },
};

const ITEM_ORDER = {
    // ... existing orders
    'tutorials': [
        'beginner-tutorial',
        'intermediate-tutorial',
        'advanced-tutorial',
    ],
};

🔄 Kết quả

Sidebar sẽ hiển thị:

📁 Guides (order: 1)
  └─ Getting Started (custom order 0)
  └─ Local Development (custom order 1)
  └─ Deployment (custom order 2)
  └─ Advanced Features (alphabetical)
  └─ Best Practices (alphabetical)

📁 Architecture (order: 2)
  └─ System Design (custom order 0)
  └─ Service Communication (custom order 1)
  └─ Database Design (alphabetical)

📁 Skills (order: 3)
  └─ Project Rules (custom order 0)
  └─ Comment Code (custom order 1)
  └─ API Design (custom order 2)
  └─ Testing Patterns (alphabetical)

⚡ Reload để xem thay đổi

Sau khi chỉnh sửa docs-generator.ts:

1. Lưu file
2. Refresh trang web (Ctrl/Cmd + R)
3. Navigation cache sẽ tự động rebuild

🎨 Tips

1. Giữ custom order ngắn gọn: Chỉ liệt kê 3-5 items quan trọng nhất
2. Đặt tên file có ý nghĩa: Alphabetical sorting sẽ hợp lý hơn
3. Consistency: Dùng cùng naming convention cho tất cả files
4. Documentation: Thêm comment giải thích tại sao sắp xếp như vậy

📌 Checklist

Khi thêm doc mới:

• Tạo file .md trong thư mục category phù hợp
• Kiểm tra xem có cần custom order không
• Nếu cần, thêm vào ITEM_ORDER
• Test bằng cách refresh trang
• Kiểm tra cả EN và VI locale

❓ Troubleshooting

Doc không xuất hiện trong sidebar

• Kiểm tra file có extension .md không
• File không được đặt tên là README.md (bị exclude)
• Thư mục category có trong CATEGORY_CONFIG không

Thứ tự không đúng

• Kiểm tra typo trong filename ở ITEM_ORDER
• Đảm bảo dùng filename (không có .md)
• Clear browser cache và hard refresh

Category mới không xuất hiện

• Thêm vào CATEGORY_CONFIG với order phù hợp
• Đảm bảo có ít nhất 1 file .md trong thư mục