Belajar Shiki Rehype Pretty Code - Konsep Dasar & Arsitektur Utama

#Pendahuluan

Episode 1 sudah membahas mengapa kombinasi Shiki dan rehype-pretty-code ada. Sekarang saatnya membuka kap mesin dan melihat bagaimana kombinasi ini bekerja dari dalam. Episode 2 membedah konsep dasar dan arsitektur utama: alur tokenisasi Shiki dari TextMate grammar sampai HTML span, transformasi node yang dilakukan rehype-pretty-code, serta peta lengkap package yang terlibat.

Pemahaman arsitektur ini penting karena semua episode berikutnya berpijak di atasnya. Saat nanti kalian mengatur transformers, memilih engine, atau mengoptimalkan bundle, kalian harus tahu komponen mana yang bekerja di tahap mana. Jadi jangan terburu-buru, karena fondasi ini menentukan seberapa dalam kalian bisa menggali fitur.

#Alur Tokenisasi Shiki di Balik Layar

#TextMate Grammar sebagai Sumber Aturan

Semua berawal dari TextMate grammar, file yang sama yang dipakai VSCode untuk mewarnai kode. Grammar berisi pola berbasis regex yang menghasilkan scope semantik, seperti keyword.control, string.quoted.double, dan entity.name.function. Scope ini bukan warna; warna baru ditentukan belakangan oleh theme.

Konsekuensinya penting: selama grammar-nya sama dengan VSCode, hasil tokenisasi Shiki akan sama persis dengan editor. Inilah yang membuat warna di dokumentasi kalian terasa akrab bagi developer.

#Oniguruma WASM dan Mesin Tokenisasi

Regex TextMate memakai sintaks khas Oniguruma, bukan regex JavaScript biasa. Karena itu Shiki menjalankan Oniguruma melalui WebAssembly untuk menokenisasi teks. Alur kerjanya:

• Teks kode dipecah baris per baris.
• Setiap baris dicocokkan dengan aturan grammar untuk menghasilkan token.
• Setiap token diberi scope yang bisa berlapis.
• Scope dipetakan ke warna sesuai theme.
• Hasilnya dirangkai menjadi HTML span.

Di Shiki v4, mesin tokenisasi bisa dipilih lewat opsi engine. Engine default adalah Oniguruma WASM dari @shikijs/engine-oniguruma, dan ada alternatif JavaScript engine dari @shikijs/engine-javascript untuk bundle yang lebih kecil dengan kecepatan lebih lambat. Pemilihan engine ini akan kita perdalam di episode 13.

Peta alur tokenisasi Shiki

const kode = "const nilai = 42;";
const highlighter = await createHighlighter({
  langs: ["javascript"],
  themes: ["github-dark-default"],
});
const html = highlighter.codeToHtml(kode, {
  lang: "javascript",
  theme: "github-dark-default",
});

Perhatikan bahwa createHighlighter(options) menerima daftar langs dan themes yang dimuat ke memori. Setelah highlighter siap, codeToHtml(kode, opsi) menokenisasi dan langsung menghasilkan HTML berisi span berwarna.

#Output Berbentuk Span Berwarna

Hasil akhir dari Shiki murni adalah elemen <pre> dengan elemen <code> yang di dalamnya berisi banyak <span> ber-style warna dan token. Inilah HTML jadi yang bisa langsung dirender tanpa JavaScript di browser.

rehype-pretty-code tidak mengganti mekanisme ini; dia menambah lapisan struktur di sekelilingnya. Peran keduanya tegas: Shiki mengerjakan warna, rehype-pretty-code mengerjakan pengalaman code block.

#Peran rehype-pretty-code dalam Pipeline

#Mengubah Node pada Pohon HAST

rehype-pretty-code adalah plugin rehype, artinya dia bekerja pada pohon HAST (Hypertext Abstract Syntax Tree) setelah Markdown diubah menjadi HTML. Tugasnya sederhana dalam kata-kata: mendeteksi node <pre> dan <code> yang berasal dari fenced code block, lalu menggantinya dengan struktur yang lebih kaya.

Sebelum plugin bekerja, node masih polos: <pre> dan <code> tanpa metadata. Setelah plugin bekerja, node berubah menjadi:

• <figure> sebagai pembungkus utama dengan atribut data-rehype-pretty-code-figure.
• <pre> dengan atribut data-theme berisi kode yang sudah ditokenisasi.
• Elemen judul dan caption jika meta string menyediakannya.
• <code> dengan token span dari Shiki.

Transformasi ini terjadi pada pohon HAST sebelum halaman di-render, sehingga tidak ada langkah ekstra di sisi klien.

#Data Attributes sebagai Bahasa Styling

Hal paling penting yang ditambahkan rehype-pretty-code adalah data attributes yang menjadi pegangan CSS kalian. Beberapa yang paling sering dipakai:

• data-line pada setiap baris token.
• data-highlighted-line pada baris yang diminta highlight lewat meta.
• data-highlighted-chars pada karakter atau kata yang ditandai.
• data-line-numbers ketika penomoran baris aktif.
• data-changed-line, data-added-line, dan data-removed-line untuk blok diff.

Karena memakai data attributes, kalian bisa memberi style dari luar tanpa menyentuh output HTML Shiki. Ini menjaga fleksibilitas dan membuat tema bisa diganti kapan saja.

#Komponen Utama yang Perlu Kalian Kenal

#Package Inti dari Ekosistem Shiki

Ekosistem Shiki v4 dipecah menjadi package-package kecil yang bisa dipilih sesuai kebutuhan:

• shiki sebagai package utama yang merangkum highlighter, langs, dan themes.
• @shikijs/langs berisi kumpulan grammar bahasa.
• @shikijs/themes berisi kumpulan theme siap pakai.
• @shikijs/transformers berisi transformer bawaan seperti transformerNotationDiff.
• @shikijs/engine-oniguruma dan @shikijs/engine-javascript sebagai mesin tokenisasi.
• @shikijs/rehype sebagai plugin rehype resmi dari tim Shiki.

Pecahan package ini adalah salah satu perubahan besar di Shiki v4. Dengan memilih package secara selektif, ukuran bundle build bisa jauh lebih kecil — topik yang kita perdalam di episode 12 dan 13.

#Pipeline unified yang Menghubungkan Semuanya

Semua komponen bertemu di dalam pipeline unified. Pipeline ini bekerja berurutan: teks Markdown di-parse, diubah ke HTML, diberi highlight, lalu di-stringify. Urutan plugin sangat menentukan hasil akhir.

Pipeline unified lengkap

unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypePrettyCode, {
    theme: "github-dark-default",
    defaultLang: "plaintext",
  })
  .use(rehypeStringify);

Pada pipeline ini, rehypePrettyCode(options) dipasang setelah remarkRehype. Urutan ini wajib karena rehype-pretty-code hanya bisa bekerja pada HAST yang sudah terbentuk. Jika kalian memasangnya sebelum remarkRehype, plugin tidak akan menemukan node <pre> yang dicari.

#Penutup

Inti yang harus dibawa pulang:

• Shiki menokenisasi kode memakai TextMate grammar lewat Oniguruma WASM.
• Output Shiki berupa HTML span berwarna yang sudah jadi.
• rehype-pretty-code bekerja pada pohon HAST sebagai plugin rehype.
• Plugin mengubah node <pre> dan <code> menjadi <figure> kaya metadata.
• Data attributes seperti data-line dan data-highlighted-line menjadi pegangan CSS.
• Pipeline unified mengatur urutan parse, transform, dan stringify.

Di episode 3 kalian akan langsung praktik: menginstal shiki dan rehype-pretty-code, menyusun pipeline minimal, dan merender code block pertama kalian. Pastikan Node.js dan package manager sudah terpasang, karena mulai sekarang kalian akan banyak mengetik perintah npm.