AFFiNE'i CMS gibi kullanmak: kendi bloglarını nasıl kurdular?

Bu yazı, AFFiNE ekibinin kendi ürününü üretim sürecinde nasıl kullandığını anlatıyor.

Önceki sistem

Teknik yazıda eski blog şu şekilde tarif ediliyor:

• Next.js,
• GitHub deposunda statik Markdown dosyaları,
• dosya yolu ve adından route üretme,
• frontmatter içinde metadata,
• build sırasında statik sayfaya dönüştürme.

Bu düzen teknik ekip için anlaşılır.

Fakat içerik yazan herkesin:

• Markdown,
• Git,
• GitHub

bilmesi gerekir.

Ekip AFFiNE'i burada bir **authoring interface** olarak kullanmak istedi.

Yani site motorunu AFFiNE'e çevirmekten çok, yazı yazma yüzeyini AFFiNE'e taşıdılar.

İlk mimari

Yazının ilk sürümünde public workspace içeriği AFFiNE API üzerinden okunuyordu.

AFFiNE Reader kabaca şu işi yapıyordu:

1. çalışma alanındaki sayfa listesini oku,
2. her sayfadaki blokları al,
3. blok içeriğini Markdown'a dönüştür,
4. tek sayfalık Markdown çıktısı oluştur.

Sonra web uygulaması bu çıktıyı HTML'e dönüştürüyordu.

Bu zincir önemli:

**AFFiNE → blok verisi → Markdown → site**

Markdown burada yazarın doğrudan düzenlediği kanonik dosya rolünü üstlenmiyor; yayın akışındaki **ara temsil** olarak kullanılıyor.

Metadata problemi

Blog, gövde metninden daha fazla veri gerektirir.

Şunlar gerekir:

• başlık,
• yazar,
• etiket,
• slug,
• yayın durumu,
• tarih,
• kapak.

Ekip eski Markdown frontmatter'ını AFFiNE içeriğinde de kullanmaya devam etti. Böylece yazı yüzeyi değişse bile yayın sisteminin metadata sözleşmesi korunabildi.

Bu iyi bir içerik mimarisi dersi:

**Editör değişebilir. Yayın sözleşmesini editöre gömmemek gerekir.**

Eski yazıları nasıl taşıdılar?

Yaklaşık 50 eski Markdown yazısını elle kopyalamak yerine otomasyon kullandılar.

Yazıdaki tarihsel akış:

1. dağınık klasörlerdeki `index.md` dosyalarını tek dizinde toplamak,
2. klasör slug'larını dosya adına dönüştürmek,
3. frontmatter alanlarını yeni sisteme uyarlamak,
4. AFFiNE'e yükleme sürecini otomatikleştirmek.

O dönemde uygun resmî API olmadığı için Playwright ile tarayıcı etkileşimini otomatikleştiren bir importer kullanılmış.

Bugün bu otomasyonu aynen kopyalamak doğru olmaz.

Asıl ders:

**Migration, içerik taşımak kadar metadata ve kimlik taşımaktır.**

Slug bozulursa SEO değişir. Publish state bozulursa taslak yayımlanır. Görsel ilişkisi bozulursa makale eksilir.

İlk yaklaşım neden değişti?

Yazının 22 Ocak 2024 güncellemesi doğrudan üretim deneyiminden gelen iki problem anlatıyor.

İlk kurulumda blog sayfaları AFFiNE'den dinamik/ISR benzeri biçimde okunuyordu. Ekip bunun zaman zaman güvenilmez olduğunu ve API sunucusuna beklenmedik trafik üretebildiğini söylüyor.

Sonra iki aşamalı modele geçiyorlar:

1. GitHub Action, AFFiNE çalışma alanından içerikleri çekip Markdown dosyaları üretir ve repoya yazar.
2. Repo değişince Vercel build'i statik siteyi yeniden üretir.

Zincir artık:

**AFFiNE → GitHub Action → cache Markdown → Git repo → Vercel build**

Bu daha sıkıcı görünebilir.

Ama üretimde sıkıcı çoğu zaman iyidir.

Ara dosya sayesinde:

• kaynağın anlık erişilebilirliğine bağımlılık azalır,
• build girdisi gözle görülebilir,
• değişiklik Git geçmişine girer,
• yayın ile editör arasına tampon eklenir.

Public workspace neden kritik bir uyarı?

Aynı güncelleme, public workspace seçeneğinin daha sonra ürün arayüzünden kaldırıldığını söylüyor.

Belgeyi API üzerinden okumak için oturum token'ı kullanılması gerekiyordu ve bu token'ın süresi dolabiliyordu.

Bu, eski teknik yazıları neden körlemesine kurulum rehberi olarak kullanamayacağımızın iyi örneği.

Bir entegrasyon üç şeye bağlı olabilir:

• ürün özelliği,
• auth modeli,
• API davranışı.

Üçünden biri değişince "çalışan örnek" tarihsel belgeye dönüşür.

Bugün bu vakadan ne almalıyız?

Koddan çok mimari ayrımı al.

1. Yazma yüzeyi

Yazarın rahat ettiği yer.

AFFiNE olabilir. Obsidian olabilir. Google Docs olabilir.

2. İçerik sözleşmesi

Başlık, slug, durum, tarih, kaynaklar, ilişkiler.

Bu sözleşme editörden mümkün olduğunca bağımsız olmalı.

3. Dönüşüm

Editör verisini yayın biçimine çeviren adım.

4. Kanonik build girdisi

Markdown/JSON gibi diff alınabilir bir ara çıktı faydalı olabilir.

5. Yayın

Statik site veya uygulama build'i.

Bu ayrım sayesinde içerik editörü değiştiğinde bütün yayın sistemi değişmek zorunda kalmaz.

Nitorel açısından ders

Nitorel'in bugünkü içerik sistemi Git deposundaki Markdown dosyalarını kullanıyor.

Bu vaka "Nitorel'i AFFiNE'e taşıyalım" demiyor.

Tam tersine şu kuralı güçlendiriyor:

**Yazma deneyimi ile production kanonik kaynağı ayrı tutulabilir.**

Bir gün AFFiNE, başka bir editör ya da bir AI ajanı taslak üretme yüzeyi olursa bile production'a giden içerik:

• şeması doğrulanmış,
• kaynakları açık,
• diff alınabilir,
• build edilebilir

bir ara çıktıdan geçebilir.

Bu, araç bağımlılığını azaltır.

Ne zaman AFFiNE'i CMS gibi düşünmek mantıklı?

Şu durumda:

• içerik ekibi AFFiNE'de zaten çalışıyor,
• teknik ekip dönüşüm pipeline'ını sahiplenebiliyor,
• özel metadata ve build akışı kurmaya değer hacim var,
• içerik ile görsel düşünme aynı workspace'te tutuluyor.

Şu durumda gereksiz:

• on yazılık kişisel blog,
• düz Markdown zaten rahat,
• bakım yapacak teknik kapasite yok,
• "bir editör daha az olsun" hedefleniyor.

AFFiNE'in kendi blog deneyi, **üretim sisteminde nerede sınır çizilmesi gerektiğini** gösteriyor.

Editör kullanıcıya rahat bir yazma yüzeyi sunabilir; build ise doğrulanabilir ve kararlı bir girdiye ihtiyaç duyar. İki ihtiyacı ayrı tasarlamak sistemi daha dayanıklı yapar.