Tạo và chạy dự án VitePress với ServBay

VitePress là một trình tạo website tĩnh hiện đại, vận hành bởi Vue, được thiết kế chuyên biệt để xây dựng các website tài liệu nhanh, đẹp và dễ bảo trì. Dựa trên nền tảng Vite, VitePress mang lại trải nghiệm phát triển tuyệt vời và hiệu năng xuất sắc. Với các lập trình viên cần xây dựng tài liệu chuyên nghiệp cho dự án, thư viện hay sản phẩm, VitePress là sự lựa chọn hàng đầu.

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

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

VitePress là gì?

VitePress là một trình tạo website tĩnh (SSG) dựa trên Vite, kết hợp sức mạnh của Vue 3 và hiệu năng tuyệt vời của Vite để xây dựng các trang web tĩnh – nổi bật là tài liệu kỹ thuật.

Những đặc điểm nổi bật của VitePress

Trải nghiệm phát triển siêu tốc: Nhờ có Hot Module Replacement (HMR) từ Vite, mọi chỉnh sửa đều hiện lên gần như tức thì trong trình duyệt, tăng hiệu suất làm việc.
Sức mạnh từ Vue: Hỗ trợ sử dụng trực tiếp các thành phần Vue trong file Markdown, giúp tài liệu sống động và linh hoạt.
Dễ sử dụng: Cấu hình đơn giản, sẵn sàng sử dụng, tập trung tối đa vào viết nội dung.
Hiệu năng cao: Tệp tĩnh được tạo ra rất nhẹ, tải nhanh, kết hợp router phía client mang lại trải nghiệm mượt như ứng dụng một trang.
Thân thiện SEO: HTML thành phẩm tối ưu cho máy tìm kiếm quét dữ liệu, hỗ trợ tuỳ chỉnh thẻ meta.
Markdown nâng cao: Tương thích hoàn toàn với CommonMark và GitHub Flavored Markdown (GFM) cùng nhiều cú pháp bổ sung.

Với VitePress, bạn dễ dàng xây dựng website tài liệu chất lượng, hiệu năng cao chỉ bằng vài thao tác đơn giản.

Tạo và chạy dự án VitePress với ServBay

ServBay cung cấp giải pháp quản lý phiên bản Node.js tiện lợi và cấu hình máy chủ web linh hoạt để phục vụ mọi nhu cầu từ phát triển đến triển khai website tài liệu VitePress.

Điều kiện cần thiết

Trước khi bắt đầu, hãy đảm bảo những mục sau đã được chuẩn bị:

Cài đặt ServBay: Máy của bạn đã cài đặt thành công ServBay. Nếu chưa, xem hướng dẫn Cài đặt ServBay.
Cài đặt Node.js: Trong ServBay, hãy kiểm tra và bật đúng phiên bản Node.js cần thiết. Việc này thực hiện dễ dàng qua mục "Phần mềm" trên bảng điều khiển ServBay. Xem thêm Sử dụng Node.js.

Khởi tạo dự án VitePress

Tạo thư mục dự án
Mở cửa sổ terminal của bạn. Nên đặt thư mục dự án bên trong thư mục gốc website mặc định của ServBay để tiện cấu hình sau này.
macOS:
bash
```
cd /Applications/ServBay/www
mkdir servbay-vitepress-app
cd servbay-vitepress-app
```
1
2
3
Windows:
cmd
```
cd C:\ServBay\www
mkdir servbay-vitepress-app
cd servbay-vitepress-app
```
1
2
3

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

Trong thư mục servbay-vitepress-app, dùng npm hoặc yarn cài đặt VitePress theo dạng phụ thuộc phát triển, rồi thực hiện lệnh khởi tạo:

bash

npm add -D vitepress
npx vitepress init

Hoặc sử dụng Yarn:

bash

yarn add -D vitepress
yarn vitepress init

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

 ┌  Chào mừng đến với VitePress!
 │
 ◇  VitePress nên tạo cấu hình ở đâu?
 │  ./docs  # Thư mục tài liệu mặc định, nhấn Enter để xác nhận
 │
 ◇  Tiêu đề website:
 │  ServBay VitePress Demo # Nhập tiêu đề website, ví dụ ServBay VitePress Demo
 │
 ◇  Mô tả website:
 │  A VitePress site running on ServBay # Nhập mô tả cho website
 │
 ◇  Chủ đề (Theme):
 │  Default Theme # Chọn theme mặc định
 │
 ◇  Dùng TypeScript cho file cấu hình và theme?
 │  Yes # Tùy chọn, chọn theo sở thích
 │
 ◇  Thêm script VitePress vào package.json?
 │  Yes # Nên chọn Yes để thêm script tiện sử dụng
 │
 └  Đã xong! Giờ hãy chạy npm run docs:dev và bắt đầu viết tài liệu.

Sau khi hoàn tất, VitePress sẽ tạo thư mục docs bên trong dự án, với các file cấu hình mặc định (.vitepress) và trang ví dụ (index.md, guide/index.md...). Đồng thời, file package.json sẽ có thêm các script tiện lợi như docs:dev và docs:build.

Chỉnh sửa nội dung dự án VitePress

Sửa nội dung trang chủ

File trang chủ mặc định của VitePress nằm ở docs/index.md. Mở file này bằng trình soạn thảo và chỉnh sửa theo ý muốn. Ví dụ:

markdown

# Hello ServBay!

Chào mừng bạn đã sử dụng ServBay để vận hành website tài liệu VitePress.

Đây là một trang demo đơn giản tạo bằng VitePress và cung cấp qua ServBay.

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

Quá trình phát triển website VitePress thường sử dụng server phát triển tích hợp sẵn với khả năng tự động cập nhật nóng, giúp xem nhanh thay đổi. Kết hợp tính năng proxy ngược của ServBay, bạn có thể truy cập website bằng tên miền tùy chỉnh và sử dụng SSL bảo mật.

Khởi động server phát triển VitePress
Trên terminal, đảm bảo bạn đang ở thư mục dự án (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app). Chạy lệnh sau để mở server và đặt cổng (vd: 8585):
bash
```
npm run docs:dev -- --port 8585
```
1
Hoặc dùng Yarn:
bash
```
yarn docs:dev --port 8585
```
1
Server sẽ chạy tại địa chỉ cục bộ, thường là http://localhost:8585.
Cấu hình website trên ServBay (Proxy ngược)
Mở bảng điều khiển ServBay, vào mục "Website" và thêm mới cấu hình:
- Tên: Nhập tên dễ nhận diện, ví dụ Website phát triển VitePress.
- Tên miền: Đặt tên miền truy cập cục bộ, nên dùng đuôi .servbay.demo, ví dụ: vitepress-dev.servbay.demo.
- Kiểu website: Chọn Proxy ngược.
- IP: Ghi 127.0.0.1 (localhost).
- Cổng: Nhập cổng vừa chọn, ví dụ 8585.
Lưu, áp dụng các thay đổi. ServBay sẽ tự động cấu hình máy chủ web (Caddy/Nginx) để chuyển hướng truy cập https://vitepress-dev.servbay.demo về http://127.0.0.1:8585.
Truy cập website phát triển
Giờ bạn có thể mở browser và vào địa chỉ https://vitepress-dev.servbay.demo để xem website VitePress đang chạy. Bạn được cấp chứng chỉ SSL do ServBay User CA phát hành, truy cập an toàn qua HTTPS bằng tên miền tuỳ chỉnh.

Xây dựng bản phát hành (production)

Khi đã hoàn thiện tài liệu, bạn chỉ cần tạo bản tĩnh tối ưu để triển khai chính thức.

Tạo bản production
Vào thư mục dự án và chạy lệnh sau:
bash
```
npm run docs:build
```
1
Hoặc dùng Yarn:
bash
```
yarn docs:build
```
1
Quá trình build sẽ biên dịch Markdown, component Vue, v.v., đóng gói thành các file HTML, CSS, JS tĩnh tối ưu. Thành phẩm nằm ở docs/.vitepress/dist trong thư mục dự án.
Cấu hình website trên ServBay (Dịch vụ file tĩnh)
Website VitePress production là tập hợp các tệp tĩnh, có thể phục vụ trực tiếp bằng chức năng file tĩnh của ServBay.
Trên bảng điều khiển ServBay, vào "Website" và thêm cấu hình mới:
- Tên: Nhập tên nhận diện, ví dụ Website production VitePress.
- Tên miền: Đặt tên miền cục bộ để truy cập, ví dụ: vitepress-prod.servbay.demo.
- Kiểu website: Chọn Tĩnh.
- Thư mục gốc website: Điền đường dẫn tuyệt đối tới folder tệp tĩnh vừa build:
  - macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
  - Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
Lưu, áp dụng. ServBay sẽ cấu hình máy chủ web phục vụ trực tiếp các tệp này.
Truy cập website production
Truy cập tên miền vừa cấu hình, ví dụ https://vitepress-prod.servbay.demo, để xem website VitePress bản phát hành với chip SSL tự động và tên miền riêng.

Sử dụng chế độ URL sạch (`cleanUrls: true`)

VitePress hỗ trợ cleanUrls: true, nghĩa là liên kết trang sẽ không hiện đuôi .html (vd: /guide/ thay vì /guide/index.html, hoặc /about thay cho /about.html). Máy chủ web cần cấu hình bổ sung để xử lý URL dạng này.

ServBay dùng Caddy hoặc Nginx làm máy chủ. Sau đây là ví dụ cấu hình cho Caddy sử dụng chỉ thị try_files để thử tìm kiếm file phù hợp (.html hoặc index.html).

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

Sửa file cấu hình VitePress (docs/.vitepress/config.mts hoặc docs/.vitepress/config.ts), thêm/sửa mục cleanUrls:

typescript

// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  // ... các cấu hình khác
  cleanUrls: true, // Bật chế độ URL sạch
  // ... các cấu hình khác
})

Build lại dự án với npm run docs:build.

Cấu hình website ServBay (tùy chỉnh Caddy)

Mở bảng điều khiển ServBay, tìm website production (vd: vitepress-prod.servbay.demo):

Chọn chỉnh sửa.
Check Cấu hình tùy chỉnh.
Trong vùng Cấu hình Caddy, nhập đoạn cấu hình sau (nhớ thay tên miền và đường dẫn thực tế của bạn):
- macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
- Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

bash

# Thay thế bằng tên miền thực dùng, ví dụ: vitepress-cleanurl.servbay.demo
vitepress-cleanurl.servbay.demo {
    # Bật nén Brotli (zstd), Gzip để tải nhanh
    encode zstd gzip

    # Nhập cấu hình log mặc định của ServBay để debug
    import set-log vitepress-cleanurl.servbay.demo

    # Tự động xử lý chứng chỉ SSL nội bộ
    tls internal

    # Cốt lõi: thử tìm file phù hợp
    # 1. Thử path gốc (vd: /about -> /about)
    # 2. Thử index.html trong thư mục (vd: /guide/ -> /guide/index.html)
    # 3. Thử thêm .html (vd: /about -> /about.html)
    try_files {path} {path}/index.html {path}.html

    # Chỉ định thư mục gốc website
    # macOS: root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
    # Windows: root * C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
    root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist

    # Kích hoạt dịch vụ file tĩnh
    file_server
}

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

Truy cập website chế độ URL sạch
Giờ bạn có thể truy cập tên miền (vd: https://vitepress-cleanurl.servbay.demo). Đường dẫn trang không cần đuôi .html, ví dụ: để truy cập trang about.html, chỉ cần vào https://vitepress-cleanurl.servbay.demo/about.

Tổng kết

Với các bước trên, bạn đã nắm vững quy trình tạo, phát triển và triển khai website tài liệu VitePress bằng 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 máy chủ web cục bộ, bao gồm proxy ngược cho phát triển và dịch vụ tệp tĩnh cho bản sản xuất, đồng thời cung cấp tên miền tùy chỉnh cùng chứng chỉ SSL tự động.

Kết hợp ServBay và VitePress, bạn dễ dàng xây dựng và quản lý website tài liệu kỹ thuật chất lượng cao một cách hiệu quả.

Tạo và chạy dự án VitePress với ServBay ​

VitePress là gì? ​

Những đặc điểm nổi bật của VitePress ​

Tạo và chạy dự án VitePress với ServBay ​

Điều kiện cần thiết ​

Khởi tạo dự án VitePress ​

Chỉnh sửa nội dung dự án VitePress ​

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

Xây dựng bản phát hành (production) ​

Sử dụng chế độ URL sạch (cleanUrls: true) ​

Tổng kết ​

Tạo và chạy dự án VitePress với ServBay

VitePress là gì?

Những đặc điểm nổi bật của VitePress

Tạo và chạy dự án VitePress với ServBay

Điều kiện cần thiết

Khởi tạo dự án VitePress

Chỉnh sửa nội dung dự án VitePress

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

Xây dựng bản phát hành (production)

Sử dụng chế độ URL sạch (`cleanUrls: true`)

Tổng kết