Medium’da yazmak güzel; keşif, kitle ve yorum sistemiyle hâlâ en cazip yazı platformlarından biri. Ama ya bu yazıları aynı zamanda kendi kişisel sitenizde de listelemek isterseniz? Elle kopyala-yapıştır, her yeni yazıda sayfayı güncelle, içerikleri senkronize tutmaya çalış… sürdürülemez bir çaba.

İşte tam bu noktada @ykocaman/astro-medium-loader devreye giriyor. Bu yazıda eklentinin ne yaptığını, hangi ihtiyaca cevap verdiğini, nasıl kurulup kullanılacağını ve bu sitenin altyapısında nasıl çalıştığını anlatacağım.

Kaynak: astro.build

Astro Content Layer + Medium RSS

Astro, astro@5.0 ile birlikte Content Layer API’sini duyurdu. Bu API, içerik koleksiyonlarını yalnızca yerel dosyalardan değil, uzak kaynaklardan da beslemeye olanak tanıyor. İşte @ykocaman/astro-medium-loader, bu API’yi kullanarak Medium RSS feed’ini bir Astro içerik koleksiyonuna dönüştürüyor.

Başka bir deyişle: Medium profilinize ait RSS beslemesini okuyor, ayrıştırıyor ve Astro’nun getCollection('medium') API’siyle sorgulanabilir hale getiriyor. Sonuç? Medium yazılarınız, tıpkı yerel MDX dosyalarınız gibi sitenizde listeleniyor, sayfalandırılıyor ve render ediliyor.

Nasıl Çalışıyor?

Eklentinin kalbinde iki temel bileşen var:

Akış şöyle:

flowchart LR
    Medium[Medium RSS Feed] -->|rss-parser| Loader[mediumLoader]
    Loader -->|Zod schema| Collection[Astro Content Collection]
    Collection -->|getCollection| Site[Statik Site Sayfaları]
    Collection -->|render| Post[Blog Yazı Görünümü]

Her Medium yazısı için şu veriler elde ediliyor: başlık, orijinal bağlantı, yayın tarihi, açıklama, tam HTML içeriği, kategoriler ve varsa hero görseli. Ayrıca her yazının sonuna otomatik olarak canonical bağlantı ekleniyor — SEO için kritik bir detay.

Kurulum

Proje dizininde aşağıdaki komut çalıştırılır:

pnpm add @ykocaman/astro-medium-loader
# veya
npm install @ykocaman/astro-medium-loader

Astro sürümünün ^5.0.0 olması yeterli; eklenti peerDependency olarak bunu zorunlu tutuyor.

Kullanım

Kullanım, content.config.ts dosyasına bir koleksiyon tanımı eklemekten ibaret. Üç farklı depolama stratejisiyle çalıştırılabiliyor:

1. Canlı Çekme (Her Derlemede)

Her derleme veya istekte Medium RSS beslemesi yeniden çekilir. Küçük ölçekli, sık güncellenen profiller için uygun:

// content.config.ts
import { defineCollection } from 'astro:content';
import { mediumLoader } from '@ykocaman/astro-medium-loader';

const medium = defineCollection({
  loader: mediumLoader({ username: 'ykocaman' })
});

export const collections = { medium };

2. Önbellekli Kullanım (Geliştirme İçin Önerilen)

Besleme .astro/storage/medium altında önbelleğe alınır. Geliştirme sırasında tekrar tekrar istek atılmaz, ancak .astro dizini git-ignore’lu olduğu için her deploy’da güncel veri çekilir:

const medium = defineCollection({
  loader: mediumLoader({
    username: 'ykocaman',
    storage: { enabled: true, path: '.astro/storage/medium' }
  })
});

3. Kalıcı Depolama (CI ve Çevrimdışı Derleme)

Veri src/content/medium/ gibi kalıcı bir dizine yazılır. İlk derlemeden sonra Medium’a istek atılmaz. CI ortamlarında veya çevrimdışı derlemeler için ideal:

const medium = defineCollection({
  loader: mediumLoader({
    username: 'ykocaman',
    storage: { enabled: true, path: 'src/content/medium' }
  })
});

Koleksiyonu Render Etmek

Tanımlandıktan sonra, herhangi bir Astro sayfasında getCollection ve render ile kullanılabiliyor:

---
import { type CollectionEntry, getCollection, render } from 'astro:content';
import BlogPost from '../../layouts/BlogPost.astro';

export async function getStaticPaths() {
  const posts = await getCollection('medium');
  return posts.map((post) => ({
    params: { slug: post.id },
    props: post,
  }));
}

type Props = CollectionEntry<'medium'>;
const post = Astro.props;
const { Content } = await render(post);
---

<BlogPost {...post.data}>
  <Content />
</BlogPost>

Bu Sitede Nasıl Kullanılıyor?

ykocaman.dev üzerinde @ykocaman/astro-medium-loader, yerel blog yazılarıyla Medium yazılarını tek bir çatı altında birleştiriyor. İşleyiş şöyle:

src/content.config.ts — iki ayrı koleksiyon tanımlı:

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: ({ image }) => z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    heroImage: image().optional(),
  }),
});

const medium = defineCollection({
  loader: mediumLoader({
    username: MY_USERNAME,
    storage: { enabled: true }
  }),
});

export const collections = { blog, medium };

src/pages/blog/[...slug].astro — dinamik rota, her iki koleksiyonu da tarıyor. Medium yazıları öncelikli; aynı slug’a sahip yerel yazılar local- ön ekiyle çakışmadan listeleniyor.

src/utils/blog.ts — getAllPosts() fonksiyonu iki koleksiyonu birleştirip tarihe göre sıralıyor. source: 'local' | 'medium' alanıyla yazının kaynağını ayırt etmek mümkün.

Böylece ana sayfadaki blog listesi, hem yerel hem Medium yazılarını aynı kart tasarımıyla gösteriyor.

Öne Çıkan Özellikler

Hangi İhtiyaçlara Cevap Veriyor?

Bu eklenti özellikle şu senaryolarda faydalı:

• Kişisel blog + Medium yazarı: Yazılarınız Medium’da yayınlanıyor, ama kendi sitenizde de arşivlemek ve listelemek istiyorsunuz.
• Portföy siteleri: Teknik yazılarınızı Medium’da yazıyorsunuz; portföy sitenizde “Yazılar” bölümü olarak göstermek istiyorsunuz.
• İçerik toplulaştırma: Birden fazla yazarın Medium içeriklerini tek bir sitede derlemek.
• SEO stratejisi: Kendi alan adınızda canonical bağlantılı içerik sunarak arama motorlarına doğru sinyali vermek.
• CI/CD dostu: Kalıcı depolama moduyla, derleme sırasında harici istek bağımlılığını ortadan kaldırmak.

Teknik Detaylar

Eklenti, rss-parser kütüphanesini kullanarak https://medium.com/feed/@kullaniciadi adresinden gelen XML’i ayrıştırıyor. Her bir RSS öğesinden şu veriler çıkarılıyor:

• slug: Başlığın URL-dostu hale getirilmiş hali
• heroImage: İçerikteki ilk <img> etiketinden
• description: İlk 32 kelimeden oluşan özet
• content: Medium’un content:encoded alanındaki HTML (içindeki “was originally published in” bloğu canonical bağlantı eklendiği için temizleniyor)
• canonical: Orijinal Medium bağlantısına yönlendiren HTML

Zod şeması sayesinde tüm veriler doğrulanıyor; eksik alanlar için tip güvenli varsayılan değerler atanıyor.

Toparlayalım

@ykocaman/astro-medium-loader, Medium’da yazmaya devam ederken kendi Astro sitenizde de bu içerikleri zahmetsizce listelemek için tasarlanmış, hafif ve açık kaynaklı bir çözüm. 5 dakikada kurulup yapılandırılabiliyor; depolama stratejileri sayesinde hem geliştirme hem üretim ortamına uyum sağlıyor.

Medium’daki yazılarınızın kişisel sitenizde de yaşamasını istiyorsanız, bu eklenti tam size göre.

Links

• 📦 NPM Package
• 🔗 GitHub Repository
• 📖 Documentation