Astro 7'nin Rust tabanlı Sätteri markdown motoruna geçişi; display-math bloklarını düz kod haline getiriyor, başlık çapa bağlantılarını (heading anchors) kaldırıyor ve özel markdown seçeneklerini devre dışı bırakıyor. Bu durum, yükseltme yapan ve artık sitelerinde bozuk denklemler gören herkes için can sıkıcı bir sorun teşkil ediyor.

Eğer LaTeX tarzı matematiksel ifadelere, otomatik başlık bağlantılarına veya özel markdown eklentilerine güveniyorsanız, bu yükseltme içeriğinizi okunamaz hale getirebilir ve navigasyonunuzu kullanılamaz kılabilir; bu nedenle sorunu hızlıca çözmek esastır.

Yükseltme neden sorun çıkardı?

Astro artık Sätteri'yi temel Markdown işlemcisi olarak çalıştırıyor. Sätteri, eklentilerin uygulanma sırasını değiştirir: yapılandırdığınız HTML-AST (HAST) eklentilerinden önce sözdizimi vurgulama (syntax highlighting) işlemini gerçekleştirir. Bu değişiklik, üç yaygın desenin çalışmayı durdurması anlamına gelir:

  • Display math – $$ … $$ ile sınırlandırılmış bloklar, vurgulayıcı (highlighter) önce çalıştığı için sıradan kod olarak işlenir.
  • Heading anchors – Slug'ları (URL dostu kimlikler) oluşturan ve ardından bu başlıklara otomatik bağlantı veren eklentiler artık kimlikleri (ID) göremez, bu nedenle bağlantılar hiç oluşturulmaz.
  • Custom options – Sätteri işlemcisine doğrudan ilettiğiniz tüm ek ayarlar görmezden gelinir; Astro yalnızca üç önceden tanımlanmış alanı iletir.

Somut çözümler

1. Matematiği HTML-AST yerine markdown-AST (MDAST) üzerinde işleyin

Astro'nun markdown iş akışında (pipeline) iki eklenti yuvası bulunur:

  • mdastPlugins – HTML'e dönüşmeden önce ayrıştırılmış markdown ağacı üzerinde çalışır.
  • hastPlugins – Dönüşümden sonra HTML ağacı üzerinde çalışır.

Vurgulayıcı hastPlugins eklentilerinden önce çalıştığı için matematik bir kod bloğuna dönüşür. Matematik eklentinizi mdastPlugins kısmına taşıyın.

export default {
  markdown: {
    mdastPlugins: [
      // put remark-math (or your custom math handler) here
    ],
    // leave hastPlugins for things that truly need HTML nodes
  }
}

Standart kurulumlar, bir slug oluşturucu ve ardından bir autolink eklentisi yükler. Astro'da, yerleşik heading-ID eklentisi listenizden sonra çalışır ve bu durum autolink eklentisinin bağlanabileceği hiçbir şey bırakmaz. Slug eklentisini listenin başına, ardından autolink eklentisini yerleştirin.

export default {
  markdown: {
    mdastPlugins: [
      satteriSlug(),            // must be first
      satteriAutolinkHeadings() // runs after slug, sees IDs
    ]
  }
}

Böylece her başlık bir ID alır ve autolink eklentisi bunu uygun çapa (anchor) ile sarmalayabilir.

3. Ek yapılandırmayı Astro markdown nesnesinin en üst seviyesine koyun

Astro, Sätteri işlemcisine yalnızca üç belirli alanı iletir. İşlemcinin içine yerleştirdiğiniz herhangi bir şey (örneğin bir shikiConfig nesnesi) düşürülür. Bu ek ayarları markdown yapılandırmasının en üst seviyesine taşıyın.

export default {
  markdown: {
    shikiConfig: { theme: 'nord' }, // top-level, will be respected
    // other Astro-accepted fields …
    mdastPlugins: [/* … */],
    hastPlugins: [/* … */]
  }
}

Yaygın remark eklentileri için hızlı değiştirme kılavuzu

Eski remark eklentisi Yeni Astro özellik bayrağı (feature flag)
remark-gfm features.gfm
remark-frontmatter features.frontmatter
remark-math features.math
remark-directive features.directive
remark-smartypants features.smartPunctuation
remark-wiki-link features.wikilinks

Astro yapılandırmanızdaki eklenti adını, karşılık gelen features.* bayrağı ile değiştirin.

Eklentileri Sätteri'ye taşırken en iyi uygulamalar

  • Fabrika deseni (Factory pattern) – Sayfalar arasında durum sızıntısını (state leaking) önlemek için her belge için yeni bir eklenti örneği oluşturun.
  • Değiştirilemez düğümler (Immutable nodes) – Bir düğümü asla yerinde değiştirmeyin; işlemcinin değişiklikleri doğru şekilde takip edebilmesi için yeni bir düğüm nesnesi döndürün.
  • Ekleme yardımcıları (Insert helpers) – Ağacı manuel olarak parçalamak (splicing) yerine, kardeş düğümler eklemeniz gerektiğinde ctx.insertBefore veya ctx.insertAfter kullanın.

Bu kurallara uymak, işlemcinin kararlı kalmasını sağlar ve takibi zor hataları önler.

Bundan sonra neye dikkat edilmeli?

Astro'nun dokümantasyonu hala varsayılan olarak eski eklenti sırasını listeliyor, bu nedenle yeni projeler istemeden bu bozuk davranışı devralabilir. Dahili heading-ID eklentisini yeniden sıralayan olası bir yerleşik düzeltme için gelecek Astro sürümlerini takip edin. Bu süre zarfında, yukarıdaki adımlar Astro 7'ye geçtikten sonra matematik işleme, başlık çapa bağlantıları ve özel markdown seçeneklerini geri getirmenin tek güvenilir yoludur.

Özet: Astro 7'nin Sätteri motoruna geçiş; matematik yönetimini mdastPlugins kısmına taşımayı, slug eklentisini autolink'lerden önceye almayı ve tüm ek markdown ayarlarını işlemci nesnesinin dışına çıkarmayı gerektirir; bu üç düzenleme yapıldığında sitenizin denklemleri, navigasyon bağlantıları ve özel markdown özellikleri eskisi gibi çalışacaktır.