Geliştirme yaparken karşılaştığım mimari problemleri, donanım testlerimi ve sunucu loglarımı kendi “context window"umdan uçup gitmeden önce kaydetmek için uzun zamandır temiz bir blog altyapısı arıyordum. Veritabanı şişkinliği, sunucu maliyeti veya eklenti cehennemiyle uğraşmak istemediğim için rotamı Statik Site Oluşturuculara (SSG) çevirdim.

Tercihim, Go dilinin gücünü arkasına alan ve milisaniyeler içinde derlenen Hugo oldu. Tema olarak ise minimalizmi ve performansıyla öne çıkan PaperMod‘da karar kıldım.

Bu yazıda, bu blogun arkasındaki “Sıfır Maliyet, Maksimum Hız” mimarisini ve kurulum sırasında Cloudflare tarafında yaşadığım birkaç ilginç (ve sinir bozucu) “gotcha” anını paylaşacağım.

Mimari Kararlar

Sistemin akışı oldukça basit ve tamamen Git-ops mantığına dayanıyor:

  1. Lokal Ortam: Mac M4 üzerinde Markdown dosyalarıyla notlarımı tutuyorum.
  2. Depolama: Kodlar ve içerikler Private (Gizli) bir GitHub reposunda duruyor. Yani mutfağın kapısı dışarıya kapalı.
  3. Yayınlama (Deployment): GitHub’a push yaptığım anda Cloudflare Pages webhook ile tetikleniyor, repoyu çekiyor, Hugo’yu çalıştırıyor ve sitenin güncel halini global CDN üzerinden yayına alıyor.

Karşılaştığım Sorunlar ve Çözümleri

Kağıt üzerinde her şey harika dursa da, kurulum aşamasında birkaç sinsi tuzağa düştüm. İşte o tuzaklar ve çözümleri:

1. Cloudflare’in “Workers vs Pages” Karmaşası

Cloudflare yakın zamanda arayüzünü güncelleyip Workers ve Pages’i aynı menü altına aldı. Başlangıçta yanlışlıkla statik site yerine bir “Worker” oluşturmuşum. Cloudflare, verdiğim hugo --minify komutunu ezip inatla projeyi bir Node.js uygulaması sanarak npx wrangler deploy çalıştırmaya kalktı. Çözüm: Yanlışlıkla açılan Worker’ı tamamen silip, projeyi sağ üstteki gizli açılır menüden spesifik olarak “Pages” sekmesinden yeniden oluşturmak. Framework preset olarak Hugo seçtiğinizde her şey tıkır tıkır işliyor.

2. Minify ve JSON Hatası (Kritik Detay)

Sistemi ayağa kaldırdıktan sonra hugo --minify komutu aniden şu hatayla patladı: expected comma character or an array or object Nedeni: PaperMod, SEO için arka planda bir JSON-LD şeması oluşturuyor. Eğer Markdown dosyanızın front-matter (ayar) kısmında, title içinde fazladan çift tırnak (") kullanırsanız bu JSON yapısı bozuluyor ve minify işlemi çöküyor. Çözüm: Başlıklarda çift tırnak yerine tek tırnak (') kullanmak veya Cloudflare üzerindeki build komutundan --minify bayrağını kaldırmak.

3. PaperMod Kapak Görseli (Cover Image) Boyut Sorunu

Tema, yazılara eklediğiniz kapak resimlerini (ne kadar küçük olurlarsa olsunlar) zorla ekranın %100’üne yayarak piksellenmesine neden oluyordu. Çözüm: Temanın kök dosyalarına dokunmadan, orijinal yapıyı ezmek (override) için projede assets/css/extended/custom.css dizinini oluşturdum ve şu kodu ekledim:

.entry-cover { text-align: center; }
.entry-cover img {
    width: auto !important;
    max-width: 100% !important;
    margin: 0 auto !important;
    display: inline-block !important;
}