Menambahkan atau Memperbarui Plugin

Panduan ini menjelaskan cara menambahkan plugin Capacitor baru ke situs web Capgo atau memperbarui dokumentasi plugin yang sudah ada. Ini berguna bagi kontributor, maintainer, dan AI agent yang membantu pemeliharaan dokumentasi.

Ikhtisar

Saat menambahkan plugin baru ke ekosistem Capgo, Anda perlu memperbarui beberapa file dan lokasi di seluruh situs web agar plugin muncul dengan benar di semua tempat yang relevan:

1. Konfigurasi Daftar Plugin - Tambahkan metadata plugin ke master list
2. Halaman Indeks Plugin - Tambahkan plugin ke halaman daftar plugin berdasarkan kategori
3. Navigasi Sidebar - Tambahkan plugin ke sidebar dokumentasi
4. Dokumentasi Plugin - Buat halaman overview dan getting-started
5. Tutorial Plugin - Buat tutorial yang komprehensif

Lokasi File

File Utama yang Perlu Diperbarui

File	Tujuan
/src/config/plugins.ts	Master plugin list dengan metadata
/src/content/docs/docs/plugins/index.mdx	Halaman indeks plugin dengan kategori
/astro.config.mjs	Konfigurasi navigasi sidebar
/src/content/docs/docs/plugins/[plugin-name]/	Direktori dokumentasi plugin
/src/content/plugins-tutorials/en/	File tutorial bahasa Inggris

Panduan Langkah demi Langkah

1. Tambahkan Plugin ke Daftar Master

   Buka /src/config/plugins.ts dan tambahkan plugin Anda ke actions array:

   // First, import an appropriate Heroicon
   import YourIconName from 'astro-heroicons/mini/IconName.astro'
   
   // Then add to the actions array
   {
     name: '@capgo/your-plugin-name',
     author: 'github.com/Cap-go',
     description: 'Brief description of what the plugin does',
     href: 'https://github.com/Cap-go/your-plugin-name/',
     title: 'Display Name',
     icon: YourIconName,
   }

   Ikon yang Tersedia: Periksa /node_modules/astro-heroicons/mini/ untuk ikon yang tersedia.

2. Tambahkan Plugin ke Halaman Index

   Buka /src/content/docs/docs/plugins/index.mdx dan tambahkan plugin Anda di bawah kategori yang sesuai:

   <LinkCard
     title="Your Plugin Name"
     description="Brief description of what the plugin does"
     href="/docs/plugins/your-plugin-name/"
   />

   Kategori:

   • ⭐ Plugin Unggulan
   • 📱 Plugin Perangkat & Sistem
   • 🎥 Plugin Media & Kamera
   • 🛠️ Plugin Utilitas
   • 🤖 AI & Media Lanjutan
   • 📍 Lokasi & Layanan Background
   • 📞 Komunikasi & Analytics
   • 🔐 Keamanan & Sistem
   • 📊 Fitur Khusus Android
   • 📥 Download & Navigasi

3. Tambahkan ke Navigasi Sidebar

   Buka /astro.config.mjs dan tambahkan plugin Anda ke konfigurasi sidebar (sekitar baris 540):

   {
     label: 'Your Plugin Name',
     items: [
       { label: 'Overview', link: '/docs/plugins/your-plugin-name/' },
       { label: 'Getting started', link: '/docs/plugins/your-plugin-name/getting-started' },
     ],
     collapsed: true,
   }

   Plugin disusun secara alfabetis di sidebar.

4. Buat Direktori Dokumentasi Plugin

   Buat direktori baru untuk dokumentasi plugin Anda:

   mkdir -p /src/content/docs/docs/plugins/your-plugin-name/

5. Buat Halaman Overview Plugin

   Buat /src/content/docs/docs/plugins/your-plugin-name/index.mdx:

   ---
   title: "@capgo/your-plugin-name"
   description: Brief description of the plugin's purpose
   tableOfContents: false
   next: false
   prev: false
   sidebar:
     order: 1
     label: "Introduction"
   hero:
     tagline: Detailed tagline explaining what the plugin does
     image:
       file: ~public/your-plugin-icon.svg
     actions:
       - text: Get started
         link: /docs/plugins/your-plugin-name/getting-started/
         icon: right-arrow
         variant: primary
       - text: Github
         link: https://github.com/Cap-go/your-plugin-name/
         icon: external
         variant: minimal
   ---
   
   import { Card, CardGrid } from '@astrojs/starlight/components';
   
   <CardGrid stagger>
     <Card title="Feature 1" icon="puzzle">
       Description of first key feature
     </Card>
     <Card title="Feature 2" icon="rocket">
       Description of second key feature
     </Card>
     <Card title="Cross-platform" icon="puzzle">
       Works on both iOS and Android 📱
     </Card>
     <Card title="Comprehensive Documentation" icon="open-book">
       Check the [Documentation](/docs/plugins/your-plugin-name/getting-started/) to master the plugin.
     </Card>
   </CardGrid>

6. Buat Panduan Getting Started

   Buat /src/content/docs/docs/plugins/your-plugin-name/getting-started.mdx:

   ---
   title: Getting Started
   description: Learn how to install and use the plugin in your Capacitor app.
   sidebar:
     order: 2
   ---
   
   import { Steps } from '@astrojs/starlight/components';
   import { PackageManagers } from 'starlight-package-managers'
   
   <Steps>
   1. **Install the package**
      <PackageManagers pkg="@capgo/your-plugin-name" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
   
   2. **Sync with native projects**
      <PackageManagers type="exec" pkg="cap" args="sync" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
   </Steps>
   
   ## Configuration
   
   ### iOS Configuration
   [iOS-specific setup instructions]
   
   ### Android Configuration
   [Android-specific setup instructions]
   
   ## Usage
   
   [Basic usage examples]
   
   ## API Reference
   
   [Detailed API documentation]
   
   ## Complete Example
   
   [Full working example]
   
   ## Best Practices
   
   [Recommended practices and tips]
   
   ## Platform Notes
   
   [Platform-specific notes and limitations]

7. Buat File Tutorial

   Buat /src/content/plugins-tutorials/en/your-plugin-name.md:

   ---
   locale: en
   ---
   # Using @capgo/your-plugin-name Package
   
   The `@capgo/your-plugin-name` package [brief description]. In this tutorial, we will guide you through the installation, configuration, and usage of this package in your Ionic Capacitor app.
   
   ## Installation
   
   [Installation steps]
   
   ## Configuration
   
   [Configuration steps for iOS and Android]
   
   ## API Usage
   
   [Detailed API usage examples]
   
   ## Complete Example
   
   [Full working example]
   
   ## Best Practices
   
   [Tips and best practices]
   
   ## Troubleshooting
   
   [Common issues and solutions]
   
   ## Conclusion
   
   [Summary and links to additional resources]

Struktur Dokumentasi Plugin

File yang Wajib Ada

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx           # Overview page with hero and feature cards
└── getting-started.mdx # Installation and usage guide

src/content/plugins-tutorials/en/
└── your-plugin-name.md # Comprehensive tutorial

File Opsional

Untuk plugin yang kompleks, Anda dapat menambahkan halaman dokumentasi tambahan:

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx
├── getting-started.mdx
├── api-reference.mdx   # Detailed API documentation
├── examples.mdx        # Additional examples
├── troubleshooting.mdx # Troubleshooting guide
└── migrations.mdx      # Migration guides

Panduan Konten

Menulis Deskripsi Plugin

• Singkat dan Padat: Jaga deskripsi di bawah 100 karakter
• Jadilah Spesifik: Jelaskan fungsi plugin, bukan sekadar definisinya
• Gunakan Kata Kerja: Mulai dengan kata kerja seperti “Control”, “Integrate”, atau “Enable”

Contoh yang Baik:

• “Kontrol senter perangkat dengan toggle on/off sederhana”
• “Integrasikan live chat Crisp dan customer support ke dalam aplikasi Anda”
• “Aktifkan autentikasi aman menggunakan Face ID dan Touch ID”

Contoh Buruk:

• “Plugin untuk flash”
• “Ini adalah plugin Crisp”
• “Plugin biometrik”

Menulis Dokumentasi

1. Mulai dengan Instalasi: Selalu mulai dengan langkah instalasi yang jelas
2. Sediakan Konfigurasi: Sertakan persyaratan setup spesifik platform
3. Tampilkan Contoh Penggunaan: Berikan contoh code yang berfungsi
4. Sertakan Referensi API: Dokumentasikan semua method dan parameter
5. Tambahkan Contoh Lengkap: Tampilkan pola penggunaan dunia nyata
6. Daftar Best Practices: Bagikan tips untuk penggunaan optimal
7. Dokumentasikan Perbedaan Platform: Jelaskan perbedaan perilaku iOS vs Android
8. Tambahkan Troubleshooting: Atasi masalah umum

Contoh Code

• Gunakan TypeScript untuk semua contoh code
• Sertakan import di bagian atas
• Add comments explaining key steps
• Tunjukkan penanganan error
• Demonstrasikan penggunaan dasar dan tingkat lanjut

Checklist

Gunakan checklist ini saat menambah plugin baru:

• Menambahkan plugin ke /src/config/plugins.ts
• Memilih ikon yang sesuai dari Heroicons
• Menambahkan plugin ke /src/content/docs/docs/plugins/index.mdx di bawah kategori yang benar
• Menambahkan entri sidebar di /astro.config.mjs
• Membuat direktori dokumentasi plugin
• Membuat index.mdx halaman ringkasan
• Membuat getting-started.mdx panduan
• Membuat tutorial di /src/content/plugins-tutorials/en/
• Menyertakan instruksi instalasi
• Mendokumentasikan konfigurasi iOS
• Konfigurasi Android terdokumentasi
• Contoh penggunaan tersedia
• Menambahkan referensi API
• Menyertakan contoh kerja lengkap
• Daftar best practices
• Menambahkan catatan spesifik platform
• Semua link sudah dites

Referensi Ikon

Ikon umum untuk plugin (dari astro-heroicons/mini/):

Ikon	Kasus Penggunaan
BoltIcon	Flash, daya, energi
CameraIcon	Kamera, foto, video
ChatBubbleLeftIcon	Chat, pesan, komunikasi
FingerPrintIcon	Biometrik, keamanan, autentikasi
MapPinIcon	Lokasi, geolokasi, peta
SpeakerWaveIcon	Audio, suara, musik
VideoCameraIcon	Video, rekaman, streaming
CreditCardIcon	Pembayaran, pembelian
PlayCircleIcon	Media player, video player
SignalIcon	Konektivitas, jaringan, beacon
RadioIcon	Beacon, broadcast, nirkabel
ChatBubbleOvalLeftIcon	Media sosial, WeChat

Update Plugin yang Sudah Ada

Saat memperbarui plugin yang sudah ada:

1. Perbarui nomor versi di dokumentasi
2. Tambahkan panduan migrasi jika ada breaking changes
3. Perbarui referensi API dengan metode baru
4. Tambahkan contoh baru untuk fitur baru
5. Perbarui persyaratan platform jika ada perubahan
6. Revisi best practices berdasarkan fitur baru
7. Pastikan tutorial tetap mutakhir dengan API terbaru

Path Bahasa

Tulis dan tinjau dokumentasi plugin dalam bahasa Inggris. Path yang dilokalkan dibuat oleh metadata situs dan diterjemahkan di edge oleh translation Worker.

Menguji Perubahan Anda

Setelah menambahkan atau memperbarui dokumentasi plugin:

1. Build situs secara lokal:

   bun run build

2. Periksa kesalahan:

   • Pastikan semua link berfungsi
   • Pastikan gambar muncul dengan benar
   • Pastikan contoh code valid
   • Navigasi tes berfungsi

3. Preview situs:

   bun run dev

4. Verifikasi plugin Anda muncul:

   • Cek halaman daftar plugin
   • Verifikasi navigasi sidebar
   • Tes semua halaman dokumentasi
   • Pastikan halaman tutorial berfungsi

Kesalahan Umum

Peringatan

Hindari kesalahan umum berikut:

1. Lupa melakukan sync: Selalu jalankan bunx cap sync di dalam contoh
2. Penamaan tidak konsisten: Gunakan nama plugin yang sama di mana saja
3. Konfigurasi platform tidak lengkap: Dokumentasikan setup iOS dan Android
4. Link rusak: Gunakan link relatif dan pastikan berfungsi
5. Tidak ada error handling: Selalu sertakan try-catch di dalam contoh code
6. Import tidak lengkap: Sertakan semua import yang diperlukan di contoh code
7. Deskripsi tidak jelas: Jelaskan secara spesifik fungsi plugin tersebut

Butuh bantuan

Jika Anda butuh bantuan saat menambah atau memperbarui dokumentasi plugin:

• Discord: Bergabunglah di komunitas Discord kami
• GitHub: Open an issue on the repositori website
• Email: Hubungi tim di support@capgo.app

Contoh

Sebagai referensi, cek plugin-plugin dengan dokumentasi lengkap berikut:

• Updater: /src/content/docs/docs/plugins/updater/ (plugin kompleks dengan banyak halaman)
• Flash: /src/content/docs/docs/plugins/flash/ (plugin sederhana, contoh awal yang bagus)
• Social Login: /src/content/docs/docs/plugins/social-login/ (plugin dengan sub-halaman)

Ringkasan

Menambahkan plugin ke dokumentasi Capgo meliputi:

1. Menambahkan metadata ke konfigurasi utama
2. Menambahkan plugin ke halaman indeks berkategori
3. Konfigurasi navigasi sidebar
4. Membuat halaman dokumentasi yang lengkap
5. Menulis tutorial yang mendetail
6. Menguji semua perubahan secara lokal

Dengan mengikuti panduan ini, Anda memastikan plugin terdokumentasi secara konsisten dan mudah ditemukan oleh pengguna.

Lanjutkan dari Menambahkan atau Memperbarui Plugin

Jika Anda menggunakan Menambahkan atau Memperbarui Plugin untuk merencanakan pekerjaan plugin native, hubungkan dengan Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Alternatif Plugin Ionic Enterprise untuk workflow produk di Alternatif Plugin Ionic Enterprise, Capgo Native Build untuk alur kerja produk di Capgo Native Builds, dan Plugin Capacitor: Hal yang Perlu Anda Ketahui untuk konteks praktis di Capacitor Plugins: Yang Perlu Anda Ketahui.