Membuat dan Menjalankan Proyek VitePress dengan ServBay

VitePress adalah static site generator modern berbasis Vue, dirancang khusus untuk membangun situs dokumentasi yang cepat, indah, dan mudah dirawat. VitePress dibangun di atas Vite yang menghadirkan performa pengembangan dan proses build yang luar biasa. Untuk pengembang yang ingin membuat dokumentasi profesional untuk proyek, library, atau produk mereka, VitePress merupakan pilihan terbaik.

Saat mengembangkan dan menguji VitePress secara lokal, memiliki lingkungan pengembangan web yang stabil dan mudah dikonfigurasi sangatlah penting. ServBay hadir untuk tujuan ini, menawarkan integrasi berbagai versi Node.js dan server web yang kuat (seperti Caddy atau Nginx) sehingga Anda dapat dengan mudah melayani proyek VitePress Anda.

Dokumen ini akan memandu Anda memanfaatkan lingkungan terintegrasi ServBay, mulai dari membuat, mengonfigurasi, hingga menjalankan proyek VitePress dari nol, termasuk menyiapkan reverse proxy untuk server pengembangan dan layanan file statis untuk build produksi.

Apa itu VitePress?

VitePress adalah static site generator (SSG) berbasis Vite, yang memanfaatkan kekuatan Vue 3 dan performa tinggi Vite untuk membangun situs statis, terutama unggul dalam pembuatan dokumentasi teknis.

Fitur dan Keunggulan VitePress

• Pengalaman Pengembangan Super Cepat: Berkat Hot Module Replacement (HMR) dari Vite, perubahan dapat langsung terlihat di browser, meningkatkan produktivitas pengembangan.
• Ditenagai Vue: Anda dapat menggunakan komponen Vue secara langsung di dalam file Markdown, meningkatkan interaktivitas dan ekspresi dokumentasi.
• Sederhana & Mudah Digunakan: Konfigurasi simpel, langsung siap pakai, fokus pada penulisan konten.
• Performa Tinggi: File statis hasil build sangat ringan, kecepatan loading tinggi, serta didukung routing client-side yang mulus layaknya single-page application.
• Ramah SEO: Struktur HTML yang dihasilkan dioptimalkan untuk mesin pencari, serta mendukung custom meta tag di header.
• Markdown yang Ditingkatkan: Mendukung semua fitur CommonMark dan GitHub Flavored Markdown (GFM), plus tambahan sintaks khusus.

Dengan VitePress, pengembang dapat dengan mudah membuat situs dokumentasi yang berkualitas tinggi dan berperforma tinggi.

Membuat dan Menjalankan Proyek VitePress Menggunakan ServBay

ServBay menyediakan cara mudah dalam mengelola versi Node.js dan melakukan setup server web untuk proyek VitePress Anda—baik untuk server pengembangan lokal atau mode produksi menggunakan file statis.

Prasyarat

Sebelum memulai, pastikan Anda telah menyiapkan hal berikut:

1. Instal ServBay: Pastikan ServBay sudah terpasang di sistem macOS Anda. Jika belum, ikuti panduan Instalasi ServBay.
2. Instal Paket Node.js: Di dalam ServBay, pastikan Anda telah menginstal dan mengaktifkan versi Node.js yang dibutuhkan. Pengelolaan dapat dilakukan melalui panel kontrol ServBay pada halaman "Paket". Lihat juga Penggunaan Node.js.

Membuat Proyek VitePress

1. Inisialisasi Direktori Proyek

   Pertama, buka aplikasi terminal Anda. Direkomendasikan untuk membuat folder proyek di direktori root situs default ServBay /Applications/ServBay/www agar memudahkan konfigurasi situs ServBay selanjutnya.

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

2. Instal VitePress dan Inisialisasi Konfigurasi

   Di dalam direktori proyek servbay-vitepress-app, gunakan npm atau yarn untuk menambahkan VitePress sebagai dependency pengembangan dan jalankan perintah inisialisasi.

   npm add -D vitepress
   npx vitepress init

   Atau menggunakan Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Perintah inisialisasi akan memandu Anda melalui beberapa pengaturan dasar, seperti judul situs dan deskripsi. Isilah sesuai kebutuhan:

    ┌  Selamat datang di VitePress!
    │
    ◇  Di mana VitePress akan menginisialisasi konfigurasi?
    │  ./docs  # Direktori dokumen default, cukup tekan enter untuk konfirmasi
    │
    ◇  Judul situs:
    │  ServBay VitePress Demo # Masukkan judul situs Anda, misal ServBay VitePress Demo
    │
    ◇  Deskripsi situs:
    │  A VitePress site running on ServBay # Masukkan deskripsi situs Anda
    │
    ◇  Tema:
    │  Default Theme # Pilih tema, default saja cukup
    │
    ◇  Gunakan TypeScript untuk file konfigurasi dan tema?
    │  Yes # Pilih sesuai preferensi Anda
    │
    ◇  Tambahkan npm script VitePress ke package.json?
    │  Yes # Disarankan pilih Yes agar script otomatis terpasang
    │
    └  Selesai! Jalankan npm run docs:dev dan mulai menulis.

   Setelah proses inisialisasi, VitePress akan membuat subdirektori docs di dalam servbay-vitepress-app, lengkap dengan file konfigurasi (.vitepress) dan halaman contoh (index.md, guide/index.md, dsb). File package.json juga diperbarui dengan script seperti docs:dev dan docs:build.

Mengubah Konten Proyek VitePress

1. Edit Konten Beranda

   Berkas beranda default VitePress ada di docs/index.md. Anda bebas mengedit file ini menggunakan editor teks apa pun. Contoh modifikasi:

   # Halo ServBay!
   
   Selamat datang di ServBay untuk menjalankan situs dokumentasi VitePress Anda.
   
   Ini adalah situs demo lokal menggunakan VitePress yang dilayani oleh ServBay.

Masuk ke Mode Pengembangan

Untuk mengembangkan situs VitePress, Anda bisa menjalankan server pengembangan built-in yang mendukung hot reload agar perubahan langsung terlihat. Dengan fitur reverse proxy ServBay, Anda bisa mengakses server development melalui domain kustom lengkap dengan SSL.

1. Jalankan Server Pengembangan VitePress

   Di terminal, pastikan Anda berada di direktori proyek /Applications/ServBay/www/servbay-vitepress-app. Jalankan perintah berikut untuk menyalakan server pengembangan di port (misal 8585):

   npm run docs:dev -- --port 8585

   Atau dengan Yarn:

   yarn docs:dev --port 8585

   Server akan aktif pada alamat lokal (contoh http://localhost:8585) seperti yang ditampilkan di terminal.

2. Konfigurasi Website di ServBay (Reverse Proxy)

   Buka panel kontrol ServBay, masuk ke halaman "Situs". Klik untuk menambahkan konfigurasi situs yang baru.

   • Nama: Isi dengan nama yang mudah dikenali, misal VitePress Dev Site.
   • Domain: Masukkan domain lokal yang ingin digunakan untuk pengembangan. Sesuai standar ServBay dan untuk menghindari konflik, disarankan gunakan akhiran .servbay.demo, misal vitepress-dev.servbay.demo.
   • Tipe Situs: Pilih Reverse Proxy.
   • IP: Masukkan 127.0.0.1 (localhost).
   • Port: Masukkan port server pengembangan, misal 8585.

   Setelah pengaturan selesai, simpan dan terapkan perubahan pada ServBay. Web server (Caddy atau Nginx) akan otomatis mengatur proxy dari https://vitepress-dev.servbay.demo ke http://127.0.0.1:8585.

3. Akses Situs Pengembangan

   Kini, Anda dapat membuka browser dan mengunjungi domain yang telah Anda konfigurasikan: https://vitepress-dev.servbay.demo. Anda akan melihat konten situs yang diberikan oleh server pengembangan VitePress. Dengan setup ini, Anda bisa memakai domain kustom dan mendapatkan sertifikat SSL yang ditandatangani oleh ServBay User CA secara otomatis untuk akses HTTPS yang aman.

Build untuk Versi Produksi

Setelah Anda puas dengan isi dokumentasi dan siap diterbitkan, saatnya melakukan build menjadi file statis yang teroptimasi.

1. Build Versi Produksi

   Di terminal, pada direktori proyek /Applications/ServBay/www/servbay-vitepress-app, jalankan perintah berikut:

   npm run docs:build

   Atau dengan Yarn:

   yarn docs:build

   Proses build akan meng-compile serta membundel seluruh file Markdown dan komponen Vue menjadi kumpulan file HTML, CSS, dan JavaScript yang sudah dioptimalkan. Hasil build secara default terdapat pada folder docs/.vitepress/dist di dalam proyek Anda.

2. Setel Website ServBay (Layanan File Statis)

   Versi produksi VitePress pada dasarnya hanya kumpulan file statis. Anda dapat melayaninya langsung menggunakan fitur Static File Service pada ServBay.

   Buka kontrol panel ServBay, menuju "Situs", lalu tambahkan konfigurasi situs baru:

   • Nama: Masukkan nama mudah diingat, misal VitePress Production Site.
   • Domain: Masukkan domain yang ingin digunakan untuk akses versi produksi, misal vitepress-prod.servbay.demo.
   • Tipe Situs: Pilih Static.
   • Root Folder Website: Isi dengan path absolut ke hasil build, contoh: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Setelah selesai, simpan dan terapkan perubahan. ServBay akan mengonfigurasi server web untuk langsung melayani file statis dari lokasi tersebut.

3. Akses Situs Produksi

   Kini Anda bisa mengunjungi https://vitepress-prod.servbay.demo di browser. Anda akan melihat versi produksi dari situs VitePress Anda. ServBay akan menyediakan domain kustom beserta enkripsi SSL otomatis.

Mengaktifkan Mode Clean URL (cleanUrls: true)

VitePress mendukung pengaturan cleanUrls: true yang membuat tautan halaman tanpa ekstensi .html (misal /guide/ bukan /guide/index.html, atau /about bukan /about.html). Agar server web dapat melayani permintaan ini dengan benar, dibutuhkan konfigurasi tambahan.

ServBay menggunakan Caddy atau Nginx sebagai web server. Berikut adalah contoh konfigurasi untuk Caddy menggunakan direktif try_files untuk mencari file yang sesuai (termasuk ekstensi .html atau index.html jika perlu).

1. Aktifkan cleanUrls di Konfigurasi VitePress

   Edit file konfigurasi VitePress (docs/.vitepress/config.mts atau docs/.vitepress/config.ts) dan tambahkan atau sesuaikan opsi cleanUrls:

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

   Setelah itu, jalankan kembali npm run docs:build untuk rebuild situs produksi.

2. Konfigurasi Website ServBay (Custom Caddy Config)

   Buka panel kontrol ServBay dan pilih situs produksi VitePress Anda (misal vitepress-prod.servbay.demo).

   • Klik tombol edit.
   • Centang opsi Custom Config.
   • Pada area Konfigurasi Caddy, tempelkan konfigurasi berikut. Ganti servbay-vitepress-test.prod dengan domain yang Anda gunakan, dan /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist dengan path root hasil build Anda.

   # Ubah jadi domain Anda, mis: vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Aktifkan kompresi Brotli (zstd) dan Gzip untuk mempercepat loading
       encode zstd gzip
   
       # Impor konfigurasi log default ServBay untuk debugging
       import set-log vitepress-cleanurl.servbay.demo
   
       # Otomatis menambahkan SSL internal milik ServBay
       tls internal
   
       # Konfigurasi utama: cek berkas secara berurutan
       # 1. Coba path langsung (misal /about -> /about)
       # 2. Coba index.html dalam folder (misal /guide/ -> /guide/index.html)
       # 3. Coba file berakhiran .html (misal /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Set root folder website
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Aktifkan layanan file statis
       file_server
   }

   Simpan dan terapkan perubahan.

3. Akses Situs dengan Clean URL

   Kini, ketika Anda mengunjungi domain yang sudah Anda atur (misal https://vitepress-cleanurl.servbay.demo), Anda bisa mengakses halaman tanpa akhiran .html—misalkan untuk halaman about.html cukup akses https://vitepress-cleanurl.servbay.demo/about.

Ringkasan

Lewat panduan ini, Anda telah mempelajari cara membuat, mengembangkan, dan mempublikasikan situs dokumentasi VitePress di lingkungan ServBay. Dengan ServBay, pengelolaan environment Node.js dan konfigurasi server web lokal menjadi mudah—baik untuk reverse proxy di mode pengembangan maupun servis file statis di mode produksi, semuanya bisa berjalan lancar dan otomatis mendapatkan domain serta SSL kustom.

Manfaatkan kekuatan ServBay dan VitePress untuk membangun serta merawat dokumentasi teknis berkualitas secara efisien dan profesional.