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:
bashcd /Applications/ServBay/www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3Windows:
cmdcd C:\ServBay\www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3Cà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:bashnpm add -D vitepress npx vitepress init
1
2Hoặc sử dụng Yarn:
bashyarn add -D vitepress yarn vitepress init
1
2Lệ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, filepackage.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.
1
2
3
4
5
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):bashnpm run docs:dev -- --port 8585
1Hoặc dùng Yarn:
bashyarn docs:dev --port 8585
1Server 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
.- Tên: Nhập tên dễ nhận diện, ví dụ
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:
bashnpm run docs:build
1Hoặc dùng Yarn:
bashyarn docs:build
1Quá 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
- macOS:
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.
- Tên: Nhập tên nhận diện, ví dụ
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 VitePressSửa file cấu hình VitePress (
docs/.vitepress/config.mts
hoặcdocs/.vitepress/config.ts
), thêm/sửa mụccleanUrls
: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 })
1
2
3
4
5
6
7
8Build 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
- macOS:
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 }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25Lư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 trangabout.html
, chỉ cần vàohttps://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ả.