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:

1. ServBay’in kurulmuş olması: Sistemde ServBay’in başarıyla kurulmuş olması gerekir. Henüz kurmadıysanız, ServBay Kurulum Rehberi‘ni inceleyin.
2. 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

1. 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:

   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. VitePress’in Kurulumu ve Yapılandırma Başlatma

   servbay-vitepress-app klasöründe npm veya yarn ile VitePress’i geliştirme bağımlılığı olarak kurup başlatma komutunu çalıştırın.

   npm add -D vitepress
   npx vitepress init

   veya Yarn ile:

   yarn add -D vitepress
   yarn vitepress init

   Baş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-app klasöründe bir docs alt dizini oluşturur ve içinde varsayılan yapılandırma dosyasını (.vitepress) ve örnek sayfaları (index.md, guide/index.md vb.) yaratır. Ayrıca package.json dosyası da docs:dev, docs:build gibi komutlarla güncellenir.

VitePress Proje İçeriğini Düzenleme

1. Ana Sayfa İçeriğini Düzenleme

   VitePress’in varsayılan ana sayfa dosyası docs/index.md içinde bulunur. Herhangi bir metin editörüyle açıp dilediğiniz gibi düzenleyebilirsiniz. Örneğin şöyle değiştirebilirsiniz:

   # 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.

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.

1. 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):

   npm run docs:dev -- --port 8585

   veya Yarn ile:

   yarn docs:dev --port 8585

   Sunucu 8585 portunda çalışacak ve genellikle http://localhost:8585 adresinde erişilebilir olacaktır.

2. 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.demo uzantısını kullanmanız önerilir; örneğin vitepress-dev.servbay.demo.
   • Site Türü: Ters Proxy seçin.
   • IP Adresi: 127.0.0.1 yazı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.demo alan adındaki talepleri http://127.0.0.1:8585 adresine yönlendirecek şekilde otomatik ayarlar.

3. 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.

1. Ü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:

   npm run docs:build

   veya Yarn ile:

   yarn docs:build

   Yapı 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/dist dizininde bulunur.

2. 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

   Ayarları kaydedip ServBay’in yapılandırmasını uygulayın. ServBay web sunucusu, belirlediğiniz kök dizinden statik dosyaları doğrudan servis edecektir.

3. Üretim Sürümünü Ziyaret Etme

   Tarayıcıda https://vitepress-prod.servbay.demo adresine 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).

1. VitePress Yapılandırmasında cleanUrls Aktifleştirme

   VitePress config dosyanızı (docs/.vitepress/config.mts veya docs/.vitepress/config.ts) açıp siteConfig bölümünde cleanUrls seçeneğini ekleyin veya düzenleyin:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... diğer ayarlar
     cleanUrls: true, // Temiz URL aktif
     // ... diğer ayarlar
   })

   Ardından tekrar npm run docs:build ile üretim sürümünü oluşturun.

2. 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.prod alan 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

   # 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
   }

   Kaydedip ServBay’in ayarlarını uygulayın.

3. Temiz URL Modundaki Siteyi Ziyaret Etmek

   Artık belirlediğiniz alan adından (ör. https://vitepress-cleanurl.servbay.demo) sitenizi ziyaret edebilirsiniz. cleanUrls aktif olan sayfalarda .html eklemeye gerek olmadan doğrudan /about gibi 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.