ServBay ile VitePress Projesi Oluşturma ve Çalıştırma
VitePress, modern bir statik site üreticisi olup, Vue tarafından desteklenmektedir ve hızlı, şık ve kolayca yönetilebilen dokümantasyon siteleri oluşturmak için idealdir. Vite temelli altyapısıyla, üstün geliştirme deneyimi ve yüksek yapılandırma performansı sunar. Projeleriniz, kütüphaneleriniz veya ürünleriniz için profesyonel dokümantasyon oluşturmak isteyen geliştiriciler için VitePress çok iyi bir seçenektir.
VitePress ile yerel olarak geliştirme ve test yaparken, stabil ve kolayca yapılandırılabilen bir web geliştirme ortamına ihtiyaç duyarsınız. ServBay tam da bu amaçla geliştirilmiş olup, birden fazla Node.js sürümü ve güçlü web sunucuları (Caddy ya da Nginx gibi) ile VitePress projelerinizi kolayca çalıştırmanızı sağlar.
Bu makalede, ServBay’in entegre ortamını kullanarak sıfırdan bir VitePress projesinin nasıl oluşturulacağı, yapılandırılacağı ve çalıştırılacağı; geliştirme sunucusu için ters proxy ayarlanması ve üretim için statik dosya servisi kurulumu adım adım gösterilecektir.
VitePress Nedir?
VitePress, Vite tabanlı bir statik site üretici (SSG) olup Vue 3’ün güçlü olanaklarını ve Vite’ın üstün performansını kullanarak statik web siteleri oluşturmanızı sağlar. Teknik dokümantasyon hazırlamada özellikle başarılıdır.
VitePress’in Temel Özellikleri ve Avantajları
- Hızlı geliştirme deneyimi: Vite’ın hot module replacement (HMR) özelliği sayesinde yapılan değişiklikleri tarayıcıda neredeyse anında görebilirsiniz; geliştirme verimliliği çok yüksektir.
- Vue gücüyle çalışır: Markdown dosyalarında doğrudan Vue bileşenleri kullanarak dokümantasyonunuzu interaktif ve güçlü hale getirebilirsiniz.
- Kolay ve kullanıma hazır: Basit kurulum ve yapılandırma ile doğrudan içeriğe odaklanabilirsiniz.
- Yüksek performans: Oluşan statik dosyalar çok hafif ve hızlı yüklenir; dahili istemci yönlendirmesiyle tek sayfa uygulama hissi verir.
- SEO dostu: Oluşan HTML yapısı arama motorlarına uygundur ve özel başlık etiketleri eklenebilir.
- Gelişmiş Markdown: CommonMark ve GitHub Flavored Markdown (GFM) desteği ve ek sözdizimi kolaylıkları sunar.
VitePress ile geliştiriciler, yüksek kaliteli ve performanslı dokümantasyon sitelerini kolayca inşa edebilirler.
ServBay ile VitePress Projesi Kurmak ve Çalıştırmak
ServBay, Node.js sürümlerini kolayca yönetmenizi ve VitePress projeleriniz için web sunucusu yapılandırmanızı sağlar. Hem geliştirme modu hem de üretim modu için servis sağlama imkânı sunar.
Ön Koşullar
Başlamadan önce aşağıdaki hazırlıkları tamamladığınızdan emin olun:
- ServBay’in kurulmuş olması: Sistemde ServBay’in başarıyla kurulmuş olması gerekir. Henüz kurmadıysanız, ServBay Kurulum Rehberi‘ni inceleyin.
- Node.js paketinin yüklenmesi: ServBay’de gerekli Node.js paket ve versiyonlarının yüklenmiş ve etkinleştirilmiş olması gerekir. ServBay panelindeki "Paketler" bölümünden versiyon yönetebilir; Node.js Kullanımı dökümanına göz atabilirsiniz.
VitePress Projesi Oluşturma
Proje Dizininin Başlatılması
Öncelikle terminal uygulamasını açın. ServBay’in varsayılan site kök dizininde bir proje klasörü oluşturmanız tavsiye edilir; böylece ServBay’in site yapılandırmasında kolaylık yaşarsınız.
macOS:
bashcd /Applications/ServBay/www mkdir servbay-vitepress-app cd servbay-vitepress-app1
2
3Windows:
cmdcd C:\ServBay\www mkdir servbay-vitepress-app cd servbay-vitepress-app1
2
3VitePress’in Kurulumu ve Yapılandırma Başlatma
servbay-vitepress-appklasöründe npm veya yarn ile VitePress’i geliştirme bağımlılığı olarak kurup başlatma komutunu çalıştırın.bashnpm add -D vitepress npx vitepress init1
2veya Yarn ile:
bashyarn add -D vitepress yarn vitepress init1
2Başlatma komutu size bazı temel ayarları adım adım soracak; örneğin site başlığı ve açıklaması gibi. Bilgileri talimatlara göre girin:
┌ VitePress’e Hoşgeldiniz! │ ◇ VitePress yapılandırması nerede başlatılsın? │ ./docs # Varsayılan dokümantasyon klasörü; Enter ile onaylayabilirsiniz │ ◇ Site başlığı: │ ServBay VitePress Demo # Örneğin ServBay VitePress Demo yazabilirsiniz │ ◇ Site açıklaması: │ ServBay üzerinde çalışan bir VitePress sitesi # Site açıklamanızı girin │ ◇ Tema: │ Varsayılan Tema # Tema seçimi, varsayılanı yeterlidir │ ◇ Yapılandırma ve tema dosyaları için TypeScript kullanılsın mı? │ Evet # Tercihinize göre TypeScript kullanabilirsiniz │ ◇ VitePress npm komutları package.json’a eklensin mi? │ Evet # Komutların eklenmesi tavsiye edilir │ └ Tamamlandı! Artık npm run docs:dev ile geliştirmeye başlayabilirsiniz.Kurulum bitince, VitePress
servbay-vitepress-appklasöründe birdocsalt dizini oluşturur ve içinde varsayılan yapılandırma dosyasını (.vitepress) ve örnek sayfaları (index.md,guide/index.mdvb.) yaratır. Ayrıcapackage.jsondosyası dadocs:dev,docs:buildgibi komutlarla güncellenir.
VitePress Proje İçeriğini Düzenleme
Ana Sayfa İçeriğini Düzenleme
VitePress’in varsayılan ana sayfa dosyası
docs/index.mdiçinde bulunur. Herhangi bir metin editörüyle açıp dilediğiniz gibi düzenleyebilirsiniz. Örneğin şöyle değiştirebilirsiniz:markdown# Merhaba ServBay! VitePress dokümantasyon sitenizi ServBay ile çalıştırmaya hoş geldiniz. Bu, ServBay tarafından servis edilen VitePress ile oluşturulan yerel bir demo sitedir.1
2
3
4
5
Geliştirme Moduna Geçiş
VitePress’in dahili geliştirme sunucusu, kodlarda yapılan değişikliklerin anında ön izlemesini sağlar. ServBay’in ters proxy özelliği sayesinde bu sunucuyu özel alan adı ve SSL ile görüntüleyebilirsiniz.
VitePress Geliştirme Sunucusunu Başlatmak
Terminalde proje kök dizininde olduğunuzdan emin olun (macOS:
/Applications/ServBay/www/servbay-vitepress-app, Windows:C:\ServBay\www\servbay-vitepress-app). Aşağıdaki komutlarla geliştirme sunucusunu belirli bir portta başlatın (örneğin 8585):bashnpm run docs:dev -- --port 85851veya Yarn ile:
bashyarn docs:dev --port 85851Sunucu 8585 portunda çalışacak ve genellikle
http://localhost:8585adresinde erişilebilir olacaktır.ServBay Site Yapılandırması (Ters Proxy)
ServBay kontrol panelinde "Siteler" bölümüne gidin ve yeni bir site ekleyin.
- Adı: Ayırt edici bir isim girin; örneğin
VitePress Geliştirme Sitesi. - Alan Adı: Tarayıcıda erişmek istediğiniz yerel geliştirme alan adını girin. ServBay marka standardı için
.servbay.demouzantısını kullanmanız önerilir; örneğinvitepress-dev.servbay.demo. - Site Türü:
Ters Proxyseçin. - IP Adresi:
127.0.0.1yazın (yerel makinenizi temsil eder). - Port: 1. adımda kullandığınız portu girin; örneğin
8585.
Yapılandırmayı kaydedip ServBay’in ayarlarını uygulayın. ServBay, Caddy veya Nginx web sunucusunu
https://vitepress-dev.servbay.demoalan adındaki taleplerihttp://127.0.0.1:8585adresine yönlendirecek şekilde otomatik ayarlar.- Adı: Ayırt edici bir isim girin; örneğin
Geliştirme Sitesini Ziyaret Etme
Artık tarayıcıda yapılandırdığınız alan adından (
https://vitepress-dev.servbay.demo) sitenizi görüntüleyebilirsiniz. ServBay sayesinde özel alan adı ve ServBay User CA tarafından imzalanan SSL sertifikası ile güvenli HTTPS erişimine sahip olursunuz.
Üretim Sürümünü Oluşturmak
Dokümantasyonunuzu tamamladıktan sonra, dağıtıma hazır optimize edilmiş bir statik sürüm oluşturmanız gerekecek.
Üretim Sürümünü Oluşturmak
Terminalde proje kökünde olduğunuzdan emin olun (macOS:
/Applications/ServBay/www/servbay-vitepress-app, Windows:C:\ServBay\www\servbay-vitepress-app). Aşağıdaki komutları çalıştırın:bashnpm run docs:build1veya Yarn ile:
bashyarn docs:build1Yapı işlemi, Markdown dosyalarınızı ve Vue bileşenlerinizi optimize edilmiş statik HTML, CSS ve JavaScript dosyalarına dönüştürür. Oluşan dosyalar varsayılan olarak
docs/.vitepress/distdizininde bulunur.ServBay Site Yapılandırması (Statik Dosya Servisi)
Üretim sürümü tamamen statik dosyadan oluştuğu için ServBay’in statik dosya servisiyle kolayca erişim sağlayabilirsiniz.
ServBay panelinde "Siteler" bölümünden yeni bir site ekleyin.
- Adı: Ayırt edici bir isim girin; örneğin
VitePress Üretim Sitesi. - Alan Adı: Üretim sitesinde kullanmak istediğiniz yerel alan adını girin; örneğin
vitepress-prod.servbay.demo. - Site Türü:
Statik. - Site Kök Dizini: 1. adımda oluşan statik dosya dizininin mutlak yolunu yazın:
- macOS:
/Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist - Windows:
C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
- macOS:
Ayarları kaydedip ServBay’in yapılandırmasını uygulayın. ServBay web sunucusu, belirlediğiniz kök dizinden statik dosyaları doğrudan servis edecektir.
- Adı: Ayırt edici bir isim girin; örneğin
Üretim Sürümünü Ziyaret Etme
Tarayıcıda
https://vitepress-prod.servbay.demoadresine giderek üretim sitesini görüntüleyebilirsiniz. ServBay yine sizin için özel alan adı ve otomatik SSL sertifikası sağlar.
Temiz URL Modunda Çalıştırmak (cleanUrls: true)
VitePress, cleanUrls: true seçeneği ile sayfa linklerinden .html uzantısını kaldırabilir (örneğin /guide/ veya /about şeklinde, /guide/index.html ya da /about.html olmadan). Web sunucusunun bu tür talepleri doğru işlemesi için ek yapılandırma gerekir.
ServBay, web sunucusu olarak Caddy veya Nginx kullanır. Aşağıda Caddy için örnek bir yapılandırma gösterilmiştir; bu yapılandırma, try_files ile ilgili dosyayı aramak için çeşitli deneme yolları sunar (örn. .html eklemek, dizin içinde index.html aramak).
VitePress Yapılandırmasında
cleanUrlsAktifleştirmeVitePress config dosyanızı (
docs/.vitepress/config.mtsveyadocs/.vitepress/config.ts) açıpsiteConfigbölümündecleanUrlsseçeneğini ekleyin veya düzenleyin:typescript// docs/.vitepress/config.mts import { defineConfig } from 'vitepress' export default defineConfig({ // ... diğer ayarlar cleanUrls: true, // Temiz URL aktif // ... diğer ayarlar })1
2
3
4
5
6
7
8Ardından tekrar
npm run docs:buildile üretim sürümünü oluşturun.ServBay Site Yapılandırması (Özel Caddy Ayarı)
ServBay panelinden VitePress üretim sitenize ait web sitesi ayarını bulun (örneğin
vitepress-prod.servbay.demo).- Düzenle butonuna tıklayın.
- Özel Konfigürasyon seçeneğini işaretleyin.
- Caddy yapılandırması metin kutusuna aşağıdaki örnek kodu girin.
servbay-vitepress-test.prodalan adını kendi kullandığınız alan adı ile ve site kök dizini yolunu kendi yolunuzla değiştirin:- macOS:
/Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist - Windows:
C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
- macOS:
bash# Kendi kullandığınız alan adıyla değiştirin, örn: vitepress-cleanurl.servbay.demo vitepress-cleanurl.servbay.demo { # Hızlı yükleme için Brotli (zstd) ve Gzip sıkıştırma aktif encode zstd gzip # ServBay varsayılan log ayarını ekleyin, hata ayıklama kolaylığı için import set-log vitepress-cleanurl.servbay.demo # ServBay’in otomatik SSL sertifikasını kullan tls internal # Temel ayar: dosya arama denemeleri # 1. Doğrudan yol (örn. /about -> /about) # 2. Dizindek index.html (örn. /guide/ -> /guide/index.html) # 3. .html ekleme (örn. /about -> /about.html) try_files {path} {path}/index.html {path}.html # Site kök dizinini belirtin # 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 # Statik dosya servisi başlatılsın 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
25Kaydedip ServBay’in ayarlarını uygulayın.
Temiz URL Modundaki Siteyi Ziyaret Etmek
Artık belirlediğiniz alan adından (ör.
https://vitepress-cleanurl.servbay.demo) sitenizi ziyaret edebilirsiniz.cleanUrlsaktif olan sayfalarda.htmleklemeye gerek olmadan doğrudan/aboutgibi URL’lerle erişebilirsiniz.
Sonuç
Bu rehberle ServBay ortamında VitePress dokümantasyon sitesi oluşturma, geliştirme ve dağıtma adımlarını öğrendiniz. ServBay, Node.js ortam yönetimini ve yerel web sunucusu yapılandırmasını kolaylaştırır; ister geliştirme aşamasında ters proxy ile, ister üretime geçtiğinizde statik dosya servisiyle hızlıca entegre olabilirsiniz. Ayrıca otomatik alan adı ve SSL sertifikası desteğiyle güvenli ve profesyonel bir deneyim sunar.
ServBay ve VitePress’in birleşimiyle, teknik dokümantasyonunuzu daha verimli ve kaliteli biçimde oluşturabilir ve sürdürebilirsiniz.
