Membina & Menjalankan Projek VitePress dengan ServBay

VitePress merupakan penjana laman web statik moden yang dikuasakan oleh Vue, direka khusus untuk membina laman dokumentasi yang pantas, menarik dan mudah diselenggara. Dibina di atas Vite, ia menawarkan pengalaman pembangunan dan prestasi binaan yang sangat baik. Untuk pembangun yang perlukan dokumentasi profesional bagi projek, pustaka atau produk, VitePress adalah pilihan yang unggul.

Semasa membangunkan dan menguji VitePress secara tempatan, memiliki persekitaran pembangunan web yang stabil dan mudah disesuaikan adalah sangat penting. ServBay hadir sebagai penyelesaian, mengintegrasikan pelbagai versi Node.js serta pelayan web yang berkuasa seperti Caddy atau Nginx, memudahkan anda menjalankan projek VitePress anda.

Artikel ini akan membimbing anda menggunakan persekitaran bersepadu ServBay – dari membina projek VitePress baharu, mengkonfigurasi pelayan pembangunan (proksi terbalik), sehinggalah menyajikan laman produksi dengan servis fail statik.

Apakah Itu VitePress?

VitePress ialah penjana laman web statik (SSG) berasaskan Vite, memanfaatkan kuasa Vue 3 dan kelajuan Vite untuk menghasilkan laman web statik – terutamanya sesuai untuk membina dokumentasi teknikal.

Ciri-ciri & Kelebihan Utama VitePress

• Pengalaman pembangunan pantas: Berkat Hot Module Replacement (HMR) Vite, sebarang perubahan akan terus dipaparkan di pelayar, memaksimumkan kecekapan pembangunan.
• Dikuasakan oleh Vue: Menyokong penggunaan komponen Vue secara langsung dalam fail Markdown, meningkatkan interaksi dan penampilan dokumen.
• Mudah digunakan: Konfigurasi ringkas, boleh digunakan terus tanpa 'setup' yang rumit. Fokus pada penulisan kandungan.
• Prestasi tinggi: Fail statik yang dibina bersaiz kecil dan diload dengan cepat, serta pengalaman seperti aplikasi satu halaman (SPA).
• Mesra SEO: HTML yang dihasilkan dioptimumkan untuk enjin carian, siap dengan sokongan 'custom head tags'.
• Markdown dipertingkatkan: Menyokong CommonMark dan GitHub Flavored Markdown (GFM), serta menyediakan sintaks tambahan.

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

Membina & Menjalankan Projek VitePress dengan ServBay

ServBay menawarkan cara mudah untuk mengurus versi Node.js dan mengkonfigurasi pelayan web bagi projek VitePress anda – sama ada mod pembangunan atau servis fail statik untuk produksi.

Keperluan Asas

Sebelum bermula, pastikan anda telah lakukan persiapan berikut:

1. Pemasangan ServBay: ServBay telah berjaya dipasang pada sistem anda. Jika masih belum, sila rujuk Panduan Pemasangan ServBay.
2. Pemasangan pakej Node.js: Pastikan versi Node.js yang diperlukan telah dipasang & diaktifkan dalam ServBay. Anda boleh urus melalui panel kawalan ServBay pada halaman "Pakej". Rujuk Cara Guna Node.js.

Membina Projek VitePress Baharu

1. Inisialisasi direktori projek

   Mula-mula, buka aplikasi Terminal anda. Disarankan untuk membina folder projek di bawah direktori root laman ServBay, agar mudah dikonfigurasi nanti.

   macOS:

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

   Windows:

   cd C:\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 pasang VitePress sebagai kebergantungan pembangunan dan jalankan arahan inisialisasi.

   npm add -D vitepress
   npx vitepress init

   Atau menggunakan Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Arahan inisialisasi akan membimbing anda untuk menetapkan beberapa konfigurasi asas seperti tajuk laman, keterangan dan lain-lain. Masukkan maklumat seperti berikut:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Direktori dokumen lalai, tekan Enter untuk terima
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Tajuk laman anda, contoh: ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Keterangan laman
    │
    ◇  Theme:
    │  Default Theme # Pilih tema, boleh guna lalai
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Guna TypeScript untuk konfigurasi, pilih ikut citarasa 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, VitePress akan membina folder docs dalam servbay-vitepress-app, menghasilkan fail konfigurasi lalai (.vitepress) dan fail contoh halaman (index.md, guide/index.md dan sebagainya). Fail package.json juga akan dikemaskini dengan skrip seperti docs:dev dan docs:build.

Ubah Kandungan Projek VitePress

1. Edit Kandungan Halaman Utama

   Fail halaman utama VitePress terletak di docs/index.md. Buka dengan mana-mana editor teks dan ubah kepada:

   # Hello ServBay!
   
   Selamat datang ke ServBay untuk menjalankan laman dokumentasi VitePress anda.
   
   Ini adalah laman demo tempatan ciptaan VitePress, disajikan menggunakan ServBay.

Mod Pembangunan

Semasa membangunkan laman VitePress, biasanya anda guna pelayan pembangunan terbina yang menyokong 'hot reload' untuk pratonton segera. Kemudian, gunakan proksi terbalik ServBay dengan domain khusus dan perlindungan SSL.

1. Jalankan pelayan pembangunan VitePress

   Di Terminal pada direktori projek (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app), jalankan:

   npm run docs:dev -- --port 8585

   Atau guna Yarn:

   yarn docs:dev --port 8585

   Pelayan akan bermula dan mendengar pada port yang anda tetapkan (contoh: 8585). Biasanya, alamat ialah http://localhost:8585.

2. Konfigurasi laman ServBay (proksi terbalik)

   Buka panel kawalan ServBay, ke halaman "Laman Web" dan tambah konfigurasi laman baru.

   • Nama: Contoh – VitePress Dev Site.
   • Domain: Masukkan domain pembangunan tempatan, sebaiknya berakhir dengan .servbay.demo seperti vitepress-dev.servbay.demo.
   • Jenis laman: Pilih Proksi Terbalik.
   • IP: Isikan 127.0.0.1.
   • Port: Gunakan port dari langkah 1, contoh 8585.

   Simpan perubahan. ServBay akan menghubungkan Caddy atau Nginx untuk memproksi permintaan ke https://vitepress-dev.servbay.demo ke http://127.0.0.1:8585.

3. Akses laman pembangunan

   Kini anda boleh akses laman anda di pelayar melalui https://vitepress-dev.servbay.demo. Selain menggunakan domain khusus, anda juga mendapat sijil SSL automatik yang dijana oleh ServBay User CA untuk akses HTTPS.

Bina Versi Produksi

Jika dokumentasi VitePress sudah siap dan bersedia untuk diterbitkan, tiba masa untuk membina versi statik yang dioptimumkan.

1. Bina versi produksi

   Di Terminal pada root projek (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app), jalankan:

   npm run docs:build

   Atau guna Yarn:

   yarn docs:build

   Proses binaan akan kompilasi fail Markdown, komponen Vue dan lain-lain menjadi fail HTML, CSS, JavaScript statik yang telah dioptimumkan. Fail statik akan dihasilkan dalam direktori docs/.vitepress/dist.

2. Konfigurasi laman ServBay (servis fail statik)

   Untuk laman produksi, gunakan fungsi servis fail statik ServBay.

   Buka panel ServBay, di halaman "Laman Web", tambah konfigurasi baru.

   • Nama: Contoh – VitePress Production Site.
   • Domain: Domain produksi tempatan, contoh vitepress-prod.servbay.demo.
   • Jenis laman: Pilih Statik.
   • Root Direktori Laman: Isikan laluan penuh ke direktori fail statik:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   Simpan dan aktifkan perubahan. ServBay akan menyajikan fail statik dari root yang anda tetapkan.

3. Akses laman produksi

   Sekarang anda boleh layari https://vitepress-prod.servbay.demo di pelayar untuk melihat laman produk VitePress anda dengan domain khusus dan SSL automatik.

Guna Mod Clean URLs (cleanUrls: true)

VitePress menyokong konfigurasi cleanUrls: true, membolehkan pautan tanpa akhiran .html (seperti /guide/ bukan /guide/index.html, atau /about bukan /about.html). Konfigurasi tambahan pada pelayan web diperlukan untuk mod ini.

ServBay menjalankan pelayan web Caddy atau Nginx. Contoh berikut menggunakan Caddy, mengaplikasikan arahan try_files yang memadankan permintaan kepada fail yang sesuai (dengan atau tanpa .html).

1. Aktifkan cleanUrls dalam VitePress

   Edit konfigurasi VitePress (docs/.vitepress/config.mts atau docs/.vitepress/config.ts), tambah atau ubah pilihan 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 bina produksi.

2. Konfigurasi laman ServBay (Caddy khusus)

   Pada panel ServBay, cari laman produksi anda (contoh: vitepress-prod.servbay.demo).

   • Klik butang edit.
   • Pilih Konfigurasi Khusus.
   • Dalam ruangan Konfigurasi Caddy, salin dan tampal konfigurasi berikut – tukar servbay-vitepress-test.prod kepada domain sebenar anda dan laluan root kepada laluan projek anda:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # Tukar kepada domain anda, contoh vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Aktifkan pemampatan Brotli (zstd) & Gzip
       encode zstd gzip
   
       # Import konfigurasi log lalai ServBay untuk debug
       import set-log vitepress-cleanurl.servbay.demo
   
       # Urus sijil SSL dalaman ServBay
       tls internal
   
       # Konfigurasi utama: Cuba padankan fail
       # 1. Cuba padankan laluan terus (e.g., /about -> /about)
       # 2. Cuba index.html dalam laluan (e.g., /guide/ -> /guide/index.html)
       # 3. Cuba fail .html (e.g., /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Tetapkan root laman
       # 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
   
       # Aktifkan servis fail statik
       file_server
   }

   Simpan dan aktifkan.

3. Akses laman clean URL

   Kini, layari domain anda (contoh: https://vitepress-cleanurl.servbay.demo). Untuk laman clean URL, anda boleh akses alamat tanpa .html, contohnya untuk halaman about.html, hanya perlu pergi ke https://vitepress-cleanurl.servbay.demo/about.

Rumusan

Dengan mengikuti panduan ini, anda telah belajar cara membina, membangun dan melancarkan laman dokumentasi VitePress dalam persekitaran ServBay. ServBay memudahkan pengurusan Node.js serta konfigurasi pelayan web tempatan, sama ada untuk proksi terbalik semasa pembangunan mahupun servis fail statik untuk produksi – semuanya dengan sokongan domain khusus dan sijil SSL automatik.

Gabungan ServBay dan VitePress membolehkan anda menghasilkan laman dokumentasi teknikal yang berkualiti tinggi, berprestasi dan mudah diuruskan dengan lebih cekap.