Belajar Shiki Rehype Pretty Code - Custom HAST & Rehype Plugin Lanjutan

#Pendahuluan

rehype-pretty-code menghasilkan markup yang sudah lengkap, tetapi kebutuhan nyata sering melampaui fitur bawaannya: menambahkan bahasa pada tombol copy, mengubah class tertentu, atau menyuntikkan metadata dari luar. Semua itu bisa dilakukan dengan memodifikasi pohon HAST setelah plugin selesai.

Episode 17 membahas custom HAST dan rehype plugin lanjutan: memahami bentuk node HAST, menulis plugin rehype kustom yang mengunjungi dan mengubah node, serta menyusun urutan plugin yang benar dalam pipeline yang kompleks.

#Memahami HAST

#Pohon Node untuk HTML

HAST adalah representasi pohon untuk HTML yang dipakai pipeline rehype. Elemen seperti figure, pre, dan code adalah node element dengan properti tagName, properties, dan children. Atribut seperti data-rehype-pretty-code-figure tersimpan di properties sebagai pasangan kunci dan nilai.

Berikut bentuk salah satu node hasil rehype-pretty-code:

Bentuk node figure

{
  type: "element",
  tagName: "figure",
  properties: { dataRehypePrettyCodeFigure: "" },
  children: [{ type: "element", tagName: "pre", children: [] }]
}

Pemahaman struktur ini menjadi dasar untuk menulis plugin yang menargetkan elemen tertentu. Semua modifikasi kalian berakhir sebagai atribut pada HTML akhir.

#Mengapa Memodifikasi HAST

Modifikasi pada pohon lebih aman daripada memanipulasi string HTML. Karakter yang perlu di-escape tetap ditangani oleh rehype-stringify, dan atribut yang ditambahkan melalui properties diubah menjadi atribut HTML yang valid. Ini menjaga output tetap bersih dan terhindar dari bug escape.

#Membuat Rehype Plugin Kustom

#Struktur Plugin

Rehype plugin adalah fungsi yang menerima options dan mengembalikan transformer. Transformer menerima pohon HAST dan boleh mengubahnya secara langsung:

Plugin untuk menambah atribut bahasa

import { visit } from "unist-util-visit";
 
export function rehypeAddLangAttribute(options) {
  return (tree) => {
    visit(tree, { tagName: "figure" }, (node) => {
      const code = node.children.find(
        (child) => child.tagName === "code",
      );
      const lang = code?.properties?.dataLanguage;
      if (lang) {
        node.properties.dataLang = lang;
      }
    });
  };
}

Plugin di atas memakai unist-util-visit untuk menemukan semua figure. Setiap figure yang berisi code dengan bahasa mendapat atribut data-lang yang bisa dibaca JavaScript di sisi klien.

#Memasang Plugin di Pipeline

Daftarkan plugin setelah rehype-pretty-code agar node sudah berbentuk figure saat diakses:

Urutan pemasangan

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

Urutan ini menjamin plugin kustom melihat struktur yang sudah lengkap. Jika dipasang sebelum rehype-pretty-code, tidak ada node figure yang ditemukan dan plugin tidak melakukan apa pun.

#Memodifikasi Figure dan Pre

#Menambahkan Atribut pada Pre

Terkadang kalian perlu menandai <pre> agar CSS bisa menargetkannya secara spesifik. Tambahkan atribut langsung ke properti node:

Tambahkan atribut pada pre

import { visit } from "unist-util-visit";
 
export function rehypeMarkCodeBlocks() {
  return (tree) => {
    visit(tree, { tagName: "pre" }, (node) => {
      node.properties.dataCodeBlock = "";
    });
  };
}

Setelah plugin ini berjalan, setiap <pre> membawa data-code-block. CSS dan JavaScript klien bisa memakainya tanpa harus mengandalkan struktur figure yang mungkin berbeda antar versi plugin.

#Menyisipkan Node Baru

Plugin juga bisa menambah elemen, misalnya membungkus kode dengan wrapper untuk styling. Gunakan node element biasa dan tempatkan pada children:

Sisipkan wrapper

visit(tree, { tagName: "figure" }, (node) => {
  node.children.push({
    type: "element",
    tagName: "div",
    properties: { className: ["code-footer"] },
    children: [],
  });
});

Node yang disisipkan harus mengikuti format HAST: type, tagName, properties, dan children. rehype-stringify akan mengubahnya menjadi HTML yang benar.

#Urutan Plugin dalam Pipeline

#Rangkaian yang Umum

Pipeline produksi sering menggabungkan banyak plugin. Contoh urutan yang masuk akal:

Pipeline lengkap

unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeRaw)
  .use(rehypePrettyCode, { theme: "github-dark-default" })
  .use(rehypeSlug)
  .use(rehypeAutolinkHeadings)
  .use(rehypeSanitize)
  .use(rehypeStringify);

rehypeRaw mengubah HTML mentah di dalam Markdown menjadi node, lalu rehypePrettyCode memproses code block, diikuti rehypeSlug dan rehypeAutolinkHeadings untuk heading, dan sanitasi di akhir.

#Aturan Menentukan Urutan

Prinsipnya sederhana: plugin yang mengubah struktur harus dijalankan sebelum plugin yang membaca struktur tersebut. Bahasa di-highlight sebelum heading diberi id, dan sanitasi selalu di akhir untuk membersihkan semua output sebelumnya. Menukar urutan bisa membuat plugin kehilangan target atau membiarkan markup yang tidak aman lolos.

#Penutup

Inti yang harus dibawa pulang:

• HAST adalah pohon node element dengan tagName, properties, dan children.
• Modifikasi pada HAST lebih aman daripada manipulasi string HTML.
• Rehype plugin kustom dibuat dari fungsi yang mengembalikan transformer.
• unist-util-visit membantu menemukan node tertentu dalam pohon.
• Node baru disisipkan dalam format HAST yang lengkap.
• Urutan plugin menentukan apakah transformasi saling mendukung atau merusak.

Di episode 18 kalian akan belajar Shiki core dan highlighter API: memakai createHighlighter, createHighlighterCore, codeToHtml, codeToTokens, dan getSingletonHighlighter, serta memakai Shiki di luar rehype seperti markdown-it, CLI, atau render manual.