ServBay ile VitePress Projesi Oluşturma ve Çalıştırma

VitePress, Vue tarafından desteklenen modern bir statik site üretecidir ve hızlı, estetik ve kolayca yönetilebilen dökümantasyon siteleri oluşturmak için tasarlanmıştır. Vite altyapısını kullanan VitePress, üstün bir geliştirme deneyimi ve olağanüstü derleme performansı sunar. Proje, kütüphane veya ürünleriniz için profesyonel dokümantasyon hazırlamak istiyorsanız VitePress mükemmel bir seçenektir.

Yerel bir ortamda VitePress geliştirme ve test sürecinde, kararlı ve kolay yapılandırılabilir bir web geliştirme ortamı çok önemlidir. İşte ServBay tam da bunun için geliştirilmiştir. Farklı Node.js sürümlerini barındıran entegre ortamı ve güçlü web sunucu desteğiyle (Caddy veya Nginx gibi) VitePress projelerinizi kolayca çalıştırabilirsiniz.

Bu makalede, ServBay’in entegre ortamını kullanarak sıfırdan bir VitePress projesi oluşturma, yapılandırma ve çalıştırma konusunda; geliştirme sunucusunda ters proxy ayarları uygulama ve üretim ortamı için statik dosya sunumu gibi adımlarda size rehberlik edeceğiz.

VitePress Nedir?

VitePress, Vite tabanlı bir statik site üreticisi (SSG) olup, Vue 3’ün güçlü özelliklerini ve Vite’in yüksek performansını kullanarak, özellikle teknik dokümantasyon siteleri için statik web siteleri oluşturmayı kolaylaştırır.

VitePress’in Temel Özellikleri ve Avantajları

• Yıldırım Hızında Geliştirme: Vite’in sıcak modül değiştirme (HMR) özelliği ile yaptığınız değişiklikleri neredeyse anlık olarak tarayıcıda görebilirsiniz.
• Vue ile Entegre: Markdown dosyalarında doğrudan Vue bileşenleri kullanabilirsiniz; bu sayede dokümanlarınızın etkileşimini ve sunumunu geliştirebilirsiniz.
• Kullanımı Kolay: Basit kurulumuyla hazır gelir, karmaşık ayarlara gerek yoktur, içeriğe odaklanabilirsiniz.
• Yüksek Performans: Üretilen statik dosyalar ufak boyutludur ve hızlı yüklenir; dahili client-side routing ile tek sayfa uygulaması (SPA) hissiyatı sunar.
• SEO Dostu: Üretilen HTML yapısı arama motorlarının kolayca taramasını sağlar ve özelleştirilebilir head etiketlerini destekler.
• Gelişmiş Markdown: CommonMark ve GitHub Flavored Markdown (GFM)’in tüm özellikleriyle birlikte ekstra sentaks desteği sunar.

VitePress ile geliştiriciler, yüksek kaliteli ve hızlı dökümantasyon sitelerini zahmetsizce kurabilirler.

ServBay ile VitePress Projesi Oluşturmak ve Çalıştırmak

ServBay, Node.js sürümlerinin kolayca yönetilmesini sağlar ve web sunucusunun VitePress projenize uygun şekilde yapılandırılmasını mümkün kılar. Böylece gerek geliştirme, gerekse üretim ortamı için optimum bir çözüm sunar.

Gereksinimler

Başlamadan önce aşağıdaki ön hazırlıklara sahip olduğunuzdan emin olun:

1. ServBay Kurulumu: macOS sisteminizde ServBay’in kurulu olması gereklidir. Eğer henüz kurmadıysanız, ServBay Kurulum Kılavuzu’na başvurabilirsiniz.
2. Node.js Paketlerinin Kurulumu: ServBay üzerinde ihtiyacınız olan Node.js sürümünü kurup etkinleştirdiğinizden emin olun. Bunun için ServBay kontrol panelindeki "Paketler" bölümünü kullanabilirsiniz. Daha fazlası için Node.js Kullanımı dokümanına göz atın.

VitePress Projesi Oluşturma

1. Proje Dizinini Başlatın

   Önce terminal uygulamanızı açın. ServBay varsayılan web kök dizini olan /Applications/ServBay/www altında yeni bir proje klasörü oluşturmanız önerilir:

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

2. VitePress Kurulumu ve Başlangıç Yapılandırması

   servbay-vitepress-app dizininde, npm veya yarn ile VitePress’i geliştirici 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 sizi temel ayarlar konusunda yönlendirecek, örneğin site başlığı ve açıklaması:

    ┌  VitePress'e Hoş Geldiniz!
    │
    ◇  VitePress yapılandırması nereye kurulsun?
    │  ./docs  # Varsayılan doküman dizini, Enter ile onaylayabilirsiniz
    │
    ◇  Site başlığı:
    │  ServBay VitePress Demo # Siteniz için bir başlık girin (örneğin ServBay VitePress Demo)
    │
    ◇  Site açıklaması:
    │  ServBay üzerinde çalışan bir VitePress sitesi # Site açıklamanızı girin
    │
    ◇  Tema:
    │  Varsayılan Tema # Temayı seçin, varsayılan tema uygundur
    │
    ◇  Yapılandırma ve tema dosyalarında TypeScript kullanılsın mı?
    │  Evet # Tercihinize bağlı olarak seçin
    │
    ◇  VitePress npm script'leri package.json'a eklensin mi?
    │  Evet # package.json'a script eklemeniz önerilir
    │
    └  Tamamlandı! Şimdi npm run docs:dev ile yazmaya başlayabilirsiniz.

   Süreç sonunda VitePress, proje kökünüzde docs adında bir klasör, içinde varsayılan ayar dosyaları (.vitepress) ve örnek sayfalar (index.md, guide/index.md gibi) oluşturur. Ayrıca package.json dosyanız da docs:dev ve docs:build gibi script'lerle güncellenir.

VitePress Proje İçeriğini Düzenleme

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

   VitePress’in varsayılan ana sayfa dosyası docs/index.md içindedir. İstediğiniz düzenleyiciyle bu dosyayı açıp içeriğini değiştirebilirsiniz. Örneğin:

   # Merhaba ServBay!
   
   VitePress dokümantasyon sitenizi ServBay ile çalıştırmaya hoş geldiniz.
   
   Bu, ServBay üzerindeki VitePress ile oluşturulmuş yerel bir demo sitesidir.

Geliştirme Moduna Geçiş

VitePress ile geliştirirken, genellikle dahili geliştirme sunucusu üzerinden çalışılır; bu mod, canlı güncellemeler ve anlık önizleme imkânı sağlar. ServBay’in ters proxy özelliğiyle kendi alan adınız üzerinden geliştirme sunucusuna ulaşabilir ve SSL şifrelemesinden faydalanabilirsiniz.

1. VitePress Geliştirme Sunucusunu Başlatın

   Terminalde /Applications/ServBay/www/servbay-vitepress-app dizinine girin ve geliştirme sunucusunu, örneğin 8585 portunu belirterek başlatın:

   npm run docs:dev -- --port 8585

   veya

   yarn docs:dev --port 8585

   Sunucu başarıyla başlarsa, örneğin http://localhost:8585 adresinde çalışmaya başlar.

2. ServBay Sitesi (Ters Proxy) Ayarları

   ServBay kontrol panelini açın ve "Web Siteleri" sekmesinde yeni bir site ekleyin:

   • Adı: Tanıyabileceğiniz bir isim, örneğin VitePress Geliştirme Sitesi.
   • Alan Adı: Tarayıcıda ulaşmak istediğiniz geliştirme alan adı. ServBay markasına uygunluğu ve çakışmaları önlemek için .servbay.demo uzantısını öneririz (örn. vitepress-dev.servbay.demo).
   • Site Tipi: Ters Proxy seçin.
   • IP: 127.0.0.1 yazın (lokal makine).
   • Port: Yukarıda kullandığınız portu yazın (örn. 8585).

   Ayarları kaydedip uygulayın. ServBay, trafikleri https://vitepress-dev.servbay.demo adresi üzerinden http://127.0.0.1:8585 portuna yönlendirecek şekilde web sunucusunu (Caddy veya Nginx) yapılandıracaktır.

3. Geliştirme Sitesine Erişim

   Artık tarayıcıdan https://vitepress-dev.servbay.demo adresine gidebilirsiniz. Geliştirme sunucusunda çalışan içeriği göreceksiniz. ServBay sayesinde özel alan adınız ve kendi kullanıcı CA’sı tarafından imzalanmış SSL ile güvenli HTTPS bağlantınız olacak.

Üretim Sürümünü Oluşturma

VitePress dokümantasyonunuzu tamamladığınızda ve yayımlamaya hazır olduğunuzda optimize edilmiş bir statik yapıya ihtiyaç duyarsınız.

1. Üretim İçin Derleme

   Terminalde /Applications/ServBay/www/servbay-vitepress-app kökünde şu komutu çalıştırın:

   npm run docs:build

   veya

   yarn docs:build

   Süreç sonunda Markdown dosyalarınız, Vue bileşenleriniz optimize edilmiş HTML, CSS ve JavaScript dosyalarına dönüştürülür. Statik dosyalar, varsayılan olarak docs/.vitepress/dist dizininde yer alacaktır.

2. ServBay Sitesi (Statik Dosya Hizmeti) Ayarları

   Üretim sürümü yalnızca statik dosyalardan oluşur; ServBay’in statik dosya servisi ile bunları doğrudan yayınlayabilirsiniz.

   Kontrol panelinde yeni bir web sitesi ekleyin:

   • Adı: Örneğin VitePress Üretim Sitesi.
   • Alan Adı: Üretim sitesi için istediğiniz alan adı (örn. vitepress-prod.servbay.demo).
   • Site Tipi: Statik olarak seçin.
   • Kök Dizin: Oluşan statik dosyaların kesin yolu: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist

   Kaydedip başlatınca, ServBay bu dizinden statik dosya servis edecektir.

3. Üretim Sitesine Erişim

   Tarayıcınızdan https://vitepress-prod.servbay.demo adresine gidebilir ve üretim ortamınızı görebilirsiniz. ServBay, otomatik olarak alan adı ve SSL sertifikası hizmeti sunar.

Temiz URL Modunda (cleanUrls: true) Çalıştırma

VitePress, cleanUrls: true ayarına (bkz. dökümantasyon) sahiptir. Bu modda bağlantılar .html uzantısı olmadan, örneğin /guide/ veya /about olarak çalışır. Web sunucunuzun bu istekleri doğru şekilde karşılaması için ilave yapılandırma gerekir.

ServBay, Caddy veya Nginx web sunucusu kullanır. Aşağıda Caddy için bir yapılandırma örneği verilmiştir. Bu yapılandırma, gelen isteklere uygun dosyayı bulmak için try_files yönergesine dayanır (örn. /about, /about.html veya /guide/index.html gibi).

1. VitePress Konfigürasyonunda cleanUrls Özelliğini Etkinleştirin

   docs/.vitepress/config.mts veya docs/.vitepress/config.ts dosyanıza cleanUrls ekleyin:

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

   Sonrasında npm run docs:build ile tekrar derleme yapın.

2. ServBay Sitesi İçin Özelleştirilmiş Caddy Yapılandırması

   Kontrol panelinde, üretim sitesi yapılandırmanızı açın (örn. vitepress-prod.servbay.demo).

   • Düzenle butonuna tıklayın.
   • Özelleştirilmiş yapılandırma kutucuğunu işaretleyin.
   • Caddy yapılandırması alanına aşağıdaki örnek ayarları girin. Dikkat: servbay-vitepress-test.prod kısmını kendi alan adınızla, kök dizini ise kendi yolunuzla değiştirin.

   # Kendi alan adınızı kullanın, örn. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Brotli (zstd) ve Gzip sıkıştırmasını etkinleştir, daha hızlı yükleme için
       encode zstd gzip
   
       # ServBay varsayılan log ayarını dahil et, hata ayıklamayı kolaylaştırır
       import set-log vitepress-cleanurl.servbay.demo
   
       # ServBay'in iç SSL sertifikalarını otomatik işleme
       tls internal
   
       # Çekirdek ayar: dosya arama sırası
       # 1. Doğrudan dosya arama (örn. /about -> /about)
       # 2. Dizin altında index.html arama (örn. /guide/ -> /guide/index.html)
       # 3. .html uzantılı dosya arama (örn. /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Web sitesi kök dizinini belirt
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Statik dosya servisini aktif et
       file_server
   }

   Ayarları kaydedip uygulayın.

3. Temiz URL Kipiyle Siteye Erişim

   Artık ilgili alan adından (örn. https://vitepress-cleanurl.servbay.demo) erişim sağlayabilirsiniz. cleanUrls etkin olduğunda, örneğin about.html yerine https://vitepress-cleanurl.servbay.demo/about gibi uzantısız bir link ile istediğiniz sayfaya ulaşabilirsiniz.

Sonuç

Bu rehberle ServBay ortamında bir VitePress dokümantasyon sitesi oluşturmayı, geliştirmeyi ve dağıtmayı öğrendiniz. ServBay, Node.js ortam yönetimini ve yerel web sunucu yapılandırmasını önemli ölçüde kolaylaştırır. İster geliştirme sırasında ters proxy üzerinden, ister üretimde statik dosya servisinde olun, hızlıca kurulum yapabilir; otomatik olarak özel alan adı ve SSL sertifika desteğinden yararlanabilirsiniz.

ServBay ile VitePress’in avantajlarını birleştirerek, yüksek kaliteli teknik dokümantasyonlarınızı çok daha verimli biçimde oluşturup yönetebilirsiniz.