Astro ve KaTeX entegrasyonu ile web sayfasında görüntülenen matematik formülü

Astro ve KaTeX Entegrasyonu: Web Sayfalarınızda Kusursuz Matematik Gösterimi

Yayınlanma Tarihi: 10 Nisan 2025Yazar: Abdullah Gülderen
Etiketler:astrokatexlatexmatematik gösterimiweb tipografisimarkdownmdxweb geliştirme

Günümüzde, web projelerinde matematiksel ifadeleri hızlı ve temiz bir biçimde göstermek isteyenler için KaTeX mükemmel bir çözüm sunuyor. Bu yazıda, astro ile oluşturduğunuz web sayfalarına KaTeX desteğini nasıl ekleyeceğinizi detaylı olarak anlatacağım.

📚 Bölüm 1: Giriş

LaTeX tabanlı matematiksel yazım dilinin tarayıcıda hızlıca görselleştirilebilmesi için tasarlanmış olan KaTeX, özellikle akademik ve bilimsel içerik üreten web siteleri için ideal. Astro ise modern, hafif ve esnek yapısıyla statik siteler oluşturmak isteyen geliştiricilerin tercih ettiği bir framework. Bu iki güçlü teknolojiyi birleştirerek, matematiksel formülleri hatasız ve hızlı bir şekilde sunabilirsiniz.

🚀 Bölüm 2: Gereksinimler ve Hazırlık

Ön Koşullar

  • Astro Projesi: Zaten bir astro projesi başlatmış olmanız gerekiyor. Henüz başlamadıysanız, Astro’nun resmi dokümantasyonundan nasıl başlanacağını öğrenebilirsiniz.

  • Node.js ve NPM: Projenizi yönetmek için Node.js ve npm’in sisteminizde kurulu olması gerekmektedir.

  • Temel HTML/CSS Bilgisi: KaTeX entegrasyonu için HTML ve CSS bilgisi yararlı olacaktır.

Proje Yapısının Hazırlanması

Yeni bir astro projesi oluşturmak için terminalinizde şu komutu çalıştırın:

npm init astro@latest

Komut dosyasını çalıştırdıktan sonra gerekli yapılandırmaları tamamlayın. Projenin temel dizin yapısı aşağıdaki gibi olacaktır:

my-astro-project/
├── public/
├── src/
│   ├── components/
│   ├── layouts/
│   └── pages/
└── package.json

🔧 Bölüm 3: KaTeX’in Projeye Eklenmesi

KaTeX’i projeye eklemenin iki temel yolu bulunmaktadır: CDN üzerinden doğrudan ekleme veya npm ile yerel kurulum. İhtiyacınıza göre aşağıdaki yöntemlerden birini tercih edebilirsiniz.

Yöntem 1: CDN Üzerinden Ekleme

Astro’nun şablon dosyalarına veya layout dosyanıza, <head> etiketleri içinde KaTeX’in CSS ve JS dosyalarını ekleyin:

<!-- src/layouts/BaseLayout.astro (KaTeX Entegrasyonu Örneği) -->
```astro
---
// Bu layout, Astro projesine KaTeX eklemeyi gösterir.
// Herhangi bir prop almasına gerek yoktur, sadece temel yapıyı sağlar.
---
<!doctype html>
<html lang="tr">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Astro & KaTeX Örneği</title> {/* Basit bir başlık */}
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" /> {/* Favicon (isteğe bağlı) */}
    <meta name="generator" content={Astro.generator} /> {/* Astro generator (isteğe bağlı) */}

    {/* === KaTeX (Matematik Formülleri) Stil ve Script Dosyaları === */}
    {/* KaTeX için gerekli CSS dosyası */}
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU07DNEtyLUK7MAf6HnD=/" crossorigin="anonymous" /> {/* Güvenlik için integrity ekledim */}

    {/* KaTeX'in ana Javascript dosyası */}
    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjN+cwE0F/2Z+LhhBG+p9N/OQdLxyLM/5U6b6ZfU8+2/U5f+7/M=" crossorigin="anonymous"></script> {/* Güvenlik için integrity ekledim */}

    {/* KaTeX'in sayfadaki formülleri otomatik bulup işlemesi için eklenti */}
    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3rUQwPVx6b8M/d5Bf+gFIkLBCvTg=/" crossorigin="anonymous"></script> {/* Güvenlik için integrity ekledim */}

    {/* Auto-render eklentisini çalıştıracak ve ayarları yapacak script */}
    <script>
      document.addEventListener("DOMContentLoaded", function () {
        renderMathInElement(document.body, {
          // Matematiksel ifadeleri hangi karakterlerin arasına yazacağınızı belirtir
          delimiters: [
            { left: "$$", right: "$$", display: true }, // $$...$$ arasındaki ifadeler blok olarak (ayrı satırda, ortalı) gösterilir. Örn: $$ E = mc^2 $$
            { left: "$", right: "$", display: false }   // $...$ arasındaki ifadeler satır içinde gösterilir. Örn: Pisagor teoremi $a^2 + b^2 = c^2$ şeklindedir.
            // İsterseniz farklı sınırlayıcılar da ekleyebilirsiniz, örneğin:
            // { left: "\\(", right: "\\)", display: false }, // \(...\) satır içi
            // { left: "\\[", right: "\\]", display: true }  // \[...\] blok
          ]
        });
      });
    </script>
    {/* =============================================== */}

    {/* Diğer head etiketleri buraya gelebilir (CSS, fontlar vb.) */}

  </head>
  <body>
    {/* Header, Navigation gibi bileşenler buraya eklenebilir */}

    <main>
      {/* Astro sayfalarınızın asıl içeriği buraya yerleşir */}
      <slot />
    </main>

    {/* Footer gibi bileşenler buraya eklenebilir */}

    {/* Diğer scriptler buraya gelebilir */}
  </body>
</html>

Bu yöntem, hızlıca denemeler yapmak isteyenler için idealdir. Aynı zamanda dışarıdan yüklenen dosyaların güncel sürümünü kullanmanızı sağlar.

Yöntem 2: NPM ile Yerel Kurulum

Projeye KaTeX paketini dahil etmek için npm komutunu kullanın:

npm install katex

Kurulum tamamlandıktan sonra, astro projesinde KaTeX’i kullanmak için örneğin bir bileşen oluşturabilirsiniz:

---
// src/components/MathRenderer.astro
import { readFile } from 'fs/promises';
const katexCSS = await readFile(new URL('katex/dist/katex.min.css', import.meta.url), 'utf-8');
---

<style global>
  {katexCSS}
</style>

<div innerHTML={Astro.props.mathHTML}></div>

Ardından, sayfanızda bu bileşeni kullanarak matematiksel ifadeleri render edebilirsiniz:

---
// src/pages/index.astro
import MathRenderer from '../components/MathRenderer.astro';
import katex from 'katex';

const mathHTML = katex.renderToString("\\frac{a}{b} = \\sqrt{c}", {
  throwOnError: false,
  displayMode: true,
});
---

<html lang="tr">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Astro ile KaTeX Entegrasyonu</title>
  </head>
  <body>
    <h1>Merhaba, Astro ve KaTeX Dünyası!</h1>
    <p>Aşağıdaki matematiksel ifadeyi KaTeX ile render ettik:</p>
    <MathRenderer mathHTML={mathHTML} />
  </body>
</html>

🛠️ Bölüm 4: Uygulama İpuçları ve Karşılaşılabilecek Sorunlar

1. Kodun Test Edilmesi

  • Geliştirme Sunucusunu Çalıştırın: Projenizin kök dizininde aşağıdaki komut ile astro geliştirme sunucusunu başlatın.
npm run dev
  • Tarayıcıda Kontrol: Yerel sunucuda açılan sayfanızda matematiksel ifadelerin doğru şekilde render edildiğini kontrol edin.

2. Hata Ayıklama

  • CSS Dosyasının Yüklenmemesi: KaTeX CSS dosyasının doğru şekilde yüklendiğinden emin olun. Eğer stil eksikse, CDN linki veya yerel dosya yolunu tekrar kontrol edin.

  • JavaScript Hataları: Tarayıcı konsolunda hata mesajları varsa, auto-render script’inin doğru yüklendiğini ve DOMContentLoaded olayının tetiklendiğini kontrol edin.

  • Render Sorunları: KaTeX’in render işleminde hata alıyorsanız, LaTeX sözdiziminizin doğru olduğundan emin olun. Özellikle matematiksel formüllerinizi ......, ...... veya (…) gibi doğru delimiters kullanarak yazın.

🎯 Bölüm 5: Sonuç ve Ekstra Kaynaklar

KaTeX ile astro projelerinize matematiksel ifadeler eklemek, hem kullanıcı deneyimini artırır hem de içeriklerinizin profesyonel görünmesini sağlar. Bu yazıda, hem CDN hem de npm ile KaTeX entegrasyon yöntemlerini ele aldık. Kendi projenize uygun yöntemi seçip, adım adım uygulayarak sorunsuz bir matematiksel içerik sunumu sağlayabilirsiniz.

Ekstra Kaynaklar:

Eğer sorularınız olursa, yorum kısmında paylaşabilir ya da sosyal medyada etiketleyebilirsiniz. İyi kodlamalar!

← Tüm Yazılara Geri Dön