Workflow quản lý tài liệu (File-System)

Sau khi rollback bỏ qua Supabase Database cho nội dung tài liệu, chúng ta chuyển sang quy trình quản lý 100% dựa trên File-System và Git. Dưới đây là các bước chi tiết để thêm hoặc cập nhật tài liệu.

"Bài toán" & Giải pháp

Vấn đề: Việc đồng bộ (sync) giữa file Markdown local và Database gây phức tạp không cần thiết, dễ lỗi slug hoặc id khi deploy. Giải pháp: Sử dụng File-System làm "Single Source of Truth". Next.js sẽ đọc trực tiếp file .md tại build time (SSG) hoặc runtime.

Quy trình thêm bài viết mới

Bước 1: Xác định vị trí (Category)

Truy cập thư mục src/data/docs. Chọn thư mục con tương ứng với chủ đề (VD: frontend, backend, n8n-automation).

Nếu muốn tạo chủ đề mới:

1. Tạo thư mục mới trong src/data/docs/[new-topic].
2. Tạo file src/data/docs/[new-topic]/index.md để định nghĩa metadata cho Category.

Bước 2: Tạo file Markdown

Tạo file .md với tên URL-friendly. Ví dụ: src/data/docs/n8n-automation/07-backup-workflows.md

Bước 3: Khai báo Frontmatter

Bắt buộc phải có block Frontmatter ở đầu file:

---
title: "Hướng dẫn Backup Workflow"
description: "Cách tự động sao lưu config n8n ra Google Drive."
order: 7
track: "backend"      # Optional: frontend | backend | general
category: "n8n-automation" # Optional: Tự động nhận diện theo folder
level: "Intermediate" # Optional: Beginner | Intermediate | Advanced
---

Bước 4: Viết nội dung

Sử dụng Markdown chuẩn. Hệ thống hỗ trợ:

• Code highlighting
• Tables
• Images
• Links

Bước 5: Commit & Deploy

1. git add .
2. git commit -m "docs: add backup workflow guide"
3. git push

Hệ thống CI/CD sẽ tự động build lại trang web. Vì getAllDocs giờ đây đọc file trực tiếp, nội dung mới sẽ xuất hiện ngay lập tức (sau khi build xong).

Quy trình cập nhật Metadata (Menu)

Menu bên trái (Sidebar) được tạo tự động dựa trên:

1. CATEGORY_CONFIG trong src/features/docs/domain/constants.ts (để lấy icon, màu sắc).
2. Tên file hoặc order trong Frontmatter (để sắp xếp thứ tự bài).

Nếu bạn thấy Menu chưa cập nhật tên đúng:

• Kiểm tra lại title trong Frontmatter.
• Đảm bảo file docs.api.ts đã được un-comment phần đọc file-system (đã thực hiện ở Bước fix trước).