Docusaurus Belgelerinde Dinamik Karanlık Mod Ekran Görüntüleri: Gerçekten Geçiş Yapan Çözümler

Docusaurus Belgelerinde Dinamik Karanlık Mod Ekran Görüntüleri: Gerçekten Geçiş Yapan Çözümler

Modern web uygulamaları ve dokümantasyon platformları, kullanıcı deneyimini artırmak amacıyla karanlık mod (dark mode) desteği sunmaktadır. Docusaurus gibi güçlü bir statik site oluşturucu ile hazırlanan belgelerde de karanlık mod yaygın olarak kullanılır. Ancak, bu belgelerde yer alan ekran görüntüleri genellikle statik olup, kullanıcının seçtiği temaya (açık veya karanlık) otomatik olarak uyum sağlamaz. Bu durum, özellikle karanlık mod kullanıcıları için tutarsız bir görsel deneyime yol açar ve dokümantasyonun güncelliğini sorgulatır. Bu makalede, Docusaurus projelerinizde gerçekten tema geçişine duyarlı, dinamik ekran görüntüleri oluşturmanın teknik detaylarını ve pratik uygulamalarını ele alacağız.

Problem Tanımı ve Neden Önemli

Docusaurus, belgelerinizi hızlı ve etkili bir şekilde oluşturmanızı sağlayan harika bir araçtır. Varsayılan olarak açık ve karanlık mod desteği sunar, ancak bu destek genellikle metin ve arayüz elemanlarıyla sınırlıdır. Ekran görüntüleri ise genellikle JPEG veya PNG gibi statik formatlarda belgeye gömülür ve kullanıcının tema tercihinden bağımsız olarak aynı kalır. Bu durum, kullanıcı deneyimini olumsuz etkileyen çeşitli sorunlara yol açar.

Kullanıcı Deneyimi ve Tutarlılık Sorunları

Bir kullanıcı karanlık modda bir belgeyi okurken, birdenbire parlak bir ekran görüntüsüyle karşılaşması göz yorgunluğuna neden olabilir ve genel okuma akışını bozabilir. Bu, dokümantasyonun genel estetiği ve tutarlılığı açısından da bir problem yaratır. Kullanıcılar, kullandıkları uygulamanın veya okudukları belgenin her yönüyle seçtikleri temaya uygun olmasını beklerler.

Dokümantasyonun Güncelliği ve Bakımı

Eğer bir ürün hem açık hem de karanlık modda farklı arayüzlere sahipse, dokümantasyonda bu iki modu da göstermek gerekebilir. Bu genellikle iki ayrı ekran görüntüsü kullanmak anlamına gelir ki bu da dosya boyutunu artırır ve dokümantasyonun bakımını zorlaştırır. Her güncellemede iki görüntüyü de değiştirmek zorunda kalmak, geliştiriciler için ek bir yük oluşturur.

Erişilebilirlik ve Kullanıcı Tercihleri

Karanlık mod, özellikle düşük ışıklı ortamlarda veya görme engelli kullanıcılar için erişilebilirliği artıran önemli bir özelliktir. Statik, parlak ekran görüntüleri, bu kullanıcıların tercihlerini göz ardı ederek erişilebilirlik hedeflerini zayıflatır.

Mevcut Yaklaşımlar ve Sınırlılıkları

Şu anda, Docusaurus belgelerinde karanlık mod ekran görüntülerini yönetmek için birkaç yaygın ancak sınırlı yaklaşım bulunmaktadır.

İki Ayrı Görüntü Kullanımı (Light/Dark)

En basit yaklaşım, her ekran görüntüsü için hem açık hem de karanlık mod versiyonlarını hazırlayıp, bunları MDX içeriğinde koşullu olarak göstermektir. Bu, genellikle CSS veya basit JavaScript ile tema durumunu kontrol ederek yapılır.

import { useColorMode } from '@docusaurus/theme-common';

function ThemeImage({ lightSrc, darkSrc, alt }) {
  const { colorMode } = useColorMode();
  const src = colorMode === 'dark' ? darkSrc : lightSrc;
  return ;
}

Bu yöntem işlevsel olsa da, her görüntü için iki dosya gerektirir ve MDX içeriğini biraz karmaşıklaştırır. Ayrıca, görüntülerin manuel olarak yönetilmesi bakım yükünü artırır.

Manuel Geçiş Mekanizmaları

Bazı durumlarda, kullanıcıların bir düğmeye tıklayarak ekran görüntüsünün açık veya karanlık mod versiyonunu görmelerini sağlayan manuel geçişler uygulanır. Bu, kullanıcının ek bir etkileşimde bulunmasını gerektirir ve otomatik bir çözüm değildir.

Statik Görüntülerin Dezavantajları

• Yüksek Bakım Maliyeti: Her görüntü için iki versiyon oluşturmak ve sürdürmek.
• Dosya Boyutu: İki kat daha fazla görüntü dosyası, potansiyel olarak daha büyük paket boyutları.
• Kullanıcı Deneyimi: Otomatik geçiş olmaması veya manuel etkileşim gerektirmesi.
• Tutarsızlık: Dokümantasyonun diğer öğeleri temaya uyarken, ekran görüntülerinin uymaması.

Docusaurus'un Temel Tema Mekanizması

Dinamik ekran görüntüsü çözümümüzü anlamak için Docusaurus'un tema yönetimini nasıl ele aldığını bilmek önemlidir. Docusaurus, tema geçişini yönetmek için modern web standartlarını ve React bağlamını kullanır.

data-theme Özniteliği ve CSS Değişkenleri

Docusaurus, uygulamanın kök HTML elementine (genellikle veya ) data-theme adında bir öznitelik ekler. Bu özniteliğin değeri, mevcut temayı (light veya dark) gösterir. Örneğin:

Bu öznitelik, CSS değişkenlerini (custom properties) kullanarak stil değişikliklerini tetiklemek için kullanılır. Docusaurus teması, :root[data-theme='dark'] gibi seçicilerle farklı CSS değişken değerleri tanımlar. Örneğin:

:root {
  --ifm-color-primary: #3075c9; /* Light theme primary color */
}

:root[data-theme='dark'] {
  --ifm-color-primary: #66b0ff; /* Dark theme primary color */
}

Tema Değişimini Algılama

Docusaurus, React bağlamı aracılığıyla tema durumunu bileşenlere de sunar. @docusaurus/theme-common paketinden useColorMode hook'unu kullanarak mevcut tema durumuna (light veya dark) erişebiliriz. Bu, React bileşenlerinde tema geçişine duyarlı mantık oluşturmak için temel bir araçtır.

Varsayılan Tema Ayarları

docusaurus.config.js dosyasında temanın varsayılan ayarlarını yapılandırabilirsiniz. Örneğin, varsayılan temayı karanlık olarak ayarlamak veya tema geçiş düğmesini özelleştirmek mümkündür.

// docusaurus.config.js
module.exports = {
  themeConfig: {
    colorMode: {
      defaultMode: 'dark',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },
  },
};

Dinamik Ekran Görüntüsü Çözümüne Genel Bakış

Amacımız, kullanıcının Docusaurus'ta seçtiği temaya (açık veya karanlık) otomatik olarak uyum sağlayan ekran görüntüleri oluşturmaktır. Bunu başarmak için, her bir ekran görüntüsünün açık ve karanlık mod versiyonlarını önceden hazırlayacak ve ardından bu versiyonları dinamik olarak yükleyecek bir mekanizma geliştireceğiz.

Temel Fikir: Tema Bazlı Görüntü Yükleme

Çözümün ana fikri, bir görüntünün kaynak yolunu (src özniteliğini) kullanıcının mevcut tema tercihine göre değiştirmektir. Bu, ya CSS değişkenleri aracılığıyla ya da özel bir React bileşeni kullanarak yapılabilir.

Gereksinimler ve Ön Koşullar

• Her ekran görüntüsünün hem açık hem de karanlık mod versiyonları olmalı (örn: my-screenshot-light.png ve my-screenshot-dark.png).
• Docusaurus projesinde özel bileşenler oluşturma yeteneği.
• Temel React ve CSS bilgisi.

Çözüm Mimarisi

İki ana yaklaşım üzerinde duracağız:

1. CSS Değişkenleri ile Görüntü Yönetimi: CSS değişkenlerini kullanarak görüntü yollarını tema bazlı olarak tanımlama ve background-image özelliği ile kullanma.
2. React Bileşenleri ile Akıllı Görüntü Yükleme: Docusaurus'un tema bağlamını kullanarak bir React bileşeni oluşturma ve etiketinin src özelliğini dinamik olarak ayarlama.

React bileşeni yaklaşımı, MDX içeriğiyle daha iyi entegre olduğu ve etiketinin tüm özelliklerinden faydalanabildiği için genellikle daha esnektir ve tercih edilir.

React Bileşenleri ile Akıllı Görüntü Yükleme

Bu yaklaşım, Docusaurus'un React tabanlı yapısından tam olarak faydalanır ve MDX içeriğiyle sorunsuz bir entegrasyon sunar. Özel bir React bileşeni oluşturarak, tema durumunu dinleyebilir ve buna göre doğru görüntü yolunu seçebiliriz.

Özel Bir Bileşeni Oluşturma

İlk adım, Docusaurus projenizin src/components klasöründe (veya benzer bir yerde) ThemeImage.js adında yeni bir dosya oluşturmaktır. Bu bileşen, lightSrc ve darkSrc adında iki prop alacak ve mevcut temaya göre doğru src değerini seçecektir.

useColorMode Hook'u Kullanımı

@docusaurus/theme-common paketinden useColorMode hook'unu kullanarak mevcut tema durumuna kolayca erişebiliriz.

// src/components/ThemeImage.js
import React from 'react';
import { useColorMode } from '@docusaurus/theme-common';

function ThemeImage({ lightSrc, darkSrc, alt, ...props }) {
  const { colorMode } = useColorMode();
  const src = colorMode === 'dark' ? darkSrc : lightSrc;

  return ;
}

export default ThemeImage;

Bu bileşen, ek props'ları (genişlik, yükseklik, sınıf vb.) doğrudan etiketine iletebilmek için {...props} sözdizimini kullanır.

Görüntü Yollarını Dinamik Olarak Belirleme

Görüntülerinizi Docusaurus'un statik klasöründe (genellikle static/img) düzenli bir şekilde saklamanız önerilir. Örneğin:

• static/img/screenshots/light/dashboard.png
• static/img/screenshots/dark/dashboard.png

MDX dosyanızda bu bileşeni kullanmak için:

import ThemeImage from '@site/src/components/ThemeImage';

# Dashboard Ekran Görüntüsü

Aşağıdaki ekran görüntüsü, uygulamanın ana panosunu göstermektedir. Tema değiştiğinde otomatik olarak güncellenecektir.



Bu, kullanıcı deneyimini önemli ölçüde iyileştirir.

Bu yöntem, Docusaurus'un MDX yetenekleriyle mükemmel bir uyum sağlar ve geliştiricilere tanıdık bir React bileşeni arayüzü sunar.

Entegrasyon ve Optimizasyon İpuçları

Dinamik ekran görüntülerini Docusaurus projenize entegre ederken ve performansını optimize ederken dikkat etmeniz gereken bazı noktalar bulunmaktadır.

Docusaurus Projesine Entegre Etme

1. Bileşen Oluşturma: Yukarıdaki ThemeImage.js dosyasını src/components/ dizininize yerleştirin.
2. Görüntüleri Düzenleme: Tüm ekran görüntülerinizin hem açık hem de karanlık mod versiyonlarını static/img/ altında uygun bir klasör yapısıyla saklayın (örn. static/img/light/ ve static/img/dark/).
3. MDX İçeriğinde Kullanım: Belgelerinizdeki etiketlerini bileşeniyle değiştirin ve lightSrc ile darkSrc prop'larını doğru yollarla sağlayın.

Görüntü Optimizasyonu ve Performans

Her ne kadar iki ayrı görüntü dosyası kullansak da, performansı artırmak için bazı adımlar atabiliriz:

• Sıkıştırma: Görüntüleri web için optimize edin. TinyPNG veya Squoosh gibi araçlar kullanarak dosya boyutlarını küçültün.
• Format Seçimi: PNG, şeffaflık gerektiren veya keskin çizgili görüntüler için iyidir. JPEG, fotoğraflar için daha uygundur. WebP veya AVIF gibi modern formatlar daha iyi sıkıştırma sunar, ancak tarayıcı desteğini kontrol edin.
• Lazy Loading: bileşenine loading="lazy" prop'unu ekleyerek görüntülerin yalnızca görünür alana girdiğinde yüklenmesini sağlayın. Bu, sayfa yükleme hızını önemli ölçüde artırır.
• Boyutlandırma: Görüntülerinizi doğru boyutlarda sunun. Çok büyük görüntüleri tarayıcıda küçültmek performans kaybına yol açar. Gerekirse width ve height prop'larını kullanarak tarayıcının yer ayırmasını sağlayın.

Alternatif Çözümler ve Gelecek Yaklaşımlar

Daha gelişmiş çözümler için, Docusaurus'un @theme/ThemedImage bileşenini inceleyebilirsiniz. Bu bileşen, light ve dark prop'larını alarak benzer bir işlevsellik sunar ve Docusaurus tarafından dahili olarak kullanılır. Kendi özel bileşeninizi yazmak yerine bu bileşeni doğrudan kullanmak da mümkündür:

import ThemedImage from '@theme/ThemedImage';
import useBaseUrl from '@docusaurus/useBaseUrl';

Bu yaklaşım, Docusaurus'un yerleşik yeteneklerinden faydalanır ve daha az özel kod yazmanızı sağlar. useBaseUrl hook'u, statik varlık yollarını doğru şekilde çözmek için kullanışlıdır.

Sonuç

Docusaurus belgelerinde dinamik karanlık mod ekran görüntüleri kullanmak, kullanıcı deneyimini önemli ölçüde artıran ve dokümantasyonunuzu daha profesyonel hale getiren kritik bir adımdır. Statik görüntülerden dinamik, temaya duyarlı çözümlere geçiş yaparak, kullanıcılarınızın göz yorgunluğunu azaltır, erişilebilirliği artırır ve dokümantasyonunuzun genel tutarlılığını sağlarsınız. İster kendi özel React bileşeninizi oluşturun, ister Docusaurus'un yerleşik bileşenini kullanın, bu teknikler sayesinde belgeleriniz modern web standartlarına uygun, esnek ve kullanıcı dostu olacaktır. Unutmayın, iyi bir dokümantasyon sadece bilgi vermekle kalmaz, aynı zamanda bilgiyi sunuş biçimiyle de kullanıcıyı etkiler.

SSS (Sık Sorulan Sorular)

Bu yöntem tüm Docusaurus versiyonlarında çalışır mı?

Evet, bu makalede açıklanan React bileşeni tabanlı yöntem, Docusaurus v2 ve v3 ile uyumludur. useColorMode hook'u ve @theme/ThemedImage bileşeni Docusaurus'un modern versiyonlarının bir parçasıdır.

Performans üzerinde bir etkisi var mı?

Her görüntü için iki ayrı dosya bulundurmak, toplam dosya boyutunu artırabilir. Ancak, doğru görüntü optimizasyonu (sıkıştırma, modern formatlar) ve lazy loading (loading="lazy") kullanarak bu etkiyi minimize edebilirsiniz. Tarayıcı, yalnızca kullanıcının mevcut teması için ilgili görüntüyü yükleyecektir.

Sadece ekran görüntüleri için mi kullanılabilir?

Hayır, bu yöntem sadece ekran görüntüleri için değil, logonuz, ikonlarınız veya temaya göre değişmesini istediğiniz diğer tüm görseller için de kullanılabilir. Temaya duyarlı herhangi bir görsel varlık için aynı mantık uygulanabilir.

Görüntüleri nasıl optimize etmeliyim?

Görüntüleri optimize etmek için online araçlar (TinyPNG, Squoosh) kullanabilir, modern formatlara (WebP, AVIF) dönüştürebilir ve etiketinde width, height ve loading="lazy" gibi öznitelikleri kullanarak tarayıcıya daha fazla bilgi sağlayabilirsiniz.

Tema geçişi sırasında anlık bir "flicker" oluşur mu?

Görüntülerin yüklenmesi anlık bir gecikmeye neden olabilir. Ancak, tarayıcılar genellikle önbellekleme yapar ve Docusaurus'un tema geçişi genellikle çok hızlıdır. Eğer bu bir sorun teşkil ederse, yer tutucu (placeholder) görüntüler kullanmak veya geçiş sırasında küçük bir yükleme animasyonu göstermek gibi çözümler düşünülebilir.