[🛠] Mengubah catatan kaki blog GitHub Pages menjadi popover

✨ Ringkasan GPT-5.5 　

Catatan tentang mengurangi rasa tidak nyaman dari catatan kaki bawaan Kramdown yang membawa pembaca dari badan tulisan ke referensi di bagian bawah, sambil tetap mempertahankan struktur catatan kaki yang ada dan mengubah tautan catatan di badan tulisan menjadi UI popover berbentuk [1].

Begitu aku mulai memakai catatan kaki dengan serius, rasa tidak nyamannya langsung terlihat.

Saat membahas artikel luar atau bahan rujukan di blog, sekarang aku menambahkan footnote Kramdown di samping bagian teks yang relevan. Terutama tulisan seperti Kasus kekurangan surat suara yang belum pernah terjadi, kemarahan, dan kerusakan akibat ekstremis punya banyak fakta, jadi catatan kakinya juga cukup banyak.

Tapi ketika dibaca langsung, alurnya kurang enak.

Saat nomor catatan kaki di badan tulisan diklik, yang muncul bukan popup. Halaman justru turun ke area Referensi paling bawah. Sebagai perilaku bawaan, itu memang benar. Kramdown memang membuat catatan kaki seperti itu. Tapi pada tulisan panjang, posisi baca mudah hilang.

Bentuk nomor catatan kakinya juga agak canggung.

Kalau yang terlihat hanya angka kecil seperti 1 2 3 4, sulit untuk diklik. Di mobile lebih terasa lagi. Menekan angka kecil yang mengambang di tengah teks ternyata membutuhkan perhatian lebih dari yang semestinya.

Jadi kali ini aku sedikit mengubah sistem catatan kaki.

Di badan tulisan, catatan terlihat seperti [1], [2], [3], dan saat ditekan, halaman tidak turun ke bawah, melainkan membuka popover kecil.

Struktur Kramdown tidak kuubah

Sejak awal aku tidak ingin mengubah sintaks Markdown atau cara footnote dibuat.

Sekarang tulisan memakai format seperti ini.

Kalimat di badan tulisan.[^source]

[^source]: Penjelasan sumber dan tautan

Cara ini sebaiknya tetap dipertahankan.

Dari sisi penulisan, aku memakai sintaks yang cukup dekat dengan standar Markdown, lalu saat Jekyll melakukan build, Kramdown membuat HTML catatan kaki. Area Referensi di bawah juga tetap ada. Kalau struktur ini ikut diganti, semua tulisan lama dan terjemahannya juga bisa ikut tersentuh.

Jadi kriteria pekerjaan kali ini sederhana.

Format penulisan tetap dipertahankan.
Catatan kaki bawah yang dibuat Kramdown tetap dipertahankan.
Yang diubah hanya tampilan dan perilaku klik tautan catatan kaki di badan tulisan.

Dengan kata lain, data asli dan fallback tetap ada, hanya pengalaman membacanya yang diperbaiki.

Nomor catatan kaki dibuat terlihat seperti [1]

Pertama aku mengubah CSS.

Kramdown memberi class a.footnote pada tautan catatan kaki di badan tulisan. Tautan itu kubuat seperti tombol inline-flex kecil, lalu kutambahkan kurung siku dengan ::before dan ::after.

Hasilnya, di badan tulisan tidak lagi terlihat seperti satu angka saja, tetapi seperti ini.

[1] [2] [3]

Area yang bisa ditekan juga sedikit diperlebar.

Kalau terlihat seperti tombol besar, ritme teks akan rusak. Tapi kalau tetap berupa angka kecil seperti sebelumnya, sulit diklik. Jadi aku hanya menambahkan border dan latar yang sangat tipis, sementara ukuran huruf tetap lebih kecil dari teks utama.

Karena blog ini punya mode terang dan gelap, warna tidak ku-hardcode. Aku menyesuaikannya dengan variabel Sass yang sudah ada.

$primary-color
$background-color
$border-color
$text-color

Blog ini sudah memuat customOverride.scss setelah skin terang dan gelap. Jadi aku menambahkan style catatan kaki di _sass/custom/customOverride.scss, bukan mengubah langsung file asli tema.

Klik membuat popover

Berikutnya JavaScript.

Sebelumnya, SmoothScroll dipasang pada semua tautan #hash. Tautan catatan kaki pada akhirnya juga tautan internal ke sesuatu seperti #fn:..., jadi saat diklik halaman akan bergerak halus ke bawah.

Kali ini aku mencegat lebih dulu hanya tautan catatan kaki di badan tulisan.

Targetnya ini.

.page__content a.footnote[href^="#fn"]

Saat diklik, pergerakan hash bawaan dicegah, lalu isi catatan yang sudah dirender di daftar catatan bawah dicari dan dikloning. Di dalam catatan bawah ada tautan reversefootnote untuk kembali ke badan tulisan, tetapi di dalam popover itu tidak diperlukan, jadi dihapus.

Alurnya seperti ini.

Klik catatan kaki di badan tulisan
-> baca target id dari href
-> cari footnote li di bawah
-> clone isinya
-> hapus reversefootnote
-> masukkan ke popover
-> hitung posisi di dekat tautan catatan kaki

Karena hash tidak diubah, URL juga tidak menjadi berantakan. Halaman juga tidak turun ke bagian paling bawah.

Ada tiga cara untuk menutupnya.

Klik lagi catatan kaki yang sama
Klik di luar popover
Esc atau tombol tutup

Untuk penggunaan keyboard, aku juga menambahkan aria-haspopup="dialog" dan aria-expanded. Popover itu sendiri memakai role="dialog". Ini belum sampai bisa disebut komponen aksesibilitas yang sempurna, tetapi setidaknya lebih baik daripada div mengambang tanpa makna.

Dibuat agar tidak keluar layar di mobile

Posisi popover catatan kaki penting.

Menampilkannya tepat di bawah tautan badan tulisan terasa alami, tetapi di dekat sisi kanan layar atau pada lebar mobile, popover mudah keluar layar.

Jadi saat menentukan posisi, aku memaksa margin di dalam viewport.

Kiri minimal 12px
Kanan juga minimal 12px
Jika ruang bawah kurang, tampilkan di atas
Jika masih kurang, clamp ke dalam viewport

Lebar popover juga bukan lebar tetap.

width: min(30rem, calc(100vw - 1.5rem));

Di desktop, popover tidak terlalu lebar. Di mobile, popover tidak lebih lebar dari layar.

Untuk catatan kaki yang panjang, aku juga menambahkan max-height dan overflow: auto. Tujuannya agar judul artikel luar atau tautan yang panjang tidak membuat popover menutupi seluruh layar.

File minified juga diperbarui

Di blog ini, assets/js/_main.js adalah source, sedangkan situs yang dipublikasikan membaca assets/js/main.min.js.

Jadi setelah memperbaiki JS, aku membuat ulang file minified dan source map dengan task Rake.

bundle exec rake js

Kalau langkah ini terlewat, source lokal bisa terlihat sudah benar, tetapi situs sebenarnya masih menyajikan JS lama. Untuk pekerjaan seperti ini, file source dan file distribusi harus dilihat bersama.

Yang aku cek

Pengecekan dilakukan seperti ini.

node --check assets/js/_main.js
bundle exec rake js
bundle exec jekyll build

Lalu aku membuka tulisan nyata yang punya banyak catatan kaki lewat server statis lokal.

Yang dicek adalah ini.

Apakah tautan catatan kaki terlihat dalam bentuk [1]
Apakah URL hash tidak berubah setelah diklik
Apakah halaman tidak berpindah ke area referensi bawah
Apakah popover muncul
Apakah isi catatan kaki bawah masuk ke popover
Apakah popover tetap berada di dalam layar pada lebar mobile

Di desktop, posisi catatan kaki bawah memang jauh di bagian bawah dokumen, tetapi setelah catatan kaki diklik, scroll tetap berada di sekitar badan tulisan. Pada lebar mobile, popover juga tetap berada di dalam layar.

Fiturnya kecil, tapi rasa membaca cukup berubah

Pekerjaan ini bukan fitur besar.

Tidak ada model data, tidak ada routing, tidak ada halaman baru. Hanya membuat tautan catatan kaki yang sudah ada menjadi lebih mudah dilihat, lalu menampilkan popover saat diklik.

Tapi rasa membacanya cukup berubah.

Terutama pada tulisan yang banyak fakta, catatan kaki bukan hiasan. Saat pembaca berpikir, “ini asalnya dari mana?”, ia harus bisa langsung memeriksanya. Kalau untuk memeriksa saja ia dilempar ke bagian paling bawah tulisan lalu harus kembali lagi ke badan tulisan, catatan kaki cepat terasa menyebalkan.

Sekarang pembaca bisa menekan [1] sambil membaca badan tulisan, mengecek sumber, lalu menutupnya.

Bagian Referensi di bawah juga tetap ada. Orang yang ingin melihat semua sumber sekaligus di akhir tulisan masih bisa menggulir ke bawah.

Itu saja yang kuinginkan.

Cara menulis Markdown tetap sama. Struktur dasar Jekyll/Kramdown tetap hidup. Yang dibuat lebih ringan hanya jari dan mata pembaca.

Kecil, tetapi blog memang perlu terus menumpuk perbaikan seperti ini.