Belajar Shiki Rehype Pretty Code - Diff & Anotasi Kode

#Pendahuluan

Artikel teknis yang menjelaskan perubahan kode sering membuat pembaca bingung membaca baris demi baris. Diff block menyelesaikan masalah ini: kode sebelum dan sesudah ditampilkan berdampingan, dengan baris yang ditambah dan dihapus diberi tanda yang langsung terlihat.

Episode 8 membahas diff dan anotasi kode: cara mengaktifkan mode diff lewat meta string, menandai baris tambah dan hapus, menambahkan anotasi berupa line highlight dan caption, serta memadukan semuanya dalam satu blok yang rapi. Setelah episode ini, kalian bisa menjelaskan migrasi kode dengan visual yang jelas tanpa satu baris teks pun.

#Membuat Diff Block

#Meta diff dan Marker Tambah Hapus

Mode diff diaktifkan dengan menambahkan kata kunci diff pada meta string fenced code block. Di dalam isi blok, kalian menandai baris yang ditambah dengan // + dan baris yang dihapus dengan // -. Berikut contoh blok diff pada bahasa TypeScript:

Contoh diff sederhana

const a = 1;
const b = 2;
// +console.log(a + b);
// -console.log(a * b);

Kombinasi meta string dan marker ini menghasilkan markup yang khas. Baris dengan marker + mendapat atribut data-added-line, sedangkan baris dengan marker - mendapat atribut data-removed-line. Keduanya menjadi target styling di CSS.

#Instalasi dan Pemeriksaan Versi

Sebelum mencoba, pastikan versi package kalian mendukung fitur diff. Jalankan perintah berikut di terminal:

npm view rehype-pretty-code version
npm view @shikijs/transformers version

Perintah npm view rehype-pretty-code version membaca versi terbaru dari registry npm. Fitur diff memakai mesin rehype-pretty-code langsung, jadi tidak perlu dependency tambahan untuk memulainya.

#Anotasi Baris Penting

#Menggabungkan Diff dengan Line Highlight

Diff hanya menandai perubahan. Untuk menarik perhatian ke baris tertentu di luar konteks tambah-hapus, gabungkan meta diff dengan lines pada baris pembuka. Instruksi lengkapnya seperti diff lines={2}:

Diff dengan line highlight

const nama = "dunia";
// +console.log(`Halo, ${nama}`);
// -console.log(nama);

Meta lines={2} menandai baris kedua sebagai baris yang disorot penuh, terlepas dari status diff-nya. Anotasi ini berguna ketika kalian ingin menyorot baris yang berubah namun tidak menambah atau menghapus apa pun, seperti perbaikan nama variabel.

#Caption sebagai Anotasi Konteks

Anotasi tidak harus berupa highlight. Caption menjelaskan mengapa perubahan dilakukan. Tambahkan caption pada meta string sehingga pembaca memahami tujuan diff tanpa membaca paragraf panjang:

Diff dengan caption

const daftar = [1, 2, 3];
const total = daftar.reduce((a, b) => a + b, 0);
// +console.log("total", total);

Caption tampil di bawah blok dan melengkapi title di atas blok. Kombinasi title, caption, dan diff membuat blok berdiri sendiri sebagai unit informasi yang utuh.

#Styling Diff di CSS

#Warna Tambah dan Hapus

Data attributes bawaan memudahkan styling tanpa class tambahan. Targetkan atribut data-added-line dan data-removed-line di stylesheet:

[data-rehype-pretty-code-figure] [data-added-line] {
  background-color: rgba(46, 160, 67, 0.15);
}
[data-rehype-pretty-code-figure] [data-removed-line] {
  background-color: rgba(248, 81, 73, 0.15);
}

Baris yang ditambah diberi nuansa hijau dan baris yang dihapus diberi nuansa merah. Warna ini meniru tampilan editor diff modern sehingga pembaca langsung mengenali polanya.

#Menjaga Keterbacaan

Hindari warna yang terlalu pekat agar token kode tetap terbaca. Background transparan dengan opacity rendah menjaga kontras teks tetap tinggi. Kalian juga bisa menambah garis vertikal di sisi kiri blok, mirip teknik line highlighting di episode 7.

#Contoh Lengkap Diff

#Diff, Highlight, dan Caption Sekaligus

Mari gabungkan semua fitur dalam satu blok yang mewakili perbaikan bug:

Diff lengkap

export function proses(input) {
  if (!input) return null;
// +  const bersih = input.trim();
  return bersih ?? input;
}

Baris yang ditambah disorot hijau lewat diff, sementara lines={3} menambahkan anotasi penuh pada baris tersebut. Jika kalian memeriksa DevTools, baris 3 akan membawa atribut data-added-line dan data-highlighted-line sekaligus.

#Memeriksa Markup Hasil Diff

Untuk memastikan atribut benar-benar dihasilkan, filter hasil render seperti sebelumnya:

Periksa atribut diff

const attr = html.matchAll(/data-(added|removed|highlighted)-line/g);
console.log([...attr].map((m) => m[0]));

Menjalankan skrip pemeriksaan ini membantu kalian memahami bahwa diff, anotasi, dan highlight bekerja pada lapisan atribut yang sama dan bisa digabungkan bebas.

#Penutup

Inti yang harus dibawa pulang:

• Mode diff diaktifkan lewat meta diff pada fenced code block.
• Baris ditambah memakai marker // + dan dihapus memakai marker // -.
• Baris diff menghasilkan data-added-line dan data-removed-line.
• Anotasi bisa dikombinasikan: lines untuk highlight dan caption untuk konteks.
• Styling diff dilakukan murni di CSS dengan menargetkan atribut.
• Diff, line highlight, dan caption bisa hadir dalam satu blok yang sama.

Di episode 9 kalian akan belajar inline code highlighting: cara menonaktifkan bypassInlineCode agar kode inline seperti console.log di dalam kalimat ikut di-highlight sesuai bahasa, sekaligus menyamakan semantik warnanya dengan code block di sekitar.