Belajar Shiki Rehype Pretty Code - Options Dasar rehype-pretty-code

#Pendahuluan

Pipeline hello world di episode 3 hanya memakai satu opsi: theme. Padahal rehype-pretty-code menyediakan banyak options dasar yang menentukan perilaku highlight dan bentuk markup keluaran. Episode 4 membedah lima opsi paling mendasar: theme, keepBackground, defaultLang, grid, dan bypassInlineCode.

Selain memahami arti tiap opsi, kalian juga perlu memahami struktur output HTML yang dihasilkan. Markup <figure>, <pre>, dan <code> dengan data attributes inilah yang akan kalian styling dengan CSS di seluruh proyek konten kalian.

#Membaca Options Dasar

#theme: Menentukan Palet Warna Utama

Opsi theme menentukan palet warna yang dipakai Shiki saat menokenisasi. Nilainya bisa string nama theme bawaan, objek theme Shiki, atau objek berisi beberapa theme untuk mode terang dan gelap.

Menyetel theme

.use(rehypePrettyCode, {
  theme: "github-dark-default",
})

Nilai defaultnya adalah github-dark-default. Karena tema ini gelap, pastikan kalian juga menyetel background di CSS agar kode tetap terbaca. Di episode 15 kita akan mengupas object theme untuk dual mode terang dan gelap.

#keepBackground: Mengontrol Background dari Theme

Theme Shiki biasanya menyertakan warna background. Opsi keepBackground menentukan apakah background itu ikut disalin ke output HTML atau tidak.

Matikan background bawaan

.use(rehypePrettyCode, {
  theme: "one-dark-pro",
  keepBackground: false,
})

Nilai defaultnya true, artinya background theme ikut dipakai. Jika kalian ingin mengelola background sendiri lewat CSS, setel keepBackground menjadi false. Ini berguna ketika background halaman sudah ditentukan dan warna theme hanya diperlukan untuk token.

#Opsi untuk Kode dan Grid

#defaultLang: Bahasa Cadangan

Opsi defaultLang menentukan bahasa yang dipakai ketika sebuah fenced code block tidak mencantumkan meta bahasa.

Bahasa cadangan

.use(rehypePrettyCode, {
  defaultLang: "plaintext",
})

Tanpa defaultLang, code block tanpa meta bahasa tidak di-highlight dan dibiarkan polos. Mengatur defaultLang menjadi plaintext menjaga kode tetap utuh tanpa warna, sementara nilai seperti ts akan memberikan highlight meski penulis lupa menyebutkan bahasanya.

#grid: Menambahkan Karakter Grid

Opsi grid menambahkan karakter grid di belakang setiap token untuk membantu penyejajaran visual saat elemen kode dirender sebagai grid CSS.

Aktifkan grid

.use(rehypePrettyCode, {
  grid: true,
})

Fitur ini bermanfaat saat kalian memakai CSS grid untuk baris kode, misalnya pada layout dengan nomor baris yang harus selalu sejajar. Karakter grid biasanya disembunyikan secara visual lewat CSS dengan warna transparan.

#bypassInlineCode: Mengontrol Kode Inline

Secara default rehype-pretty-code tidak menyentuh kode inline, yaitu teks yang dibungkus satu pasang backtick. Opsi bypassInlineCode yang defaultnya true membuat perilaku itu.

Aktifkan highlight inline

.use(rehypePrettyCode, {
  bypassInlineCode: false,
})

Saat disetel false, kode inline bisa di-highlight dengan syntax `kode{:js}`. Fitur lengkapnya akan kita praktikkan di episode 9, karena ini memengaruhi banyak bagian penulisan dokumentasi.

#Memahami Struktur Output HTML

#Dari pre Polos Menjadi figure Berstruktur

Salah satu perbedaan terbesar rehype-pretty-code adalah bentuk markup yang dihasilkan. Sebuah fenced code block:

Contoh input markdown

const s = "halo";

akan diubah menjadi struktur <figure> yang membungkus <pre> dan <code>:

Struktur output yang disederhanakan

<figure data-rehype-pretty-code-figure>
  <pre data-theme="github-dark-default">
    <code data-language="ts">
      <span>const</span>
      <span>s</span>
    </code>
  </pre>
</figure>

Struktur ini memberi kalian "pegangan" CSS yang jelas. Elemen <figure> bisa dijadikan container dengan border dan radius, <pre> diatur untuk scroll, dan <code> untuk font serta padding.

#Data Attributes sebagai API Styling

Setiap fitur yang kalian minta lewat meta string akan diterjemahkan menjadi data attributes. Misalnya baris yang di-highlight memunculkan data-highlighted-line, dan nomor baris memunculkan data-line-numbers pada elemen <code>.

[data-rehype-pretty-code-figure] pre {
  border-radius: 8px;
  overflow-x: auto;
}

Aturan CSS seperti [data-rehype-pretty-code-figure] pre tidak memerlukan class tambahan dari kalian. Cukup andalkan atribut yang sudah dihasilkan, dan seluruh tema visual code block bisa dikendalikan dari satu tempat.

#Penutup

Inti yang harus dibawa pulang:

• theme menentukan palet warna, defaultnya github-dark-default.
• keepBackground mengontrol apakah background theme ikut disalin.
• defaultLang menjadi bahasa cadangan untuk code block tanpa meta.
• grid membantu penyejajaran visual baris kode.
• bypassInlineCode mengatur apakah kode inline ikut di-highlight.
• Output standarnya berupa <figure> dengan <pre> dan <code> kaya data attributes.

Di episode 5 kalian akan belajar memilih bahasa dan theme dengan tepat: cara menulis meta bahasa pada fenced code block, mengenal daftar bahasa dari @shikijs/langs, serta memilih theme bawaan yang cocok dan mengatur background-nya sendiri.