Mencipta dan Menjalankan Projek VitePress dengan ServBay

VitePress adalah penjana laman web statik moden yang disokong oleh Vue, direka khas untuk membina laman dokumentasi yang pantas, menarik dan mudah diselenggara. Ia dibina berasaskan Vite, menawarkan pengalaman pembangunan serta prestasi binaan yang mengagumkan. Untuk pembangun yang ingin mencipta dokumentasi profesional untuk projek, pustaka atau produk, VitePress merupakan pilihan yang sangat baik.

Semasa membangun dan menguji VitePress secara tempatan, anda memerlukan persekitaran pembangunan web tempatan yang stabil dan mudah dikonfigurasikan. Di sinilah ServBay menyerlah — ia menggabungkan pelbagai versi persekitaran Node.js dan pelayan web berkuasa (seperti Caddy atau Nginx), membolehkan anda menyediakan servis untuk projek VitePress anda dengan mudah.

Panduan ini akan membimbing anda menggunakan persekitaran terbina dalam ServBay untuk mencipta, mengkonfigurasi dan menjalankan projek VitePress daripada awal, termasuk tetapan proksi songsang untuk pelayan pembangunan dan servis fail statik untuk binaan pengeluaran.

Apa itu VitePress?

VitePress ialah penjana laman statik (SSG) berasaskan Vite yang memanfaatkan kekuatan Vue 3 dan prestasi pantas Vite untuk menghasilkan laman web statik, terutamanya untuk dokumentasi teknikal.

Ciri-ciri dan Kelebihan Utama VitePress

• Pengalaman pembangunan sangat pantas: Dengan Hot Module Replacement (HMR) dari Vite, anda dapat melihat perubahan serta-merta di penyemak imbas, sekali gus meningkatkan produktiviti.
• Dipacu oleh Vue: Gunakan komponen Vue terus dalam fail Markdown, yang menyemarakkan interaktiviti serta keupayaan dokumentasi.
• Mudah digunakan: Konfigurasi ringkas, sedia guna, fokus pada penulisan kandungan.
• Prestasi tinggi: Fail statik yang terhasil bersaiz kecil, pantas dimuat, dan dengan routing klien terbina dalam, pengalaman laman seperti aplikasi satu halaman (SPA) terjamin lancar.
• Mesra SEO: Struktur HTML tersusun untuk kemudahan enjin carian serta sokongan tag kepala tersuai.
• Markdown diperkaya: Menyokong sepenuhnya CommonMark dan GitHub Flavored Markdown (GFM), beserta sintaks tambahan.

Dengan VitePress, pembangun boleh membina laman dokumentasi berkualiti tinggi dan berprestasi dengan mudah.

Mencipta dan Menjalankan Projek VitePress menggunakan ServBay

ServBay menyediakan cara mudah untuk mengurus versi Node.js dan mengkonfigurasi pelayan web supaya projek VitePress anda dapat diservis sama ada dalam mod pembangunan mahupun sebagai fail statik selepas binaan produksi.

Prasyarat

Sebelum bermula, pastikan perkara berikut telah disediakan:

1. Pasang ServBay: ServBay telah berjaya dipasang pada sistem macOS anda. Jika belum, rujuk Panduan Pemasangan ServBay.
2. Pasang Pakej Node.js: Dalam ServBay, pastikan versi Node.js yang diperlukan telah dipasang dan diaktifkan. Anda boleh uruskan ini di halaman "Pakej" dalam panel kawalan ServBay. Sila rujuk Menggunakan Node.js.

Mencipta Projek VitePress

1. Inisialisasi Direktori Projek

   Mula-mula, buka aplikasi terminal anda. Disyorkan untuk mencipta folder projek di direktori root laman web ServBay, iaitu /Applications/ServBay/www, demi memudahkan konfigurasi laman web pada langkah seterusnya.

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

2. Pasang VitePress dan Inisialisasi Konfigurasi

   Dalam direktori projek servbay-vitepress-app, gunakan npm atau yarn untuk menambah VitePress sebagai kebergantungan pembangunan, kemudian jalankan perintah inisialisasi.

   npm add -D vitepress
   npx vitepress init

   Atau dengan Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Perintah inisialisasi akan memandu anda melengkapkan tetapan asas seperti judul laman dan deskripsi. Ikuti arahan seperti berikut:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Direktori dokumentasi lalai, tekan Enter untuk terima
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Masukkan judul laman anda, contoh: ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Masukkan deskripsi laman
    │
    ◇  Theme:
    │  Default Theme # Pilih tema, tema lalai sesuai
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Gunakan TypeScript atau tidak untuk konfigurasi, ikut pilihan anda
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Tambah skrip ke package.json, disarankan pilih Yes
    │
    └  Done! Now run npm run docs:dev and start writing.

   Selepas inisialisasi selesai, VitePress akan mencipta subdirektori docs di bawah servbay-vitepress-app, serta menghasilkan fail konfigurasi lalai (.vitepress) dan beberapa fail halaman contoh (index.md, guide/index.md dll). Fail package.json anda juga akan dikemaskini dengan skrip seperti docs:dev dan docs:build.

Mengubah Kandungan Projek VitePress

1. Edit Kandungan Halaman Utama

   Fail halaman utama lalai VitePress ialah docs/index.md. Anda boleh membukanya menggunakan mana-mana editor teks dan mengubah kandungannya. Sebagai contoh, boleh gantikan menjadi:

   # Hello ServBay!
   
   Selamat datang menggunakan ServBay untuk menjalankan laman dokumentasi VitePress anda.
   
   Ini adalah laman demo tempatan yang dibina menggunakan VitePress dengan servis daripada ServBay.

Mod Pembangunan

Semasa membangunkan laman VitePress, anda biasanya akan menggunakan pelayan pembangunan terbina dalam yang menawarkan hot reload untuk pratonton masa nyata. Dengan menggunakan fungsi proksi songsang ServBay, anda boleh mengakses pelayan pembangunan ini melalui domain tersuai serta mendapat manfaat SSL yang disediakan oleh ServBay.

1. Jalankan Pelayan Pembangunan VitePress

   Di terminal, pastikan anda berada dalam direktori projek /Applications/ServBay/www/servbay-vitepress-app. Jalankan perintah berikut untuk memulakan pelayan pembangunan di port yang ditetapkan (contohnya 8585).

   npm run docs:dev -- --port 8585

   Atau dengan Yarn:

   yarn docs:dev --port 8585

   Pelayan akan bermula dan mendengar di port tempatan tersebut (contohnya 8585). Alamat pelayan biasanya dipaparkan sebagai http://localhost:8585.

2. Konfigurasi Laman ServBay (Proksi Songsang)

   Buka panel kawalan ServBay dan navigasi ke halaman "Laman Web". Klik tambah untuk buat konfigurasi laman baharu.

   • Nama: Masukkan nama mudah dikenali, contoh VitePress Dev Site.
   • Domain: Masukkan domain tempatan yang anda ingin gunakan. Untuk kekalkan konsisten dengan jenama ServBay dan elak konflik, disarankan gunakan akhiran .servbay.demo, contohnya vitepress-dev.servbay.demo.
   • Jenis Laman: Pilih Proksi Songsang.
   • IP: Isikan 127.0.0.1 (tempatan).
   • Port: Letakkan port yang anda tetapkan sebelum ini, contoh 8585.

   Setelah selesai, simpan dan gunakan tetapan baru. ServBay akan automatik konfigurasi pelayan web (seperti Caddy atau Nginx) untuk memproksikan permintaan ke https://vitepress-dev.servbay.demo ke http://127.0.0.1:8585.

3. Akses Laman Pembangunan

   Kini anda boleh melawat domain yang anda tetapkan, contohnya https://vitepress-dev.servbay.demo di pelayar anda. Anda akan melihat kandungan laman yang diservis oleh pelayan pembangunan VitePress. Dengan konfigurasi ServBay, anda bukan sahaja mendapat domain tersuai — anda juga mendapat sijil SSL automatik yang ditandatangani oleh ServBay User CA, membolehkan akses selamat melalui HTTPS.

Membina Versi Pengeluaran

Setelah laman dokumentasi siap untuk dipublikasi, anda perlu hasilkan versi statik yang telah dioptimumkan.

1. Bina Versi Pengeluaran

   Di terminal, pastikan anda berada dalam direktori projek /Applications/ServBay/www/servbay-vitepress-app. Jalankan:

   npm run docs:build

   Atau dengan Yarn:

   yarn docs:build

   Proses ini akan membina serta membungkus fail Markdown, komponen Vue dan lain-lain menjadi fail statik HTML, CSS, dan JavaScript yang telah dioptimumkan. Secara lalai, hasil binaan disimpan di dalam docs/.vitepress/dist dalam projek anda.

2. Konfigurasi Laman ServBay (Servis Fail Statik)

   Untuk versi pengeluaran yang dalam bentuk fail statik, anda boleh gunakan fungsi servis fail statik dalam ServBay secara langsung.

   Buka panel kawalan ServBay dan navigasi ke halaman "Laman Web". Klik tambah untuk buat konfigurasi baharu.

   • Nama: Masukkan nama mudah dikenali, contoh VitePress Production Site.
   • Domain: Masukkan domain yang ingin digunakan untuk laman pengeluaran, contoh vitepress-prod.servbay.demo.
   • Jenis Laman: Pilih Statik.
   • Root Laman: Letakkan path mutlak ke direktori hasil binaan statik anda: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Selepas simpan dan aktifkan, ServBay akan tetapkan pelayan web untuk terus menyediakan servis fail statik dari direktori ini.

3. Akses Laman Pengeluaran

   Kini anda boleh mengakses laman anda di https://vitepress-prod.servbay.demo menerusi pelayar. Anda akan melihat versi pengeluaran laman VitePress. Sama seperti sebelum ini, domain tersuai serta SSL disediakan secara automatik oleh ServBay.

Menjalankan dalam Mod Clean URL (cleanUrls: true)

VitePress menyokong konfigurasi cleanUrls: true, yang membuang akhiran .html pada URL laman yang dijana (contohnya, /guide/ bukannya /guide/index.html, atau /about berbanding /about.html). Untuk pelayan web memahami permintaan ini dengan betul, perlu ada konfigurasi tambahan.

ServBay menggunakan Caddy atau Nginx sebagai pelayan web. Contoh berikut memfokuskan pada tetapan Caddy, memanfaatkan arahan try_files bagi mencari fail berkaitan (termasuk ext .html atau direktori /index.html).

1. Aktifkan cleanUrls dalam Konfigurasi VitePress

   Sunting fail konfigurasi VitePress anda (docs/.vitepress/config.mts atau docs/.vitepress/config.ts), dan tambah/ubah suai opsyen cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... konfigurasi lain
     cleanUrls: true, // Aktifkan Clean URL
     // ... konfigurasi lain
   })

   Jalankan semula npm run docs:build untuk menghasilkan binaan pengeluaran baharu.

2. Konfigurasi Laman ServBay (Guna Konfigurasi Caddy Tersuai)

   Buka panel kawalan ServBay, pergi ke halaman "Laman Web". Cari laman yang telah dikonfigurasi untuk laman pengeluaran VitePress anda (contohnya vitepress-prod.servbay.demo).

   • Klik butang edit.
   • Pilih pilihan Konfigurasi Tersuai.
   • Dalam ruang konfigurasi Caddy, masukkan kandungan berikut (gantikan domain serta direktori root dengan nilai sebenar anda):

   # Gantikan dengan domain sebenar anda, contoh: vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Aktifkan pemampatan Brotli (zstd) dan Gzip untuk kelajuan
       encode zstd gzip
   
       # Import konfigurasi log default ServBay untuk debugging
       import set-log vitepress-cleanurl.servbay.demo
   
       # Automatik urus sijil SSL dalaman ServBay
       tls internal
   
       # Konfigurasi utama: cuba cari fail berkaitan
       # 1. Cuba padan path terus (cth: /about -> /about)
       # 2. Cuba cari /index.html dalam path (cth: /guide/ -> /guide/index.html)
       # 3. Cuba cari path dengan akhiran .html (cth: /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Set root laman web
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Aktifkan servis fail statik
       file_server
   }

   Simpan dan gunakan tetapan baharu.

3. Akses Laman Mod Clean URL

   Sekarang, akseslah domain anda (contoh: https://vitepress-cleanurl.servbay.demo). Untuk laman dengan clean URL, anda boleh melawat URL tanpa akhiran .html, contohnya laman about.html boleh diakses melalui https://vitepress-cleanurl.servbay.demo/about.

Rumusan

Dengan mengikuti panduan ini, anda kini telah mempelajari cara mencipta, membangun dan deploy laman dokumentasi VitePress menggunakan persekitaran ServBay. ServBay memudahkan pengurusan persekitaran Node.js dan konfigurasi pelayan web tempatan — sama ada untuk proksi songsang semasa pembangunan, mahupun menyediakan fail statik untuk pengeluaran — disertakan dengan sokongan domain tersuai dan sijil SSL automatik.

Gabungan hebat antara ServBay dan VitePress ini membantu anda membina serta menyelenggara dokumentasi teknikal berkualiti tinggi secara lebih efisien.