Hướng dẫn đăng một bài viết
Written by Le Cong Hieu-On Jan 8, 2026-
tutorial
Tài liệu này hướng dẫn cách tạo và tổ chức một bài viết trong hệ thống, bao gồm cấu trúc thư mục, quy tắc đặt tên và cấu trúc nội dung bài viết.
Điều kiện tiên quyết
Trước khi bắt đầu, hãy đảm bảo bạn đã đáp ứng các yêu cầu kỹ thuật sau:
- Quyền truy cập: Có khả năng truy cập và cập nhật code trên repository:
git@gitlab.base.vn:hieu.le02/api-docs.git - Môi trường local: Để kiểm tra bài viết trước khi đăng, hãy thực hiện:
- Pull code mới nhất từ nhánh
master. - Truy cập thư mục
api-docs - Cài đặt dependencies:
npm install. - Chạy môi trường phát triển:
npm run dev. - Truy cập: http://localhost:3000 để xem trước thay đổi.
- Pull code mới nhất từ nhánh
1. Tổng quan
Một bài viết:
- Được viết dưới định dạng
.mdhoặc.mdx - Được lưu trong thư mục
contents/ - Có metadata ở đầu file
- Hình ảnh minh họa được đặt trong
public/images/
2. Cấu trúc thư mục
- Mỗi bài viết là một file
.mdhoặc.mdx - File nằm trong thư mục
contents/ - Có thể được nhóm theo chủ đề bằng cách tạo thư mục con
2.1 Quy ước đặt tên file
- Viết thường
- Các từ được phân cách bằng
-hoặc_
Ví dụ hợp lệ
huong-dan.mdhướng_dẫn.md
Ví dụ không hợp lệ
hướng dẫn.md
2.2 Ví dụ cấu trúc thư mục đầy đủ
3 Cấu trúc nội dung file
Một file bài viết tiêu chuẩn bao gồm hai phần chính: Metadata và Nội dung.
3.1 Phần Metadata
Phần này khai báo thông tin bài viết cho hệ thống (SEO, hiển thị danh sách). Phải đặt ở ngay đầu file.
| Trường | Bắt buộc | Mô tả |
|---|---|---|
title | ✅ | Tiêu đề bài viết |
description | ❌ | Mô tả ngắn nội dung |
author | ❌ | Tên tác giả |
date | ❌ | Ngày đăng (ISO 8601) |
tags | ❌ | Danh sách tag |
3.2 Phần Nội dung
Sử dụng cú pháp Markdown thông thường bên dưới phần metadata.
4. Cách đăng bài (Quy trình Deployment)
Hệ thống sử dụng cơ chế CI/CD tự động. Để xuất bản bài viết, bạn thực hiện theo các bước sau:
Bước 1: Chuẩn bị nội dung
- Tạo file .md hoặc .mdx theo cấu trúc tại Mục 2 và Mục 3.
- Đảm bảo hình ảnh đã được đặt đúng trong thư mục public/images/.
Bước 2: Commit và Push
Sử dụng Git để lưu các thay đổi và gửi lên server:
Bước 3: Tự động hóa (Trigger Build)
- Sau khi bạn commit lên nhánh master trên GitLab, hệ thống sẽ tự động kích hoạt (trigger) luồng build.
- Bạn có thể theo dõi tiến độ tại phần CI/CD > Pipelines trên giao diện Jenkinsv3
Bước 4: Kiểm tra kết quả
- Sau khi Pipeline báo passed, nội dung sẽ tự động được cập nhật (publish) lên domain chính thức: api-docs.basevn.tech
💡 Lưu ý quan trọng:
- Kiểm tra kỹ nhánh: Chỉ những commit trên nhánh master mới được triển khai lên domain chính thức. Các nhánh khác thường chỉ dùng để preview hoặc lưu trữ tạm thời.
- Thời gian cập nhật: Quá trình build và deploy thường mất từ 1-2 phút tùy vào khối lượng nội dung thay đổi.
Ví dụ tham khảo
Bài viết này có nội dung như sau: