Kendi Blog Altyapınızı Sıfırdan Yazmak: Markdown'dan SEO Dostu HTML'e

Bir geliştiricinin blog açmak için önünde hazır onlarca seçenek var: WordPress, Ghost, statik site üreteçleri... Ben yine de bu sitenin paylaşım sistemini sıfırdan yazmayı seçtim — kısmen öğrenmek için, kısmen de tam kontrole sahip olmak için. Bu yazıda o sürecin teknik kararlarını anlatıyorum: içerik nerede yaşar, markdown nasıl HTML olur, arama motoru ne görür ve hangi ayrıntılar gerçekten fark yaratır. Kendi altyapısını yazmayı düşünen herkes için yol haritası niyetine.

İçeriğin tek doğruluk kaynağı: markdown

İlk karar içeriğin formatıydı ve cevap netti: markdown, veritabanında saklanır. HTML'i elle yazmak sürdürülemez; WYSIWYG editörlerin ürettiği HTML ise zamanla çöp birikintisine dönüşür. Markdown ikisinin de iyi yanlarını taşır: düz metin olarak okunabilir, sürümlenebilir, her editörde yazılabilir.

Benim akışım şöyle çalışır: makaleyi bilgisayarımda bir makale.md dosyası olarak yazarım (başında başlık, kategori, özet gibi alanları tutan bir ön blok ile); yayınlarken içerik yönetim panelinden gövdeyi yapıştırır, kapak görselini yüklerim. Sunucu, markdown'ı veritabanına kaydeder ve sayfa istendiğinde HTML'e çevirir. Kaynak her zaman markdown'dır; HTML her zaman türetilmiş üründür. Bu ayrım önemli: ileride tasarımı tamamen değiştirseniz bile içeriğinize dokunmanız gerekmez.

Render kararı: istemci mi, sunucu mu?

İlk sürümümde markdown'ı tarayıcıda, JavaScript ile render ediyordum. Çalışıyordu — ta ki sayfanın kaynağına bakana kadar: arama motorunun gördüğü şey, içerik yerine bir yükleme animasyonu ve ham markdown'dı. İçerik sitesi için bu, görünmez olmakla eşdeğer.

Bugünkü mimari: sunucu tarafı render (SSR) esas, istemci süslemesi ek. Sayfa istendiğinde sunucu, markdown'ı semantik HTML'e çevirip tam içerikli bir sayfa döner; tarayıcıdaki JavaScript ise üzerine yalnızca etkileşim ekler (içindekiler tablosu, kod kopyalama düğmesi, görsel büyütme). JavaScript hiç çalışmasa bile içerik eksiksiz okunur.

app.get('/shares/:slug', (req, res) => {
  db.get('SELECT * FROM shares WHERE slug = ?', [req.params.slug], (err, yazi) => {
    if (!yazi) return res.status(404).send(notFoundPage);
    const govdeHtml = markdownToHtml(yazi.content);  // sunucuda çevir
    res.send(sayfaSablonu({ ...yazi, govdeHtml }));
  });
});

Bu kararın yan faydası performans oldu: içerik ilk baytta geldiği için sayfalar, istemci render'lı hâline göre gözle görülür hızlı açılıyor.

URL ve slug: küçük görünen büyük karar

/yazi?id=42 ile /shares/rest-api-tasarimi arasında hem kullanıcı hem arama motoru için dağlar kadar fark var. Slug üretirken Türkçe'nin inceliklerini unutmamak gerekiyor:

function slugUret(baslik) {
  return baslik
    .toLowerCase()
    .replace(/ğ/g, 'g').replace(/ü/g, 'u').replace(/ş/g, 's')
    .replace(/ı/g, 'i').replace(/ö/g, 'o').replace(/ç/g, 'c')
    .replace(/[^a-z0-9]+/g, '-')   // kalan her şey tire
    .replace(/^-+|-+$/g, '');      // baş/son tireleri kırp
}

İki kural daha: slug bir kez yayınlandıktan sonra değişmez (değişecekse eskisinden yenisine 301 yönlendirme şart) ve her sayfa kendi canonical adresini beyan eder. Aynı içeriğin ?utm_source=... gibi parametreli kopyaları, canonical etiketi sayesinde arama motorunda tek sayfada birleşir.

Arama motorunun gördüğü katman

İçerik hattının görünmeyen ama kritik parçaları:

• Sitemap. Statik bir dosya değil, veritabanından üretilen dinamik bir uç nokta: yeni yazı yayınlandığı anda sitemap'te yerini alır. Her kayıtta lastmod alanı bulunur.
• Meta açıklamaları. Her yazının özeti, description etiketine ve sosyal paylaşım (Open Graph) etiketlerine işlenir. Özetin 160 karakteri aşmaması ve markdown kalıntılarından temizlenmesi gerekir — benim şablonum bunu otomatik yapar.
• Yapısal veri (JSON-LD). Her yazı sayfasına Article şeması gömülür: başlık, yazar, yayın tarihi, görsel. Bu, arama sonuçlarında zengin görünüm şansını artırır ve maliyeti birkaç satır JSON'dur.
• İç bağlantılar. Her yazının altında ilgili yazılara gerçek <a href> bağlantıları listelenir. Hem okuyucu sitede kalır hem de tarayıcı (crawler) tüm içeriğe link üzerinden ulaşabilir — JavaScript'le doldurulan "öneriler" kutusu bu işi görmez.

Hazır platform yerine kendi altyapın: bilanço

Dürüst bir karşılaştırma yapayım. Kaybettiklerim: hazır tema ekosistemi, eklenti pazarı, "beş dakikada kurulum" konforu ve başkasının çözdüğü güvenlik sorunları. İlk haftalarda yorum sistemi, görsel yükleme ve önizleme gibi "platformlarda bedava" gelen özellikleri tek tek yazmak gerekti.

Kazandıklarım: sayfanın her baytı üzerinde kontrol (ne istenmeyen betik, ne şişkin tema CSS'i), kendi sunucumda kendi verim, istediğim her özelliği — paylaşım istatistiklerinden içerik panelindeki ufak otomasyonlara — tam istediğim gibi ekleyebilme özgürlüğü. Ve tabii en değerlisi: altyapının her katmanını (HTTP'den SEO'ya) gerçek bir projede öğrenmiş olmak.

Tavsiyem ihtiyaca göre: amacınız yalnızca yazmaksa hazır platform kullanın; amacınız web geliştirmeyi derinlemesine öğrenmekse kendi altyapınızı yazmak, alacağınız en verimli derslerden biridir.

Sonuç

Kendi blog altyapınızı yazmak, "markdown'ı HTML'e çeviren bir betik"ten çok daha fazlası: içeriğin tek kaynağını belirlemek, render'ı sunucuya almak, URL'leri ömürlük tasarlamak ve arama motorunun gördüğü görünmez katmanı (sitemap, meta, yapısal veri, iç bağlantılar) bilinçli kurmak. Bu kararların her biri küçük; toplamı ise sitenizin bulunabilirliği ile görünmezliği arasındaki fark. Sıfırdan yazmasanız bile bu katmanları bilmek, kullandığınız her hazır platformu daha iyi değerlendirmenizi sağlar.