Cloudflare Pages ile Hugo Sitesi Yayınlama (Hugo Deploy Rehberi)

Hugo ile web sitesi yapımı, özellikle performans ve bakım kolaylığı isteyen ekipler için son yıllarda çok popüler hale geldi. Ancak statik site üretmek tek başına yeterli değil; asıl fark, bu siteyi global CDN üzerinde hızlı, güvenli ve sürdürülebilir bir şekilde yayınlayabildiğinizde ortaya çıkıyor. İşte bu noktada Cloudflare Pages devreye giriyor: Git tabanlı bir akışla (GitHub/GitLab), her commit’te otomatik build alıp yayına çıkabilen, ayrıca preview deployments ile PR bazlı önizleme linkleri üretebilen güçlü bir statik site hosting çözümü.

Bu yazıda “Cloudflare Pages ile Hugo sitesi yayınlama” sürecini uçtan uca ele alacağız: doğru repo hazırlığı, hugo deploy için Cloudflare Pages build ayarları, baseURL ve asset path problemlerini önleme, custom domain + DNS + SSL adımları, branch/preview stratejisi ve en sık karşılaşılan hataların pratik çözümleri. Hedef, yalnızca “yayına aldım” demek değil; aynı zamanda SEO açısından temiz (canonical, sitemap, robots) ve teknik olarak sağlam bir kurulum yapmak.

Cloudflare Pages ve Hugo: Neden Bu İkili?

Cloudflare Pages, statik siteleri Git üzerinden otomatik olarak yayınlamaya odaklanan bir platform. En güçlü yanları:

• Global CDN: İçerik, ziyaretçiye en yakın noktadan servis edilir (TTFB ve genel hız için çok iyi).
• Preview Deployments: Pull Request (PR) veya branch bazlı otomatik önizleme URL’leri.
• Kolay custom domain ve otomatik HTTPS: Sertifika yönetimiyle uğraşmadan SSL/TLS.
• Basit build mantığı: Doğru build command ve output directory ile kısa sürede yayına çıkarsınız.

Hugo ise Go tabanlı, çok hızlı bir statik site üreteci. Büyük içerik sitelerinde bile build süreleri genellikle oldukça kısadır. Bu ikili birleştiğinde, özellikle “kurumsal blog”, “dokümantasyon”, “landing page setleri” gibi senaryolarda hem maliyet hem performans açısından güçlü bir çözüm elde edersiniz.

Statik site faydaları burada netleşir: Veritabanı yok, saldırı yüzeyi küçük, cache mantığı doğal, ölçekleme derdi yok. Bu yüzden “statik site hosting” arayan ekipler için Cloudflare Pages + Hugo kombinasyonu sıkça önerilir. Statik mi dinamik mi kararsızsanız, karar çerçevesi için şu yazı da yardımcı olur: Statik Site mi Dinamik CMS mi? Hugo ve Drupal Ne Zaman?

Yayına Hazırlık: Repo Yapısı, BaseURL ve Hugo Build Mantığı

Cloudflare Pages tarafına geçmeden önce, Hugo projenizin deploy’a hazır olduğundan emin olalım. En kritik noktalar genellikle şuralarda sorun çıkarır:

1) Proje çıktısı: public/ klasörü (output directory)

Hugo build aldığınızda çıktıyı varsayılan olarak public/ klasörüne yazar. Cloudflare Pages “Build output directory” alanına genellikle public girmeniz gerekir. En sık yapılan hata, bunu dist gibi başka bir klasör sanmak.

2) baseURL doğru değilse ne olur?

baseURL yanlış ayarlanırsa şu problemler görülebilir:

• Deploy sonrası CSS/JS çalışmıyor, sayfa “çıplak” görünüyor
• Canonical URL’ler yanlış çıkar, SEO tarafında kopya içerik riski oluşur
• RSS/sitemap linkleri hatalı üretilebilir

İlk aşamada Cloudflare Pages size bir *.pages.dev adresi verecek. İsterseniz ilk deploy’u bu adresle test edip sonra custom domain’e geçebilirsiniz. Örnek hugo.toml (veya config.toml) yaklaşımı:

baseURL = "https://proje-adi.pages.dev/"
languageCode = "tr-tr"
title = "Örnek Hugo Site"

Custom domain bağladıktan sonra bunu:

baseURL = "https://www.ornekdomain.com/"

şeklinde güncellersiniz.

3) Üretim build komutu: hugo --minify

Cloudflare Pages build ayarında “Build command” olarak çoğu senaryoda şunu kullanabilirsiniz:

hugo --minify

Bu, HTML/CSS/JS çıktılarında küçültme yaparak performansa katkı sağlar. “Core Web Vitals” odağınız varsa statik sitelerin neden avantajlı olduğuna dair şu içeriğe de göz atabilirsiniz: Core Web Vitals ve Statik Siteler: Neden Daha Hızlı?

4) .gitignore ve commit düzeni

Genelde public/ klasörü repoya commit edilmez; Cloudflare Pages build sırasında kendisi üretir. .gitignore içinde public/ olması normaldir.

Cloudflare Pages’te Hugo Deploy: Build Ayarları (Adım Adım)

Şimdi “cloudflare pages hugo” kurulumuna geçelim. Amaç: Git repo → otomatik build → otomatik yayın.

1) Cloudflare Pages’te proje oluşturma

1. Cloudflare hesabınıza giriş yapın.
2. Pages bölümüne gidin.
3. Create a project (Proje oluştur) seçin.
4. Git sağlayıcınızı bağlayın: GitHub veya GitLab
5. Hugo projenizin bulunduğu repoyu seçin.

2) Framework preset ve manuel ayarlar

Cloudflare Pages bazen Hugo için hazır preset sunar. Sunmuyorsa manuel girmeniz yeterli.

Aşağıdaki ayarlar çoğu Hugo projesi için standarttır:

• Build command: hugo --minify
• Build output directory: public
• Root directory: Repo kökü (monorepo ise ör. /site)

Monorepo örneği: Eğer repo içinde apps/site gibi bir klasörde Hugo projesi varsa, “Root directory” alanına onu girin. Bu, “cloudflare pages hugo root directory monorepo” gibi long-tail aramalarda da sık karşılaşılan bir ihtiyaç.

3) Hugo sürümü ve “extended” ihtiyacı

Bazı temalar SCSS/SASS pipeline kullanır ve Hugo Extended gerektirir. Eğer build loglarında “extended required” benzeri bir hata görürseniz:

• Temanızın dokümantasyonunu kontrol edin (extended şart mı?)
• Cloudflare Pages build ortamında Hugo sürüm/variant seçimi için environment variable veya platformun sunduğu ayarları kullanın.

Bu konu sıkça “cloudflare pages build failed hugo extended” şeklinde aranır. İpucu: Build loglarını okumak, sorunun %80’ini tek başına çözer—hangi sürüm bekleniyor, hangi modül eksik, hangi path bulunamıyor net yazar.

4) Deploy sonrası kontrol listesi (ilk 5 dakika)

Deploy bittiğinde şu kontrolleri yapın:

• Ana sayfa açılıyor mu?
• CSS/JS düzgün yükleniyor mu?
• İç linkler 404 veriyor mu?
• sitemap.xml oluşmuş mu? (Hugo’da genellikle otomatik)
• robots.txt var mı/isteniyor mu?

İçerik üretimi ve pazarlama hedefleri olan sitelerde, yayın sonrası ölçümleme zincirini baştan kurgulamak da önemli. Özellikle lead toplayan sayfalarda şu rehber iyi bir tamamlayıcıdır: Web Sitesinden Lead: Form, CRM ve Ölçümleme Zinciri

Custom Domain, DNS ve SSL: Cloudflare Pages Custom Domain Kurulumu

Projeyi *.pages.dev altında çalıştırmak hızlıdır ama kurumsal kullanımda genellikle özel alan adı (custom domain) şarttır. “cloudflare pages custom domain” kurulumunda amaç; doğru DNS kayıtları, doğru yönlendirme stratejisi ve tek bir canonical host belirlemektir.

1) Custom domain ekleme

Cloudflare Pages projenize girin → Custom domains → domaininizi ekleyin:

• ornekdomain.com (apex)
• www.ornekdomain.com (www)

Genellikle ikisini birden ekleyip birini “primary” yapmanız iyi olur.

2) Apex mi www mu? (SEO ve yönlendirme stratejisi)

Burada kritik olan, iki hostu aynı anda “asıl” gibi kullanmamak. Seçenekler:

• www primary: www.ornekdomain.com canonical, apex → www 301
• apex primary: ornekdomain.com canonical, www → apex 301

Hangi seçeneği seçerseniz seçin:

• Hugo baseURL değerini buna göre ayarlayın
• Cloudflare Pages/Cloudflare DNS tarafında yönlendirmeyi netleştirin

3) DNS kayıtları: CNAME/AAAA/A konusu

DNS tarafında Cloudflare size yönlendirme/record önerileri sunar. Genel mantık:

• www için çoğunlukla CNAME kullanılır (Pages’in verdiği hedefe)
• Apex domain için platformun yönlendirmesine göre CNAME flattening benzeri davranışlar devreye girebilir (Cloudflare DNS bunu kolaylaştırır)

DNS değişiklikleri sonrası “çalışmıyor” demeden önce:

• Yayılım (propagation) süresini bekleyin
• Cloudflare’ın gösterdiği doğrulama adımlarını tamamlayın

4) SSL/TLS ne kadar sürer?

“cloudflare pages ssl ne kadar sürer” sorusunun cevabı: çoğu zaman dakikalar içinde, bazen daha uzun sürebilir. Sertifika hazırlanırken kısa süreli uyarılar görebilirsiniz. Bu sırada “Always Use HTTPS” ve HSTS gibi ayarları aceleyle açmadan önce sitenin stabil çalıştığından emin olun.

Preview Deployments, Branch Stratejisi ve Sorun Giderme (Troubleshooting)

Cloudflare Pages’in B2B ekipler için en güçlü yanlarından biri preview deployments. PR açtığınızda otomatik bir preview URL oluşur. Bu sayede:

• İçerik ekibi Markdown değişikliklerini PR ile gönderebilir
• Tasarım/tema değişiklikleri canlıya çıkmadan test edilir
• main prod, develop staging gibi bir akış kurulabilir

Önerilen branch yaklaşımı

• main: Production
• develop: Staging/QA
• Feature branch + PR: Preview

Bu düzen, özellikle birden fazla kişinin içerik girdiği Hugo projelerinde hataları azaltır.

En sık hatalar ve hızlı çözümler

Aşağıdaki başlıklar, “cloudflare pages 404”, “deploy sonrası css çalışmıyor”, “site güncellenmiyor cache” gibi aramalarda da sık karşılık bulur:

1. Deploy oldu ama CSS/JS yok

• baseURL yanlış olabilir (en yaygını)
• Tema asset path’leri absolute bekliyor olabilir
• Geçici test için baseURL’i pages.dev adresinize set edip tekrar deneyin

2. 404 hatası alıyorum

• “Build output directory” yanlış girilmiş olabilir (public olmalı)
• Hugo gerçekten build alıyor mu? Build log’unda public/ içine dosya yazıldığını doğrulayın
• URL yapısı (trailing slash) ile sunucu davranışı çakışıyor olabilir (genelde Pages statik hostingte daha nadir)

3. Site güncellenmiyor (cache şüphesi)

• Cloudflare Pages CDN doğası gereği hızlı cache davranışı gösterir
• Genellikle yeni deploy sonrası sorun kalmaz; ancak tarayıcı cache’i yanıltabilir (hard refresh deneyin)
• Asset fingerprinting (Hugo Pipes) kullanıyorsanız zaten bu sorun azalır

4. Build failed: Hugo Extended / sürüm uyumsuzluğu

• Tema dokümantasyonundaki minimum Hugo sürümünü kontrol edin
• Gerekirse Hugo sürümünü sabitleyin (build ortamında aynı sürümü kullanmak, “bende çalışıyor” problemlerini azaltır)

Son olarak, yayın sonrası SEO planınızda yalnızca klasik SEO değil, içeriklerin farklı arama yüzeylerinde bulunabilirliği (GEO gibi) de konuşuluyorsa şu yazı iyi bir çerçeve sunar: SEO ve GEO Birlikte Nasıl Planlanır?

İç Bağlantı Önerileri

• SEO ve GEO Birlikte Nasıl Planlanır?
• Web Sitesinden Lead: Form, CRM ve Ölçümleme Zinciri
• Statik Site mi Dinamik CMS mi? Hugo ve Drupal Ne Zaman?
• Core Web Vitals ve Statik Siteler: Neden Daha Hızlı?