Cheatsheet MDX
14 Mei 2025
L Azlan Rafar
Software Engineer
Tujuan Referensi Ini
Saya membuat dokumen ini sebagai pusat referensi untuk semua hal terkait konfigurasi MDX yang digunakan di proyek ini. Saat membangun situs yang kaya konten, mudah sekali lupa sintaks spesifik sebuah komponen kustom atau anotasi yang tepat untuk sebuah code block. Cheatsheet ini menjadi rujukan cepat bagi siapa saja yang ingin menggunakan atau memahami setup yang ada.
Mengapa MDX?
Keputusan menggunakan MDX didorong oleh kebutuhan akan lebih dari sekadar teks statis. Saya ingin bisa menyisipkan elemen interaktif, live preview, dan media kaya ke dalam dokumentasi teknis tanpa mengorbankan keterbacaan Markdown standar. Dengan menggabungkan kedua dunia ini, kita mendapatkan sistem andal yang terasa natural bagi developer maupun penulis.
Sintaks Dasar Markdown
MDX mendukung semua fitur Markdown standar secara langsung. Anda bisa menggunakannya untuk menyusun ide dengan cepat sebelum menambahkan komponen yang lebih kompleks.
Tipografi dan Daftar
Anda bisa membuat heading, daftar, dan format teks dasar dengan simbol sederhana:
- Teks tebal untuk penekanan
- Teks miring untuk sorotan halus
Inline codeuntuk variabel atau potongan kode singkat
Blok kutipan juga didukung untuk menyoroti pemikiran atau saran penting:
Markdown adalah fondasinya, tetapi MDX adalah arsitektur yang memungkinkan kita membangun sesuatu yang lebih interaktif.
Mengelola Metadata dengan Frontmatter
Setiap file MDX di proyek ini wajib memiliki blok frontmatter YAML di bagian paling atas. Blok ini digunakan oleh build system untuk membuat judul halaman, deskripsi, dan thumbnail.
Metadata ini penting untuk SEO serta untuk pembuatan indeks blog dan link navigasi secara otomatis.
Syntax Highlighting dengan Rehype Pretty Code
Agar code block mudah dibaca, saya menggunakan plugin bernama rehype-pretty-code. Plugin ini menangani syntax highlighting saat proses build, sehingga pengguna tidak perlu mengunduh library besar hanya untuk melihat teks berwarna.
Fitur Highlighting
Plugin ini mendukung beberapa anotasi andal yang melampaui pewarnaan standar:
- Highlight Baris: Gunakan
// [!code highlight]untuk menarik perhatian ke baris tertentu. - Indikator Diff: Gunakan
// [!code ++]atau// [!code --]untuk menunjukkan perubahan kode. - Highlight Kata: Gunakan
// [!code word:X]untuk menyorot setiap kemunculan kata tertentu.
Contoh Code Block
Komponen Kustom
Salah satu alasan utama menggunakan MDX adalah kemampuan menyematkan komponen React langsung ke dalam konten. Ini berguna untuk membangun pola UI yang dapat digunakan ulang dalam dokumentasi.
Komponen Alert
Anda bisa menggunakan komponen Alert untuk menonjolkan informasi tertentu:
Komponen ini cocok untuk catatan, peringatan, atau callout yang perlu menonjol dari teks lainnya.
Menyematkan Media Kaya
Selain teks dan kode biasa, MDX memungkinkan integrasi konten pihak ketiga menggunakan iframe dan widget kustom.
Musik dan Audio
Anda bisa menyematkan pemutar musik dari Spotify atau Apple Music untuk menambahkan soundtrack ke postingan atau membagikan lagu tertentu.
Lagu Spotify
Album Spotify
Konten Video
Video YouTube dapat disematkan dengan iframe sederhana. Saya menyarankan rasio aspek enam belas banding sembilan agar video menyesuaikan ukuran dengan benar di semua layar.
Integrasi Teknis dengan Next.js
Di balik layar, proyek ini menggunakan @next/mdx untuk memproses file MDX saat build. Konten diperlakukan seperti komponen React yang sudah dikompilasi, sehingga kita bisa melakukan query post, mengurutkannya berdasarkan tanggal, dan memvalidasi frontmatter secara otomatis.
Keunggulan Setup Ini
- Type Safety: Setiap post divalidasi terhadap schema di
lib/posts.ts. - Performa: Konten diproses dan dioptimalkan saat build.
- Fleksibilitas: Memudahkan kita menambahkan plugin rehype atau remark baru untuk memperluas kemampuan sistem MDX.
Penutup
Cheatsheet ini akan terus berkembang seiring pertumbuhan proyek. Ini adalah tempat pertama yang perlu Anda cek saat ragu cara menerapkan fitur tertentu dalam tulisan Anda. Dengan mengikuti pola-pola ini, kita memastikan seluruh situs tetap konsisten dan berperforma baik.
Gambar oleh Camila Q. Franco