Panduan Menulis MDX untuk Pemula

MDX adalah format yang menggabungkan kekuatan Markdown dengan fleksibilitas komponen. Jika Anda terbiasa menulis Markdown, MDX akan terasa familiar — dengan tambahan kemampuan super. Artikel ini akan mengajarkan semua yang perlu Anda ketahui.

Apa Itu MDX?

MDX = Markdown + JSX

MDX memungkinkan Anda:

• Menulis konten dengan syntax Markdown yang familiar
• Menyisipkan komponen interaktif di tengah konten
• Menggunakan JavaScript untuk logika dinamis
• Mengimpor dan menggunakan komponen Astro/React

Syntax Markdown Dasar

Heading

Gunakan tanda # untuk heading. Jumlah # menentukan level:

# Heading 1 (H1) - Jangan gunakan, title sudah H1
## Heading 2 (H2) - Section utama
### Heading 3 (H3) - Sub-section
#### Heading 4 (H4) - Sub-sub-section

Paragraf dan Line Break

Paragraf dipisahkan dengan baris kosong:

Ini paragraf pertama. Lorem ipsum dolor sit amet.

Ini paragraf kedua. Dipisahkan oleh baris kosong.

Untuk line break dalam paragraf yang sama,
gunakan dua spasi di akhir baris  
atau tag <br />.

Bold dan Italic

**Teks bold** atau __juga bold__
*Teks italic* atau _juga italic_
***Bold dan italic***
~~Strikethrough~~

Hasil:

• Teks bold
• Teks italic
• Bold dan italic
• Strikethrough

List

- Item pertama
- Item kedua
  - Sub-item (indent 2 spasi)
  - Sub-item lagi
- Item ketiga

1. Langkah pertama
2. Langkah kedua
3. Langkah ketiga

Link

[Teks link](https://example.com)
[Link internal](/blog/artikel-lain)
[Link dengan title](https://example.com "Hover title")

Gambar

![Alt text](./gambar.png)
![Alt text](/images/gambar.jpg)

Blockquote

> Ini adalah kutipan.
> Bisa multi-line.
>
> > Nested quote juga bisa.

Ini adalah contoh blockquote yang sudah di-render.

Code

Gunakan `npm install` untuk instalasi.

Hasil: Gunakan npm install untuk instalasi.

```javascript
const greeting = 'Hello World';
console.log(greeting);
```

Tabel

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Hasil:

Horizontal Rule

---

Fitur MDX: Komponen

Ini yang membedakan MDX dari Markdown biasa — kemampuan menggunakan komponen.

Import Komponen

Di awal file (setelah frontmatter), import komponen yang akan digunakan:

---
title: "Judul Artikel"
# frontmatter lainnya...
---

import InfoBox from '@/components/mdx/InfoBox.astro';
import Terminal from '@/components/mdx/Terminal.astro';
import Steps from '@/components/mdx/Steps.astro';
import Step from '@/components/mdx/Step.astro';

Konten artikel dimulai di sini...

Menggunakan Komponen

Setelah diimport, gunakan komponen dengan syntax JSX:

<InfoBox type="tip" title="Tips Penting">
Ini adalah isi dari info box.
</InfoBox>

Komponen dengan Children

Beberapa komponen menerima konten di dalamnya:

<Accordion title="Klik untuk expand">
Ini adalah konten yang tersembunyi.
Bisa berisi **markdown** juga.
</Accordion>

Props Komponen

Komponen menerima props (parameter):

<InfoBox 
  type="warning" 
  title="Peringatan"
>
  Hati-hati dengan langkah ini!
</InfoBox>

<Terminal
  title="Install dependencies"
  content="npm install"
/>

Komponen Populer di Sitemas

import InfoBox from '@/components/mdx/InfoBox.astro';

<InfoBox type="note" title="Catatan">
  Informasi tambahan...
</InfoBox>

<InfoBox type="tip" title="Tips">
  Tips berguna...
</InfoBox>

<InfoBox type="warning" title="Peringatan">
  Hati-hati dengan...
</InfoBox>

<InfoBox type="danger" title="Bahaya">
  Jangan lakukan ini...
</InfoBox>

import Terminal from '@/components/mdx/Terminal.astro';

<Terminal
  title="Install Node.js"
  content="brew install node"
/>

import CodeBlock from '@/components/mdx/CodeBlock.astro';

<CodeBlock title="app.js" lang="javascript">
// kode JavaScript Anda di sini
const express = require('express');
const app = express();
</CodeBlock>

import Steps from '@/components/mdx/Steps.astro';
import Step from '@/components/mdx/Step.astro';

<Steps>
  <Step title="Langkah Pertama">
    Penjelasan langkah pertama...
  </Step>
  <Step title="Langkah Kedua">
    Penjelasan langkah kedua...
  </Step>
</Steps>

Markdown di Dalam Komponen

Anda bisa menggunakan Markdown di dalam komponen:

<InfoBox type="tip" title="Tips">

Ini adalah list di dalam InfoBox:

- Item pertama dengan **bold**
- Item kedua dengan `code`
- Item ketiga dengan [link](/blog)

</InfoBox>

Escape Characters

Untuk menampilkan karakter spesial secara literal:

\*Ini bukan italic\*
\# Ini bukan heading
\[Ini bukan link\]

Tips Produktivitas

1. Snippet di VS Code

Buat snippet untuk komponen yang sering digunakan. Di VS Code: Ctrl+Shift+P → “Snippets” → “MDX”.

2. Preview Sampingan

VS Code mendukung preview Markdown. Tekan Ctrl+Shift+V atau klik icon preview.

3. Auto-complete Import

Jika menggunakan ekstensi MDX, import akan auto-complete.

4. Copy dari Template

Sitemas menyediakan template di src/templates/. Copy dan modifikasi.

Kesalahan Umum

1. Lupa Baris Kosong

MDX memerlukan baris kosong di sekitar komponen:

Teks sebelum
<InfoBox type="tip">
Konten
</InfoBox>
Teks sesudah

Teks sebelum

<InfoBox type="tip">
Konten
</InfoBox>

Teks sesudah

2. Self-closing Tag Salah

Komponen tanpa children harus self-closing:

<!-- ❌ Salah -->
<Terminal title="Test" content="echo hello"></Terminal>

<!-- ✅ Benar -->
<Terminal title="Test" content="echo hello" />

3. Lupa Import

Setiap komponen yang digunakan harus diimport terlebih dahulu.

4. String dengan Quotes

Jika props berisi quote, gunakan escape atau kombinasi:

<!-- ✅ Gunakan quote berbeda -->
<Terminal content='echo "Hello World"' />

<!-- ✅ Atau escape -->
<Terminal content="echo \"Hello World\"" />

Referensi Cepat

Langkah Selanjutnya

Sekarang Anda menguasai MDX! Pelajari cara mengelola kategori dan tag:

Kesimpulan

MDX memberikan kebebasan menulis yang luar biasa — dari artikel sederhana dengan Markdown murni hingga konten interaktif dengan komponen kustom.

Kuncinya adalah:

1. Kuasai Markdown dasar terlebih dahulu
2. Pelajari komponen yang tersedia
3. Praktik dengan menulis artikel
4. Eksperimen dengan kombinasi komponen

Semakin sering Anda menulis, semakin natural MDX terasa. Selamat menulis!