Menyisipkan tangkapan layar yang diperbarui otomatis ke dalam dokumen

• Membuat alur yang secara otomatis menangkap tangkapan layar dari aplikasi web yang sedang berjalan dan memperbaruinya bersamaan dengan build dokumentasi bantuan, sehingga gambar dokumentasi tetap dalam kondisi terbaru bahkan setelah UI berubah
• Komentar SCREENSHOT di dalam Markdown berisi instruksi seperti path target, metode pengambilan, dan CSS selector, lalu dibaca saat proses build untuk diisi dengan gambar yang sebenarnya
• Rake task menjalankan Chrome headless melalui Capybara dan Cuprite, mengelompokkan pekerjaan per tim agar bisa login sekali lalu berkeliling ke banyak URL untuk mengambil gambar
• Pengambilan gambar mendukung tiga mode: element, full_page, dan viewport, serta mengendalikan UI yang terbuka atau elemen yang tidak perlu dengan opsi seperti click, wait, crop, torn, dan hide
• Dengan sekali rails manual:build, pembuatan tangkapan layar dan build halaman bantuan berjalan bersama, sehingga lebih mudah menyelaraskan kode dan dokumentasi dalam PR atau commit yang sama dan sangat mengurangi gesekan dari pengambilan serta crop manual

---

Pendekatan tangkapan layar yang diperbarui otomatis

• Pusat bantuan untuk Jelly (layanan inbox email bersama untuk tim) yang sedang beroperasi dikonfigurasi untuk secara otomatis menangkap tangkapan layar dari aplikasi web yang sedang berjalan dan memperbaruinya lagi setiap kali build dijalankan
• Dokumen ditulis dalam Markdown, lalu diproses menjadi HTML dengan Redcarpet berdasarkan artikel Self-updating screenshots, kemudian dirender sebagai ERB view di aplikasi Rails
• Di dalam Markdown terdapat komentar SCREENSHOT, yang memuat instruksi seperti path target, metode pengambilan, dan CSS selector
  • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
  • Tag gambar tepat di bawahnya digunakan sebagai lokasi untuk menempatkan hasil
• Bahkan perubahan kecil pada warna UI, posisi tombol, atau teks dapat dengan mudah membuat tangkapan layar dokumentasi lama menjadi usang, dan alur ini mengurangi beban pembaruan manual tersebut

Pipeline pengambilan dan manfaat pemeliharaan

• Secara internal, Rake task menjalankan Chrome headless melalui Capybara dan Cuprite untuk memindai komentar SCREENSHOT di semua file Markdown
• Pekerjaan tangkapan layar diproses dengan pengelompokan berdasarkan tim, sehingga dalam tim yang sama cukup login sekali lalu mengunjungi banyak URL
• Ada tiga mode pengambilan yang didukung
  • element: menangkap elemen DOM tertentu dengan CSS selector
  • full_page: menangkap seluruh halaman, dan bila perlu dapat dipotong berdasarkan tinggi
  • viewport: hanya menangkap area yang saat ini terlihat di jendela browser
• Opsi detail seperti click, wait, dan crop memungkinkan penangkapan otomatis terhadap keadaan setelah tombol diklik atau layar setelah animasi selesai
  • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
  • Setelah menekan tombol untuk membuka formulir, sistem menunggu 200 ms lalu mengambil tangkapan layar dengan memotong ke area tertentu
• Ada juga opsi tambahan torn dan hide
  • torn menerapkan efek tepi kertas sobek menggunakan CSS clip-path
  • hide menyembunyikan sementara elemen yang tidak seharusnya muncul di layar, seperti dev toolbar atau cookie banner
• Seluruh pipeline dijalankan hanya dengan satu perintah, rails manual:build, yang memproses semua pengambilan tangkapan layar dan build halaman bantuan sekaligus
• Sumber dokumentasi disusun di bawah public/manual/ menurut seksi seperti basics, setup, dan advanced
• Pada tahap build, file-file Markdown ini diubah menjadi ERB view di bawah app/views/help/, sekaligus membuat breadcrumb dan navigasi seksi
• Karena pengembangan fitur dan pembaruan bantuan dapat ditangani bersama dalam codebase yang sama, sinkronisasi antara kode dan dokumentasi menjadi lebih mudah dijaga dalam PR atau commit yang sama
• Penanganan pengecualian seperti elemen yang perlu di-scroll, popover yang harus dibuka lewat klik, dan crop untuk menghindari bagian yang tidak perlu memang memerlukan lebih banyak waktu implementasi, tetapi setelah dibangun, pusat bantuan bisa diperbarui jauh lebih sering
• Cukup dengan alur mengubah UI, menjalankan build lagi, lalu melakukan commit atas hasilnya, tangkapan layar selalu bisa dijaga tetap terbaru, sehingga gesekan dari pengambilan dan crop manual hampir hilang

[GN⁺]

Komentar Hacker News

• Saya juga menambahkan .#screenshots derivation yang mirip, dan meski biaya setup awalnya besar, setelah itu hampir tidak perlu maintenance
  Sekalian menghasilkan screenshot secara terprogram, buat saja dua versi aplikasi untuk light/dark theme, lalu tukar sesuai prefers-color-scheme: dark
  Hal seperti ini juga bekerja baik di GitHub README: https://github.com/CyberShadow/CyDo#readme
  • Sangat setuju dengan pendekatan ini
    Untuk aplikasi mobile, saya membuat Nix menjalankan emulator Android sekali pakai untuk menghasilkan screenshot terbaru, tanpa perlu pra-konfigurasi dan tanpa meninggalkan data setelah dijalankan
    Dalam kasus saya, setup-nya sendiri juga tidak terlalu sulit; justru lebih sulit memikirkan idenya, dan kode Nix-nya saya buat sekaligus dengan LLM favorit saya
    Memperbarui screenshot secara manual memang bukan pekerjaan paling berat di dunia, tapi alur upload-apk + take-screenshot + transfer-back-to-PC + edit selalu terasa agak merepotkan, jadi pada akhirnya hampir tidak pernah saya lakukan
• Di mobile, scroll horizontal untuk contoh kode benar-benar diperlukan
  Saya masih bisa menebak dari konteks, tapi tetap terasa tidak nyaman
• Ini sangat berguna untuk proyek mobile
  App store mewajibkan screenshot, dan karena harus membuat gambar sebanyak jumlah ukuran layar dikalikan jumlah lokalisasi, prosesnya cepat menjadi merepotkan
  Dulu saya menulis skrip sendiri untuk ini, dan sekarang alat Fastlane seperti https://fastlane.tools/ sangat membantu
  Saya juga memakai Fastlane untuk game puzzle logika saya, Nonoverse, dan Anda bisa melihat contoh screenshot di halaman App Store-nya: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
  Saya juga sudah mengotomatisasi perekaman video App Preview, termasuk beberapa adegan, dan kalau ada yang tertarik rasanya ini cukup layak ditulis sebagai posting terpisah
  • Ini langsung terdengar sangat menarik, tapi saya belum begitu paham apakah ini layanan berbayar atau aplikasi OS yang berjalan secara lokal
• Keren juga
  Game kasual kecil yang saya buat dengan vibe coding selalu dimulai dari kondisi di mana aplikasinya bisa dijalankan headless lewat CLI, dengan rendering tekstur offscreen, perintah screenshot, sampai pengukuran performa
  Menambahkan ini juga hampir tidak memakan waktu, dan memberi agen jalur untuk mengotomatisasi UI serta memeriksa titik-titik penting
  Karena itu, membuat agen memperbarui screenshot juga jadi sangat mudah
  Memang belum serapi bentuk yang benar-benar menyatu ke dalam proses build, tapi sekarang saya jadi ingin menambahkan bagian itu juga
  • Saya juga melakukan hal yang sama
    Saya juga punya argumen CLI untuk offscreen screenshot path serta world pos/camera view vector, dan menjalankan benchmark skrip dengan format input berbasis teks
    Format ini terdiri dari beberapa baris segmen bernama, panjang n game tick untuk tiap segmen, serta input kontrol untuk masing-masing segmen
    Saya sangat sering memakainya saat A/B testing visual dan performa sambil mengerjakan kode game
  • Penasaran apakah Anda bisa membagikan beberapa tautan ke game kasual itu
    Saya juga sangat tertarik dengan seberapa mudah vibe coding membuat pengembangan game
    Pada era Adobe Flash, ekosistem game indie benar-benar sangat hidup, dan setelah itu hampir tidak ada yang menyentuh tingkat kemudahan pengembangan seperti itu
    vibe coding tampaknya seperti alat pertama yang benar-benar melampaui level tersebut
  • Pernyataan hampir tidak memakan waktu untuk menambahkan ini tergantung kasusnya
    Saya penasaran Anda memakai engine apa
• Benar-benar keren
  Saya terutama suka bahwa deklarasi screenshot bisa ditaruh inline di dalam dokumen Markdown
  Untuk aplikasi desktop saya, saya sudah membuat solusi yang menghasilkan screenshot dalam berbagai bahasa dan mode light/dark, menghilangkan noise, bahkan menambahkan frame jendela Windows/macOS
  Saya merangkumnya di sini: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
  Saat ini masih berupa skrip terpisah jadi cukup merepotkan untuk dirawat, tapi saya perlu melihat kemungkinan memasukkannya sebagai bagian dari markdown/mdx
  Ini memberi saya inspirasi yang bagus
• Saya memang sering sekali membutuhkan hal seperti ini
  Sampai-sampai rasanya bisa dipakai sebagai meme seperti karya terbaik X yang tidak akan disadari siapa pun
• Ini bagus
  https://github.com/zombocom/rundoc yang saya buat juga punya fitur serupa
  Tujuan utamanya adalah membuat tutorial, jadi output dari perintah yang dijalankan juga dimasukkan kembali ke dalam dokumen
• Rasanya pendekatan rendering real-time juga mungkin di sini
  Misalnya dengan menaruh live preview dari alat itu di dalam sebuah persegi panjang
  Jika alatnya ringan, ini mungkin optimal juga secara visual, dan pengaturan rendering seperti setelan aksesibilitas browser atau addon pengguna juga bisa tercermin apa adanya
  • Atau cukup lakukan static build untuk HTML
    Dokumentasi iommi memang benar-benar melakukan itu: https://kodare.net/2025/01/14/iframes-not-screenshots.html
  • Tapi saya rasa ini juga bisa menjadi isu keamanan
• Saya pernah berpikir untuk ikut melakukan pembuatan screenshot saat menjalankan tes e2e
  Jika docs/ untuk dokumentasi juga diletakkan di repositori yang sama, lalu setiap kali perlu screenshot baru saat memperbarui dokumentasi kita menambahkan tes baru, sepertinya ini akan cocok sekali
• Bagus
  Saya juga sempat mulai membuat hal yang persis seperti ini beberapa tahun lalu, tapi akhirnya saya mengabstraksikannya ke arah yang lebih umum seperti https://picshift.io/
  Meski begitu, saya tetap sangat menyukai use case screenshot ini, dan nama asli proyek ini juga dulu ScreenSync
  • Bagus, dibuat dengan baik, dan menyenangkan melihat berbagai pendekatan seperti ini bisa hidup berdampingan