ServBay Ortamında Jigsaw'un Kurulumu ve Yapılandırılması

Genel Bakış

Bu doküman, güçlü bir yerel Web geliştirme ortamı olan ServBay üzerinde Jigsaw statik site jeneratörünü nasıl kurup yapılandıracağınızı adım adım açıklar. ServBay, PHP, Node.js ve daha birçok teknoloji yığını için entegre bir geliştirme ortamı sunar, böylece Jigsaw projelerinizi hızlı ve kolay şekilde kurabilirsiniz. ServBay sayesinde, Jigsaw sitenizi yerel alan adı, HTTPS ve hızlı bir Web sunucusu ile yapılandırabilir, tüm odağınızı site içeriğine verebilirsiniz.

Jigsaw Nedir?

Jigsaw, Laravel bileşenleriyle geliştirilmiş, Tighten şirketi tarafından sunulan bir statik site jeneratörüdür. Laravel Blade şablon motorunun gücünü ve esnekliğini kullanır, Markdown dosyalarını okur ve saf statik HTML siteler oluşturur. Jigsaw özellikle dokümantasyon siteleri, bloglar, açılış sayfaları veya arka uç veri tabanı ve dinamik sunucu işlemlerine ihtiyaç duymayan her türlü site için idealdir. Temel avantajları şunlardır:

• Alışık olduğunuz araçları kullanır: Eğer Laravel veya Blade şablonlarına aşinaysanız, Jigsaw'u hızlıca öğrenebilirsiniz.
• Performans ve güvenlik: Oluşturulan statik siteler çok hızlı yüklenir ve sunucu tarafında kod çalışmadığı için güvenlik seviyesi yüksektir.
• Esnek şablonlar: Blade sayesinde karmaşık düzenler ve bileşenler oluşturabilirsiniz.
• Markdown desteği: İçeriğinizi kolayca yazabilirsiniz.

Kullanım Senaryoları

Jigsaw aşağıdaki projeler için oldukça uygundur:

• Proje ve API dokümantasyon siteleri
• Kişisel bloglar veya teknik paylaşım siteleri
• Kurumsal ya da ürün açılış sayfaları
• Küçük tanıtım siteleri
• Yüksek performans ve güvenlik gerektiren, içeriği sık değişmeyen web siteleri

Ön Koşullar

Başlamadan önce aşağıdaki şartları karşıladığınızdan emin olun:

1. ServBay'in kurulu ve çalışıyor olması: macOS'ta ServBay'i yükleyip başlatmanız gerekir. ServBay, Jigsaw için gerekli olan PHP, Composer ve Node.js/npm ile birlikte gelir.
2. Komut satırında temel yeterlilik: Terminalde birkaç komut çalıştırmanız gerekecek.
3. Composer ve npm hakkında temel bilgi: Jigsaw'un kurulumu Composer gerektirir, ön uç derlemeleri için de npm kullanılır.

Kurulum ve Yapılandırma Aşamaları

Bu bölümde, ServBay ortamında bir Jigsaw projesinin kurulumu ve yapılandırmasının detaylı adımlarını bulacaksınız.

Adım 1: Proje Dizinini Oluşturun

Öncelikle terminal uygulamanızı açın ve ServBay’in önerdiği web kök dizinine (/Applications/ServBay/www) giderek Jigsaw projeniz için yeni bir alt klasör oluşturun.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

Proje dizininin adı servbay-jigsaw-demo olacak ve tüm proje dosyalarınız bu dizinde saklanacak.

Adım 2: Composer ile Jigsaw Projesi Oluşturun

ServBay’de Composer önceden kurulmuş ve yapılandırılmıştır, bu nedenle terminalde doğrudan composer komutunu kullanabilirsiniz. Şimdi, yeni oluşturduğunuz proje dizininde (/Applications/ServBay/www/servbay-jigsaw-demo) aşağıdaki komutu çalıştırarak bir Jigsaw projesi başlatın:

composer create-project tightenco/jigsaw .

Bu komut, Jigsaw'un en son sürümünü ve tüm PHP bağımlılıklarını mevcut dizine (.) yükleyecektir. Komutun sonundaki . işareti, projenin doğrudan mevcut dizine kurulmasını, alt bir jigsaw klasörü oluşturulmamasını sağlar.

Adım 3: ServBay’de Web Sitesini Yapılandırın

Jigsaw sitenizi web tarayıcınızdan erişmek için, ServBay’de yeni bir yerel site yapılandırmanız gerekir.

1. ServBay Arayüzünü Açın: ServBay simgesine çift tıklayın veya menü çubuğundaki ServBay ikonundan kontrol paneline gidin.
2. “Web Siteleri”ne gidin: Sol menüden “Web Siteleri” sekmesine tıklayın.
3. Yeni Site Ekleyin: Arayüzün altındaki “+” düğmesine basın ve “Web Sitesi Ekle”yi seçin.
4. Site Bilgilerini Girin:
   • Ad (Name): Kolay tanıyabileceğiniz bir isim yazın, örneğin ServBay Jigsaw Demo.
   • Alan Adı (Domain): Yerel erişim için istediğiniz alan adını girin. Gerçek alan adlarıyla çakışmamak için .servbay.demo uzantısını kullanmanızı öneririz (örn. jigsaw-demo.servbay.demo). ServBay bu alan adını otomatik olarak yerelde çözecektir.
   • Site Türü (Site Type): PHP olarak seçin, çünkü Jigsaw’un oluşturma süreci PHP’ye ihtiyaç duyar.
   • PHP Sürümü (PHP Version): ServBay’de kurulu olan sürümlerden birini seçin; güncel ve kararlı bir sürüm tercih edin.
   • Site Kök Dizini (Site Root): Çok önemli bir adımdır. Jigsaw oluşturduğu statik dosyaları, proje klasörünüzdeki build_local dizininde tutar. Bu nedenle site kökünüzü aşağıdaki çıktı klasörüne yönlendirin: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Kaydedin ve Uygulayın: Tüm bilgileri girdikten sonra “Kaydet” tuşuna basın. ServBay, yapılandırma değişikliklerini uygulamanız için onay ister. Onayladığınızda ServBay, Web sunucu yapılandırmasını (Caddy veya Nginx) otomatik olarak güncelleyecek ve HTTPS yapılandıracaktır.

Adım 4: Ön Uç Bağımlılıklarını Kurun

Jigsaw projelerinde genellikle npm kullanılarak ön uç varlıklar (ör. SASS, JavaScript dosyaları) yönetilir ve derlenir. ServBay, Node.js ve npm’i dahili olarak kullanıma sunar.

Proje klasörünüzde (/Applications/ServBay/www/servbay-jigsaw-demo) şu komutu çalıştırın:

npm install

Bu, proje kökündeki package.json dosyasını okuyup gerekli Node.js modüllerini node_modules klasörüne indirecektir.

Adım 5: Jigsaw Sitesini Derleyin

Tüm bağımlılıkları kurduktan sonra, statik site çıktılarını oluşturmak için Jigsaw’u derlemeniz gerekir.

Proje klasörünüzde şu komutu çalıştırın:

./vendor/bin/jigsaw build

Bu komutun yaptığı işlemler:

1. source klasöründeki Markdown ve Blade dosyalarını işler.
2. webpack.mix.js dosyasında tanımlı derleme görevlerini uygular (eğer npm install ile Laravel Mix yüklendiyse).
3. Sonuçta oluşan HTML, CSS, JS ve diğer dosyaları build_local klasöründe toplar.

Adım 6: Sitenizi Görüntüleyin

Şimdi, Jigsaw sitenizin statik dosyaları, /Applications/ServBay/www/servbay-jigsaw-demo/build_local dizininde hazır. Site kök dizininizi ServBay’de buraya yönlendirdiğiniz için, yapılandırdığınız yerel alan adıyla sitenizi tarayıcıda görüntüleyebilirsiniz.

Web tarayıcınızı açın ve adım 3’te belirlediğiniz alan adına gidin, örneğin https://jigsaw-demo.servbay.demo. ServBay, yerel HTTPS sertifikalarını otomatik olarak yönetir (ServBay User CA kullanır) ve Jigsaw’un varsayılan karşılama sayfasını görmelisiniz.

Özelleştirme ve Geliştirme

Temel ortamınızı başarıyla kurdunuz, artık Jigsaw sitenizin içeriğini ve stilini gönlünüzce özelleştirebilirsiniz.

İçerik ve Şablonları Düzenleme

• Sitenizin kaynak kodu, proje kökündeki source klasöründedir.
• HTML düzenleri ve bileşenleri Blade şablonlarıyla, source/_layouts ve source/_partials gibi alt klasörlerde tutulur.
• Sayfa içeriklerinin çoğu Markdown formatındadır ve source veya alt dizinlerde bulunur (örn. source/index.md, source/about.md).
• Blog yazıları genellikle source/_posts klasöründe, YYYY-MM-DD-slug.md formatında yer alır.

Yeni Sayfa/Yazı Ekleme

Yeni bir sayfa veya blog yazısı eklemek için, sadece source klasörü ya da ilgili alt klasörde (örn. source/_posts) yeni bir Markdown dosyası oluşturun.

Örneğin, bir source/about.md dosyası eklemek için:

---
title: "Hakkımızda"
description: "ServBay Jigsaw Demo hakkında daha fazla bilgi edinin"
---

# Hakkımızda

Bu, Jigsaw kullanılarak oluşturulmuş bir hakkımızda sayfasıdır.

Burada şirket tanıtımı, takım bilgileri gibi içeriklere yer verebilirsiniz.

Stil ve Scriptleri Özelleştirme

Jigsaw projelerinde genellikle ön uç varlıkların derlenmesi için Laravel Mix (webpack.mix.js) kullanılır.

• Stil dosyaları (genellikle SASS/SCSS), source/_assets/sass klasöründe yer alır.
• JavaScript dosyaları source/_assets/js klasöründe bulunur.

Bu varlıkları derlemek için proje klasörünüzde npm komutlarını kullanabilirsiniz:

• npm run dev: Geliştirme için varlıkları derler, source map ekler, sıkıştırmaz.
• npm run watch: Geliştirme için varlıkları derler ve dosya değişikliklerini izleyip anında tekrar derler; geliştirme sürecinde çok kullanışlıdır.
• npm run prod: Üretim ortamı için varlıkları derler, genellikle minify ve optimize eder.

Örneğin, source/_assets/sass/main.scss dosyasını düzenledikten sonra, CSS dosyası oluşturmak için npm run dev veya npm run watch çalıştırabilirsiniz.

Siteyi Yeniden Oluşturma

Önemli Not: source klasöründeki içerik dosyalarını (Markdown) veya şablon dosyalarını (Blade) her değiştirdiğinizde aşağıdaki Jigsaw derleme komutunu tekrar çalıştırmalısınız:

./vendor/bin/jigsaw build

Eğer ön uç varlıklarında (SASS, JS) değişiklik yaptıysanız, ilgili derlemeyi tekrar üretmek için npm run dev veya npm run watch çalıştırmalısınız. Çoğu Jigsaw projesinde, Jigsaw’un build komutu Mix derlemesini de tetikler, ancak adım adım yapmak hata ayıklama için faydalı olabilir.

Dikkat Edilecekler

• Çıktı dizini: Jigsaw varsayılan olarak geliştirme için build_local, üretim için build_production dizinlerine çıktı verir. ServBay web kökünü erişmek istediğiniz dizine (genelde geliştirirken build_local) işaret ettiğinden emin olun.
• Web sunucu: ServBay, Caddy veya Nginx ile, build_local içindeki statik dosyaları doğrudan ve verimli şekilde sunar. Jigsaw’un dahili jigsaw serve komutunu kullanmanıza gerek yoktur (bu komut hızlı önizleme içindir, fakat ServBay’in tam özellikli web sunucusu kadar güçlü değildir).
• HTTPS: ServBay, .servbay.demo alan adları için otomatik olarak HTTPS yapılandırır ve ServBay User CA sertifikası ile sertifika üretir. Tarayıcıda güvenlik uyarıları almamak için CA sertifikasını sisteminize güvenilir olarak eklemeniz gerekebilir.
• Temiz derleme: Tuhaftı bir derleme sorunu ile karşılaşırsanız, şu komut ile temiz derleme yapabilirsiniz: ./vendor/bin/jigsaw build --clean.

Sık Sorulan Sorular (SSS)

S: Markdown dosyalarını değiştirdim ama tarayıcıda güncellenmiyor, neden?

C: İçerik veya şablonları değiştirdikten sonra tekrar ./vendor/bin/jigsaw build komutunu çalıştırmalısınız.

S: SCSS dosyasını değiştirdim ama stil değişmedi, neden?

C: Ön uç varlıklarını değiştirdikten sonra proje klasöründe npm run dev veya npm run watch komutlarını çalıştırarak stil dosyalarını tekrar üretmeniz gerekir.

S: Yerel alan adını açamıyor veya “dosya bulunamadı” uyarısı alıyorum. Ne yapmalıyım?

C: Şunları doğrulayın:

1. ServBay’in açık ve çalışıyor olması.
2. Site ayarlarının doğru yapılmış olması: Alan adınız ve site kökü /Applications/ServBay/www/servbay-jigsaw-demo/build_local dizinine işaret ediyor mu?
3. ./vendor/bin/jigsaw build komutunu başarıyla çalıştırdığınızdan ve build_local içinde (örn. index.html) dosyaların oluştuğundan emin olun.

S: Jigsaw sitesini nasıl canlıya alabilirim?

C: Jigsaw tamamen statik dosya üretir. Yaygın süreç aşağıdaki gibidir:

1. Üretim ortamı için ./vendor/bin/jigsaw build production komutunu çalıştırın (ekstra optimizasyonlarla).
2. build_production dizinindeki tüm dosyaları, Netlify, Vercel, GitHub Pages gibi statik site barındırma servislerine veya çeşitli bulut depolama alanlarına yükleyin.

Özet

ServBay sayesinde macOS ortamında Jigsaw statik site jeneratörü çok hızlı ve kolay şekilde kurulup yapılandırılabilir. ServBay ihtiyacınız olan tüm çalışma ortamını (PHP, Composer, Node.js, npm) ve güçlü bir yerel Web sunucusu entegrasyonu sunar. Bu rehberi takip ederek kısa sürede Jigsaw projesini başlatabilir, ServBay’in avantajları ile yerel geliştirme sürecinizi en üst düzeye çıkarabilirsiniz.