Belgelere otomatik güncellenen ekran görüntüleri eklemek

 (interblah.net)
11 puan yazan GN⁺ 2026-04-27 | 1 yorum | WhatsApp'ta paylaş
  • Çalışan bir web uygulamasından ekran görüntülerini otomatik olarak yakalayıp yardım dokümanı derlemesiyle birlikte güncelleyen bir akış kurarak, UI değişikliklerinden sonra bile doküman görsellerini güncel tutmak
  • Markdown içindeki SCREENSHOT yorumları hedef yol, yakalama yöntemi, CSS selector gibi talimatları içerir; derleme sırasında bunlar okunup gerçek görseller yerleştirilir
  • Rake task, Capybara ve Cuprite üzerinden headless Chrome çalıştırır; işleri ekip bazında gruplayarak tek bir girişten sonra birden fazla URL üzerinde dolaşıp yakalama yapar
  • Yakalama, element, full_page, viewport olmak üzere üç modu destekler; click, wait, crop, torn, hide gibi seçeneklerle açık durumdaki UI veya gereksiz öğeler de kontrol edilir
  • rails manual:build komutunu bir kez çalıştırmak, ekran görüntüsü üretimi ile yardım sayfası derlemesini birlikte yürütür; kod ile dokümanı aynı PR ya da commit içinde eşleştirmeyi kolaylaştırarak manuel yakalama ve manuel kırpma kaynaklı sürtünmeyi büyük ölçüde azaltır

Otomatik güncellenen ekran görüntüsü yaklaşımı

  • Canlıda çalışan Jelly (ekipler için paylaşımlı e-posta gelen kutusu hizmeti) yardım merkezi, çalışan web uygulamasından ekran görüntülerini otomatik olarak yakalayacak ve yeniden derlendiğinde bunları birlikte güncelleyecek şekilde yapılandırılmış
  • Dokümanlar Markdown ile yazılıyor; Self-updating screenshots yazısında anlatıldığı gibi Redcarpet ile HTML'ye işlenip ardından Rails uygulamasının ERB view'larıyla render ediliyor
  • Markdown içinde SCREENSHOT yorumları yer alıyor ve burada hedef yol, yakalama yöntemi, CSS selector gibi talimatlar birlikte tutuluyor
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • Hemen altındaki görsel etiketi, sonucun yerleştirileceği konum olarak kullanılıyor
  • UI'nin renkleri, düğme konumu veya metni az da olsa değiştiğinde mevcut doküman ekran görüntüleri kolayca eskiyor; bu akış da bu manuel güncelleme yükünü azaltıyor

Yakalama hattı ve bakım etkisi

  • İçeride Rake task, Capybara ve Cuprite üzerinden headless Chrome çalıştırarak tüm Markdown dosyalarındaki SCREENSHOT yorumlarını tarıyor
  • Ekran görüntüsü işleri ekip bazında gruplanıyor; aynı ekipte yalnızca bir kez giriş yapıldıktan sonra birden fazla URL dolaşılacak şekilde yapılandırılmış
  • Desteklenen yakalama modları üç tane
    • element: CSS selector ile belirli bir DOM öğesini yakalar
    • full_page: Tüm sayfayı yakalar; gerekirse yükseklik temelinde kırpılabilir
    • viewport: Tarayıcı penceresinde o anda görünen alanı yakalar
    Reklam
  • Ayrıntılı seçenekler olarak click, wait, crop kullanılabiliyor; böylece düğmeye tıkladıktan sonra ortaya çıkan durum ya da animasyon sonrasındaki ekran da otomatik olarak yakalanabiliyor
    • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
    • Düğmeye basıp formu açtıktan sonra 200 ms bekler ve belirli bir alanı kırparak yakalar
  • Ek seçenekler arasında torn ve hide da var
    • torn, CSS clip-path kullanarak yırtılmış kağıt kenarı efekti uygular
    • hide, dev toolbar veya cookie banner gibi ekranda görünmemesi gereken öğeleri geçici olarak gizler
  • Tüm hat, tek bir rails manual:build komutuyla çalışır; tüm ekran görüntüsü yakalamalarını ve yardım sayfası derlemesini birlikte işler
  • Doküman kaynakları, public/manual/ altında basics, setup, advanced gibi bölümlere göre düzenlenmiş
  • Derleme aşamasında bu Markdown dosyaları app/views/help/ altındaki ERB view'larına dönüştürülür; breadcrumb ve bölüm navigasyonu da birlikte oluşturulur
  • Özellik geliştirme ile yardım dokümanı güncellemesini aynı kod tabanı içinde birlikte ele alabilmek, kod ile dokümanın senkronizasyonunu aynı PR ya da aynı commit içinde korumayı kolaylaştırır
  • Kaydırma gerektiren öğeler, tıklanınca açılan popover'lar ve istenmeyen bölümlerden kaçınmak için yapılan crop gibi istisna işlemleri uygulamada daha fazla zaman gerektirse de, kurulumdan sonra yardım merkezi çok daha sık güncellenmeye başlanmış
  • UI'yi değiştirip derlemeyi yeniden çalıştırdıktan sonra sonucu commit etmekten ibaret bir akışla ekran görüntülerini her zaman güncel tutmak mümkün; böylece manuel yakalama ve manuel kırpma kaynaklı sürtünme neredeyse tamamen ortadan kalkıyor

İlgili okumalar

1 yorum

 
GN⁺ 2026-04-27
Hacker News yorumları
  • Ben de benzer şekilde bir .#screenshots derivation ekledim; ilk kurulum maliyeti yüksek olsa da sonrasında neredeyse hiç bakım gerektirmiyor.
    Ekran görüntülerini programatik olarak üretirken uygulamanın light/dark theme için iki sürümünü de birlikte oluşturup, prefers-color-scheme: dark ile uygun olanı değiştirmek yeterli oluyor.
    Bu tür şeyler GitHub README'lerinde de gayet iyi çalışıyor: https://github.com/CyberShadow/CyDo#readme
    • Bu yaklaşıma çok katılıyorum.
      Mobil uygulamalarda Nix ile tek seferlik bir Android emülatörü ayağa kaldırıp güncel ekran görüntülerini ürettim; önceden yapılandırma gerekmiyor ve çalıştırma sonrası veri de kalmıyor.
      Benim durumumda kurulumun kendisi o kadar da zor değildi; asıl zor olan fikri bulmaktı ve Nix kodunu da sevdiğim bir LLM ile tek seferde oluşturdum.
      Ekran görüntülerini manuel güncellemek dünyanın en zor işi değil ama upload-apk + take-screenshot + transfer-back-to-PC + edit akışı hep hafif sinir bozucu olduğundan sonunda neredeyse hiç yapmamaya başlıyorum.
  • Mobilde kod örnekleri için yatay kaydırma kesinlikle gerekli.
    Bağlamdan aşağı yukarı ne olduğu anlaşılabiliyordu ama yine de rahatsız ediciydi.
  • Bu, mobil projeler için gerçekten çok kullanışlı.
    Uygulama mağazalarında ekran görüntüleri zorunlu ve ekran boyutu ile yerelleştirme sayısı kadar görsel üretmek gerektiği için iş hızla zahmetli hale geliyor.
    Eskiden bunun için kendi script'lerimi yazıyordum; şimdi ise https://fastlane.tools/ gibi Fastlane araçları çok yardımcı oluyor.
    Mantık bulmaca oyunum Nonoverse için de Fastlane kullanıyorum; örnek ekran görüntülerini uygulama mağazası sayfasında görebilirsiniz: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
    App Preview videolarının kaydını da birden fazla sahneyi içerecek şekilde otomatikleştirdim; merak eden olursa bunun hakkında ayrıca yazılabilecek bir konu bence.
    • İlgi çekici görünüyor ama bunun ücretli bir servis mi yoksa yerelde çalışan bir OS uygulaması mı olduğu konusunda pek emin olamadım.
  • Oldukça hoş.
    vibe coding ile yaptığım küçük casual oyunlar her zaman uygulamanın CLI üzerinden headless çalışabildiği, offscreen texture rendering, ekran görüntüsü komutu ve performans ölçümü yapabildiği bir halde başlıyor.
    Bunu eklemek neredeyse hiç zaman almıyor ve ajanın UI'ı otomatikleştirip önemli noktalara bakabilmesi için de bir kanal açıyor.
    Bu sayede ajanın ekran görüntülerini güncellemesini sağlamak da çok kolaylaşıyor.
    Build sürecine tamamen gömülü hali kadar temiz değil ama artık o kısmı da eklemeyi düşünüyorum.
    • Ben de aynısını yapıyorum.
      offscreen screenshot path ile world pos/camera view vector için CLI argümanlarım da var ve metin tabanlı bir giriş formatıyla script benchmark'ları çalıştırıyorum.
      Bu format; isimlendirilmiş segmentlerden oluşan birden çok satır, segment başına n oyun tick süresi ve her segmentin kontrol girdilerinden oluşuyor.
      Oyun kodu üzerinde çalışırken görselleri ve performansı A/B test etmek için bunu çok sık kullanıyorum.
    • Bu casual oyunların bağlantılarını paylaşabilir misin diye merak ediyorum.
      Ben de vibe coding'in oyun geliştirmeyi ne kadar kolaylaştırdığıyla çok ilgileniyorum.
      Adobe Flash döneminde bağımsız oyun ekosistemi gerçekten çok canlıydı; o zamandan beri neredeyse hiçbir şey bu kadar kolay geliştirme imkânı sunmadı.
      vibe coding, bu seviyeyi ilk kez aşan araç gibi görünüyor.
    • Bunu eklemek neredeyse hiç zaman almıyor sözü duruma göre değişir.
      Hangi engine'i kullandığını merak ettim.
  • Gerçekten çok hoş.
    Markdown belgelerinin içine ekran görüntüsü bildirimlerini satır içinde koyabilme fikri özellikle çok hoşuma gitti.
    Masaüstü uygulamam için farklı dillerde ve light/dark modlarda ekran görüntüleri üreten, gürültüyü temizleyen ve Windows/macOS pencere çerçeveleri ekleyen bir çözüm hazırlamıştım.
    Burada anlattım: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
    Şu anda ayrı bir script olduğu için bakımı epey can sıkıcı; bunu markdown/mdx'in bir parçası haline getirmeyi düşünmeliyim.
    Güzel bir ilham oldu.
  • Buna gerçekten çok sık ihtiyaç duydum.
    kimsenin fark etmediği X en iyi çalışması tarzı bir meme olarak bile kullanılabilir.
  • Bu güzel.
    Benim https://github.com/zombocom/rundoc projemde de benzer bir özellik var.
    Ana amaç tutorial oluşturma olduğu için, çalıştırılan komutların çıktısını da tekrar belgenin içine yerleştiriyor.
  • Burada gerçek zamanlı render yaklaşımı da mümkün olabilir diye düşünüyorum.
    Aracın canlı önizlemesini bir dikdörtgenin içine yerleştirmek gibi.
    Araç hafifse görsel olarak da en iyi seçenek olabilir ve tarayıcının erişilebilirlik ayarları ya da kullanıcı eklentileri gibi render ayarları da aynen yansıtılabilir.
  • e2e testleri çalıştırırken ekran görüntüsü üretimini de işin içine katmayı düşünmüştüm.
    Belgeler için docs/ klasörünü de aynı depoda tutup, belgeleri güncellerken yeni ekran görüntüsü gerektiğinde yeni bir test eklemek oldukça uyumlu bir yaklaşım gibi duruyor.
  • Güzel.
    Ben de birkaç yıl önce tam olarak bunu yapmaya başlamıştım ama sonunda https://picshift.io/ gibi daha genel amaçlı bir çözüme soyutladım.
    Yine de ekran görüntüsü kullanım senaryosu hâlâ çok hoşuma gidiyor ve bu projenin ilk adı da ScreenSync idi.
    • Güzel, iyi yapılmış ve bu tür farklı yaklaşımların bir arada bulunması sevindirici.