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:
- ServBay Kurulumu: macOS sisteminizde ServBay’in kurulu olması gereklidir. Eğer henüz kurmadıysanız, ServBay Kurulum Kılavuzu’na başvurabilirsiniz.
- 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
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:bashcd /Applications/ServBay/www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3VitePress 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:bashnpm add -D vitepress npx vitepress init
1
2veya Yarn ile:
bashyarn add -D vitepress yarn vitepress init
1
2Baş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ıcapackage.json
dosyanız dadocs:dev
vedocs:build
gibi script'lerle güncellenir.
VitePress Proje İçeriğini Düzenleme
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:markdown# Merhaba ServBay! VitePress dokümantasyon sitenizi ServBay ile çalıştırmaya hoş geldiniz. Bu, ServBay üzerindeki VitePress ile oluşturulmuş yerel bir demo sitesidir.
1
2
3
4
5
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.
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:bashnpm run docs:dev -- --port 8585
1veya
bashyarn docs:dev --port 8585
1Sunucu başarıyla başlarsa, örneğin
http://localhost:8585
adresinde çalışmaya başlar.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 üzerindenhttp://127.0.0.1:8585
portuna yönlendirecek şekilde web sunucusunu (Caddy veya Nginx) yapılandıracaktır.- Adı: Tanıyabileceğiniz bir isim, örneğin
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.
Üretim İçin Derleme
Terminalde
/Applications/ServBay/www/servbay-vitepress-app
kökünde şu komutu çalıştırın:bashnpm run docs:build
1veya
bashyarn docs:build
1Sü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.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.
- Adı: Örneğin
Ü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).
VitePress Konfigürasyonunda
cleanUrls
Özelliğini Etkinleştirindocs/.vitepress/config.mts
veyadocs/.vitepress/config.ts
dosyanızacleanUrls
ekleyin:typescript// docs/.vitepress/config.mts import { defineConfig } from 'vitepress' export default defineConfig({ // ... diğer ayarlar cleanUrls: true, // Temiz URL'leri etkinleştir // ... diğer ayarlar })
1
2
3
4
5
6
7
8Sonrasında
npm run docs:build
ile tekrar derleme yapın.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.
bash# 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 }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23Ayarları kaydedip uygulayın.
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ğinabout.html
yerinehttps://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.