Tạo và Vận Hành Dự Án VitePress với ServBay

VitePress là một trình tạo website tĩnh hiện đại, được xây dựng trên nền tảng Vue, tối ưu cho việc tạo website tài liệu nhanh, đẹp và dễ bảo trì. Dựa trên Vite, VitePress cung cấp trải nghiệm phát triển vượt trội và hiệu suất build tối ưu. Đối với các nhà phát triển đang muốn tạo tài liệu chuyên nghiệp cho dự án, thư viện hay sản phẩm, VitePress là một lựa chọn xuất sắc.

Khi phát triển và kiểm thử VitePress tại máy local, một môi trường web ổn định, dễ cấu hình là rất quan trọng. ServBay ra đời để đáp ứng nhu cầu này với khả năng tích hợp nhiều phiên bản Node.js cũng như máy chủ web mạnh mẽ như Caddy hoặc Nginx, giúp bạn dễ dàng triển khai dự án VitePress của mình.

Bài viết này sẽ hướng dẫn cách tận dụng môi trường tích hợp của ServBay để khởi tạo, cấu hình và chạy dự án VitePress từ con số 0, bao gồm thiết lập proxy ngược cho server phát triển và dịch vụ file tĩnh cho bản build production.

VitePress là gì?

VitePress là một trình tạo website tĩnh (SSG) dựa trên Vite, tận dụng sức mạnh của Vue 3 và hiệu suất cực nhanh của Vite để xây dựng website tĩnh, đặc biệt thích hợp cho website tài liệu kỹ thuật.

Tính năng và ưu điểm nổi bật của VitePress

• Trải nghiệm phát triển cực nhanh: Nhờ vào HMR (Hot Module Replacement) của Vite, mọi thay đổi được cập nhật gần như ngay lập tức trên trình duyệt, tối ưu hiệu quả lập trình.
• Hỗ trợ mạnh mẽ bởi Vue: Cho phép sử dụng trực tiếp các component Vue trong file Markdown, tăng tính tương tác và trực quan cho tài liệu.
• Đơn giản, dễ dùng: Cấu hình trực quan, sẵn sàng sử dụng, tập trung vào việc sáng tạo nội dung.
• Hiệu suất cao: File tĩnh xuất ra nhẹ, tốc độ tải nhanh, kết hợp router client tích hợp mang lại trải nghiệm SPA mượt mà.
• Thân thiện với SEO: HTML được tạo ra tối ưu cho công cụ tìm kiếm và hỗ trợ meta tag tuỳ chỉnh.
• Tăng cường Markdown: Hỗ trợ toàn diện chuẩn CommonMark và GitHub Flavored Markdown (GFM), đồng thời mở rộng cú pháp tiện dụng.

Với VitePress, bạn có thể dễ dàng xây dựng website tài liệu chất lượng cao và hiệu năng tối ưu.

Tạo và Chạy Dự Án VitePress bằng ServBay

ServBay mang đến giải pháp tiện lợi để quản lý phiên bản Node.js và cấu hình máy chủ web cho dự án VitePress, dù là ở chế độ development với server local hay production với file tĩnh.

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

Trước khi bắt đầu, hãy đảm bảo bạn đã hoàn tất các bước sau:

1. Cài đặt ServBay: Đảm bảo ServBay đã được cài đặt thành công trên macOS của bạn. Nếu chưa, xem hướng dẫn cài đặt ServBay.
2. Cài đặt gói Node.js: Trong ServBay, kiểm tra đã cài và kích hoạt đúng phiên bản Node.js cần thiết. Quản lý tại tab "Phần mềm" trong bảng điều khiển ServBay. Tham khảo Hướng dẫn sử dụng Node.js.

Khởi tạo dự án VitePress

1. Tạo thư mục dự án

   Mở Terminal. Bạn nên tạo thư mục dự án ngay tại thư mục gốc website của ServBay: /Applications/ServBay/www để tiện cấu hình website sau này.

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. Cài đặt VitePress và khởi tạo cấu hình

   Trong thư mục dự án servbay-vitepress-app, sử dụng npm hoặc yarn để cài VitePress như devDependency và chạy lệnh khởi tạo.

   npm add -D vitepress
   npx vitepress init

   Hoặc dùng Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Lệnh khởi tạo sẽ hướng dẫn bạn thiết lập một số thông tin cơ bản như tiêu đề trang, mô tả website, v.v. Nhập theo hướng dẫn:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Thư mục tài liệu mặc định, nhấn Enter để dùng.
    │
    ◇  Site title:
    │  Demo VitePress với ServBay # Nhập tiêu đề site, ví dụ Demo VitePress với ServBay
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Nhập mô tả website
    │
    ◇  Theme:
    │  Default Theme # Chọn theme, giữ mặc định
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Chọn Yes hoặc No tuỳ thích
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Khuyên dùng Yes để thêm script vào package.json
    │
    └  Done! Now run npm run docs:dev and start writing.

   Sau khi hoàn thành, VitePress sẽ tạo thư mục con docs với các file cấu hình mặc định (.vitepress) và các trang mẫu (index.md, guide/index.md, ...). File package.json sẽ có thêm scripts như docs:dev, docs:build.

Thay đổi nội dung dự án VitePress

1. Chỉnh sửa nội dung trang chủ

   File trang chủ mặc định của VitePress nằm tại docs/index.md. Dùng editor bất kỳ để mở và thay nội dung, ví dụ:

   # Xin chào ServBay!
   
   Chào mừng bạn sử dụng ServBay để vận hành trang tài liệu VitePress của mình.
   
   Đây là site demo local được xây dựng bằng VitePress và phục vụ qua ServBay.

Chạy ở chế độ phát triển

Khi phát triển, bạn nên dùng server dev nội bộ của VitePress để tận hưởng tính năng reload nóng (hot reload). Sau đó, sử dụng proxy ngược của ServBay để truy cập website qua domain tùy chỉnh, được hỗ trợ SSL.

1. Khởi động server phát triển của VitePress

   Mở Terminal, đảm bảo bạn đang ở /Applications/ServBay/www/servbay-vitepress-app. Chạy lệnh sau để bật dev server ở port 8585:

   npm run docs:dev -- --port 8585

   Hoặc với Yarn:

   yarn docs:dev --port 8585

   Server sẽ lắng nghe tại địa chỉ cục bộ (thường là http://localhost:8585).

2. Cấu hình website trên ServBay (proxy ngược)

   Mở bảng điều khiển ServBay, vào tab "Website", thêm mới một website:

   • Tên: Đặt tên dễ phân biệt, ví dụ VitePress Development.
   • Tên miền: Nhập domain local mong muốn (khuyến nghị hậu tố .servbay.demo, ví dụ vitepress-dev.servbay.demo).
   • Loại website: Chọn Proxy ngược.
   • IP: Điền 127.0.0.1.
   • Cổng: Điền trùng port đã khởi chạy, ví dụ 8585.

   Lưu và áp dụng thay đổi. ServBay sẽ tự động cấu hình máy chủ web (Caddy hoặc Nginx) để chuyển hướng traffic từ https://vitepress-dev.servbay.demo đến http://127.0.0.1:8585.

3. Truy cập website phát triển

   Mở trình duyệt, vào https://vitepress-dev.servbay.demo. Bạn sẽ thấy nội dung website VitePress đang được serve từ dev server, qua domain tùy chỉnh do ServBay cấp phát SSL tự động.

Build bản production

Khi website sẵn sàng, bạn cần build phiên bản tĩnh tối ưu để triển khai.

1. Build bản production

   Từ thư mục dự án /Applications/ServBay/www/servbay-vitepress-app, chạy:

   npm run docs:build

   Hoặc với Yarn:

   yarn docs:build

   Kết quả build sẽ được xuất ra ở docs/.vitepress/dist gồm các file tĩnh HTML, CSS, JS tối ưu.

2. Cấu hình ServBay website (dịch vụ file tĩnh)

   Website VitePress production này chỉ gồm các file tĩnh, nên có thể được serve trực tiếp bởi ServBay Static File Service.

   Trên bảng điều khiển:

   • Tên: Đặt ví dụ VitePress Production.
   • Tên miền: Nhập domain local, ví dụ vitepress-prod.servbay.demo.
   • Loại website: Chọn Static.
   • Thư mục gốc: Điền đường dẫn tuyệt đối tới folder các file build: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Lưu và áp dụng. ServBay cấu hình máy chủ web để serve trực tiếp từ thư mục này.

3. Truy cập website production

   Truy cập https://vitepress-prod.servbay.demo trên trình duyệt sẽ thấy site bản production hoàn chỉnh. Tên miền tùy chỉnh kèm SSL do ServBay cấp phát tự động.

Chạy ở chế độ Clean URL (cleanUrls: true)

VitePress hỗ trợ cleanUrls: true, giúp URL gọn gàng hơn (bỏ ".html", ví dụ /about thay vì /about.html hoặc /guide/ thay cho /guide/index.html). Để máy chủ web xử lý loại URL này, bạn cần cấu hình thêm.

ServBay dùng Caddy hoặc Nginx làm web server. Dưới đây là ví dụ cấu hình cho Caddy, tận dụng chỉ thị try_files thử tìm file có đuôi .html hoặc trong thư mục index.html.

1. Kích hoạt cleanUrls trong cấu hình VitePress

   Chỉnh sửa file config của VitePress (docs/.vitepress/config.mts hoặc docs/.vitepress/config.ts), thêm mục cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... cấu hình khác
     cleanUrls: true, // Bật Clean URL
     // ... cấu hình khác
   })

   Sau đó build lại bằng npm run docs:build.

2. Cấu hình website ServBay (tùy chỉnh với Caddy)

   Mở bảng điều khiển, tìm website production (ví dụ vitepress-prod.servbay.demo).

   • Bấm chỉnh sửa.
   • Tick chọn Cấu hình tuỳ chỉnh.
   • Dán nội dung sau vào khung cấu hình Caddy và thay thế domain/path phù hợp:

   # Thay địa chỉ domain thật, ví dụ vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Kích hoạt nén Brotli (zstd) và Gzip giúp tải nhanh
       encode zstd gzip
   
       # Import cấu hình log mặc định của ServBay (hữu ích khi debug)
       import set-log vitepress-cleanurl.servbay.demo
   
       # Xử lý SSL nội bộ tự động
       tls internal
   
       # Cấu hình chính: thử tìm file
       # 1. Thử path trực tiếp (e.g., /about -> /about)
       # 2. Thử path/index.html (e.g., /guide/ -> /guide/index.html)
       # 3. Thử path.html (e.g., /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Chỉ định thư mục gốc static file
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Bật dịch vụ file tĩnh
       file_server
   }

   Lưu và áp dụng cấu hình.

3. Truy cập website ở chế độ Clean URL

   Trên trình duyệt, mở https://vitepress-cleanurl.servbay.demo. Giờ bạn có thể truy cập các trang mà không cần đuôi .html, ví dụ https://vitepress-cleanurl.servbay.demo/about.

Tổng kết

Qua hướng dẫn này, bạn đã nắm được cách tạo, phát triển và triển khai website tài liệu VitePress với môi trường ServBay. ServBay giúp đơn giản hóa việc quản lý Node.js và cấu hình web server local, phục vụ nhu cầu phát triển (proxy ngược) lẫn production (file tĩnh) – kèm domain tùy chỉnh và SSL tiện lợi tự động.

Kết hợp sức mạnh của ServBay và VitePress, bạn có thể xây dựng và duy trì tài liệu kỹ thuật chất lượng cao, chuyên nghiệp và tiết kiệm thời gian hơn bao giờ hết.