Menulis dan memelihara dokumentasi Wazapin

Panduan ini untuk kontributor yang menambah atau memperbarui dokumentasi Wazapin. Situs docs adalah proyek Astro berbasis Nimbus: konten dimiliki di repository ini, dan build memvalidasi tag MDX serta tautan internal sebelum di-deploy.

Pilih bentuk halaman lebih dulu

Mulai dari pertanyaan pembaca, bukan dari komponen yang ingin kamu pakai:

Jangan membuat tipe halaman baru jika bentuk yang ada sudah cocok. Buat judul yang menjawab pertanyaan terlebih dahulu, dan paragraf pertama harus menjelaskan hasil akhirnya.

Kontrak tiap tipe konten

• Quickstart: pilihkan default untuk pembaca, tampilkan hasil yang diharapkan, jelaskan yang baru terjadi, lalu tutup dengan satu aksi berikutnya.
• Tutorial: ajarkan satu proyek end-to-end yang bermakna; tiap bagian harus meninggalkan hasil yang bisa dilihat. Opsi lengkap masuk ke referensi.
• How-to: selesaikan satu tugas spesifik dan tambahkan verifikasi sebelum aksi yang sulit dibatalkan.
• Concept: mulai dari definisi, jelaskan alasan perilakunya, lalu tutup dengan batasan dan konsep terkait.
• Reference: jawab pertanyaan nilai atau field secara lengkap atau nyatakan cakupannya dengan jelas.
• Example: berikan contoh lengkap yang bisa dijalankan, prasyarat, dan hasil yang diharapkan.
• Troubleshooting: gunakan gejala atau error sebagai judul, lalu berikan diagnosis dan langkah pemulihan paling singkat.
• Changelog: kelompokkan perubahan yang terlihat pengguna berdasarkan versi pra-rilis, tandai breaking change, dan jelaskan migrasinya. Jangan menyalin dump commit mentah.

Kontrak ini adalah checklist review, bukan build gate. Pilih tipe halaman dari pertanyaan pembaca sebelum memilih komponen.

Struktur proyek

 docs/
 ├── astro.config.ts           # URL situs, sidebar, redirect, aturan build
 ├── nimbus.json               # Provenance komponen yang dikelola CLI
 └── src/
     ├── components.ts         # Registry global MDX
     ├── components/ui/        # Komponen Nimbus milik proyek ini
     ├── content/docs/         # Halaman Inggris; direktori menjadi path URL
     ├── content/docs-id/      # Halaman Indonesia di bawah /id/
     ├── content/partials/     # Cuplikan MDX yang dipakai ulang
     ├── layouts/              # BaseLayout dan DocsLayout
     └── styles/               # Token tema dan gaya prosa

Halaman di src/content/docs/guides/example.mdx menjadi /guides/example. Tambahkan file ke sidebar hanya ketika sudah siap dibaca; build akan mendeteksi referensi sidebar yang tidak terpecahkan.

Menulis Markdown dan MDX

Setiap halaman butuh frontmatter minimal title. Buat deskripsi singkat karena dipakai di metadata halaman dan header:

---
title: "Menangani pembaruan status pengiriman"
description: "Memproses transisi terkirim, terkirim-diterima, dibaca, dan gagal dari webhook."
---

Jelaskan hasil akhirnya terlebih dahulu.

## Langkah berikutnya

Tautkan ke aksi berikutnya dengan label yang deskriptif.

Komponen MDX tersedia tanpa import hanya jika didaftarkan di src/components.ts. Registry saat ini mencakup Aside, CardGrid, LinkCard, Accordion, Steps, Tabs, dan primitif Nimbus bersama lainnya. Tag PascalCase yang tidak dikenal akan gagal pada validasi pra-build Nimbus; jangan mem-bypass pemeriksaan itu dengan menulis pendekatan HTML kustom.

Untuk kartu navigasi, pakai komponen resmi LinkCard:

<LinkCard
  title="Kirim pesan pertamamu"
  description="Ikuti quickstart dari API key hingga request yang berhasil."
  href="/id/getting-started/quickstart"
/>

Pakai Card hanya untuk konten non-tautan. Pakai CardGrid agar jarak kartu dan kolom responsif tetap konsisten.

Memakai ulang konten bersama

Panduan yang berulang sebaiknya disimpan di src/content/partials/. Render partial alih-alih mengimpor halaman MDX secara langsung:

<Render file="authentication" />

Pakai partial ketika paragraf, daftar prasyarat, atau peringatan yang sama harus identik di banyak halaman. Jangan mengekstrak konten hanya untuk memendekkan satu file, dan jangan menyembunyikan instruksi khusus halaman di dalam cuplikan generik.

Layout dan banner

Halaman dokumentasi normal memakai DocsLayout secara otomatis. Pakai frontmatter hanya ketika halaman benar-benar butuh bentuk berbeda:

---
title: "Tabel referensi yang lebar"
sidebar: false
tableOfContents: false
---

Pakai banner untuk pengumuman rilis, migrasi, deprecation, atau ketersediaan sementara yang nyata — bukan sebagai dekorasi:

---
title: "Endpoint lama"
banner:
  content: "Endpoint ini sudah deprecated. Gunakan API messages sebagai gantinya."
  type: caution
  dismissible:
    id: legacy-endpoint-v1
    days: 14
---

Jaga ID banner tetap stabil selama pemberitahuannya sama. Ganti ID hanya ketika maknanya berubah dan pembaca harus melihatnya lagi.

Menambahkan komponen Nimbus dengan aman

Pakai registry resmi agar dependensi dan provenance tetap benar:

npx @cloudflare/nimbus-docs list --type ui
npx @cloudflare/nimbus-docs add <component>

Tinjau file hasil generate dan entri nimbus.json sebelum memakai komponen. Lalu daftarkan di src/components.ts jika akan dipakai dari MDX. Pasang komponen karena halaman nyata membutuhkannya — misalnya LinkCard untuk navigasi atau Accordion untuk bagian status/error yang panjang — bukan sekadar karena ada di katalog Nimbus.

Verifikasi sebelum publish

Jalankan perintah ini dari docs/:

npm run lint:docs
npm run build

Lint harus nol error. Warning yang ada sebaiknya ditinjau tetapi tidak disembunyikan. Build harus selesai dengan validasi MDX dan pembuatan route statis. Untuk perubahan visual, buka preview hasil build dan periksa halaman aktual pada lebar desktop dan mobile, termasuk fokus keyboard untuk tautan, grup sidebar, dan kontrol disclosure.