Aggiunta o aggiornamento dei plugin

Questa guida spiega come aggiungere nuovi plugin Capacitor al sito Capgo o come aggiornare la documentazione dei plugin esistenti. È utile per contributor, maintainer e agenti AI che aiutano a gestire la documentazione.

Panoramica

Quando aggiungi un nuovo plugin all'ecosistema Capgo, devi aggiornare diversi file e posizioni nel sito per assicurarti che il plugin appaia correttamente in tutti i punti rilevanti:

1. Configurazione dell'elenco plugin - Aggiungi i metadati del plugin all'elenco principale
2. Pagina indice dei plugin - Aggiungi il plugin alla pagina dell'elenco plugin per categoria
3. Navigazione della sidebar - Aggiungi il plugin alla sidebar della documentazione
4. Documentazione dei plugin - Crea le pagine di panoramica e di onboarding
5. Tutorial del Plugin - Crea un tutorial completo

Posizione dei file

File principali da aggiornare

File	Scopo
/src/config/plugins.ts	Lista master dei plugin con metadati
/src/content/docs/docs/plugins/index.mdx	Pagina indice dei plugin con categorie
/astro.config.mjs	Configurazione della sidebar
/src/content/docs/docs/plugins/[plugin-name]/	Directory della documentazione plugin
/src/content/plugins-tutorials/en/	File tutorial in inglese

Guida passo dopo passo

1. Aggiungi il plugin alla Master List

   Apri /src/config/plugins.ts e aggiungi il tuo plugin all' 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,
   }

   Icone disponibili: Controlla /node_modules/astro-heroicons/mini/ per le icone disponibili.

2. Aggiungi il plugin alla pagina Index

   Apri /src/content/docs/docs/plugins/index.mdx e aggiungi il tuo plugin nella categoria corretta:

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

   Categorie:

   • ⭐ Plugin in evidenza
   • 📱 Plugin Device & System
   • 🎥 Plugin Media & Camera
   • 🛠️ Plugin Utility
   • 🤖 AI & Media Avanzati
   • 📍 Posizione e servizi in background
   • 📞 Comunicazione e analytics
   • 🔐 Sicurezza e sistema
   • 📊 Funzionalità specifiche per Android
   • 📥 Download e navigazione

3. Aggiungi alla navigazione laterale

   Apri /astro.config.mjs e aggiungi il tuo plugin alla configurazione della sidebar (intorno alla riga 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,
   }

   I plugin sono elencati in ordine alfabetico nella sidebar.

4. Crea la directory di documentazione del plugin

   Crea una nuova directory per la documentazione del tuo plugin:

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

5. Crea la pagina di panoramica del plugin

   Crea /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. Crea la guida per iniziare

   Crea /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. Crea il file del tutorial

   Crea /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]

Struttura della documentazione del plugin

File richiesti

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 opzionali

Per i plugin più complessi, puoi aggiungere altre pagine di documentazione:

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

Linee guida sui contenuti

Scrivere le descrizioni dei plugin

• Sii conciso: Mantieni le descrizioni sotto i 100 caratteri
• Sii specifico: Spiega cosa fa il plugin, non cos'è
• Usa verbi d'azione: Inizia con verbi come “Controlla”, “Integra”, “Abilita”

Esempi validi:

• “Controlla il flash del dispositivo con un semplice interruttore on/off”
• “Integra la live chat di Crisp e il customer support nella tua app”
• “Abilita l'autenticazione sicura tramite Face ID e Touch ID”

Esempi errati:

• “Un plugin per il flash”
• “Questo è un plugin Crisp”
• “Plugin biometrico”

Scrittura della documentazione

1. Inizia con l'installazione: Inizia sempre con passaggi di installazione chiari
2. Fornisci la configurazione: Includi i requisiti di configurazione per ogni piattaforma
3. Mostra esempi d'uso: Fornisci esempi code funzionanti
4. Includi il riferimento API: Documenta tutti i metodi e i parametri
5. Aggiungi esempi completi: Mostra pattern d'uso reali
6. Elenca le Best Practices: Condividi consigli per un uso ottimale
7. Documenta le differenze tra piattaforme: Chiarisci il comportamento tra iOS e Android
8. Aggiungi Troubleshooting: Risolvi i problemi comuni

Esempi Code

• Usa TypeScript per tutti gli esempi code
• Includi gli import in alto
• Aggiungi commenti per i passaggi chiave
• Mostra la gestione degli errori
• Dimostra l'uso base e avanzato

Checklist

Usa questa checklist quando aggiungi un nuovo plugin:

• Plugin aggiunto a /src/config/plugins.ts
• Icona appropriata scelta da Heroicons
• Plugin aggiunto a /src/content/docs/docs/plugins/index.mdx nella categoria corretta
• Aggiunta voce nella sidebar in /astro.config.mjs
• Creato directory per la documentazione del plugin
• Creata index.mdx pagina di overview
• Creata getting-started.mdx guida
• Creato tutorial in /src/content/plugins-tutorials/en/
• Inserite istruzioni di installazione
• Documentata la configurazione iOS
• Configurazione Android documentata
• Esempi d'uso forniti
• Aggiunta del riferimento a API
• Esempio completo e funzionante incluso
• Elenco delle best practice
• Note specifiche per piattaforma aggiunte
• Verifica che tutti i link funzionino

Riferimento icone

Icone comuni usate per i plugin (da astro-heroicons/mini/):

Icona	Caso d'uso
BoltIcon	Flash, alimentazione, energia
CameraIcon	Fotocamera, foto, video
ChatBubbleLeftIcon	Chat, messaggistica, comunicazione
FingerPrintIcon	Biometria, sicurezza, autenticazione
MapPinIcon	Posizione, geolocalizzazione, mappe
SpeakerWaveIcon	Audio, suono, musica
VideoCameraIcon	Video, registrazione, streaming
CreditCardIcon	Pagamenti, acquisti
PlayCircleIcon	Media player, video player
SignalIcon	Connettività, rete, beacon
RadioIcon	Beacon, broadcast, wireless
ChatBubbleOvalLeftIcon	Social media, WeChat

Aggiornare i plugin esistenti

Quando aggiorni un plugin esistente:

1. Aggiorna i numeri di versione nella documentazione
2. Aggiungi guide di migrazione se ci sono breaking changes
3. Aggiorna il riferimento a API con i nuovi metodi
4. Aggiungi nuovi esempi per le nuove feature
5. Aggiorna i requisiti della piattaforma se modificato
6. Revisionare le best practice in base alle nuove feature
7. Mantenere i tutorial aggiornati con l'ultima versione di API

Percorsi delle lingue

Scrivi e revisiona la documentazione dei plugin in inglese. I percorsi localizzati vengono generati dai metadati del sito e tradotti all'edge dal translation Worker.

Testare le modifiche

Dopo aver aggiunto o aggiornato la documentazione del plugin:

1. Buildare il sito localmente:

   bun run build

2. Controlla eventuali errori:

   • Verifica che i link funzionino
   • Assicurati che le immagini carichino
   • Conferma la validità degli esempi code
   • Testa la navigazione

3. Anteprima il sito:

   bun run dev

4. Verifica che il tuo plugin appaia:

   • Controlla la pagina dell'elenco plugin
   • Verifica la navigazione laterale
   • Testa tutte le pagine della documentazione
   • Conferma il funzionamento della pagina tutorial

Errori comuni

Attenzione

Evita questi errori comuni:

1. Dimenticare il sync: Esegui sempre bunx cap sync negli esempi
2. Naming inconsistente: Usa lo stesso nome del plugin ovunque
3. Configurazione piattaforma mancante: Documenta il setup sia per iOS che per Android
4. Link interrotti: Usa link relativi e verifica che funzionino
5. Nessuna gestione degli errori: Mostra sempre try-catch negli esempi
6. Import mancanti: Includi tutti gli import necessari negli esempi
7. Descrizioni poco chiare: Sii specifico su cosa fa il plugin

Ottenere aiuto

Se hai bisogno di aiuto per aggiungere o aggiornare la documentazione dei plugin:

• Discord: Unisciti a noi community Discord
• GitHub: Apri un'issue su repository del sito
• Email: Contatta il team su support@capgo.app

Esempi

Per riferimento, consulta questi plugin ben documentati:

• Updater: /src/content/docs/docs/plugins/updater/ (plugin complesso con più pagine)
• Flash: /src/content/docs/docs/plugins/flash/ (plugin semplice, ottimo esempio per iniziare)
• Social Login: /src/content/docs/docs/plugins/social-login/ (plugin con sottopagine)

Riassunto

Aggiungere un plugin alla documentazione di Capgo comporta:

1. Aggiungere i metadati alla configurazione principale
2. Aggiunta del plugin alla pagina indice categorizzata
3. Configurazione della navigazione nella sidebar
4. Creazione di pagine di documentazione complete
5. Scrittura di un tutorial dettagliato
6. Test locale di tutte le modifiche

Seguendo questa guida, garantisci che i plugin siano documentati in modo coerente e facilmente individuabili dagli utenti.

Continua da Aggiunta o aggiornamento dei plugin

Se stai usando Aggiunta o aggiornamento dei plugin per pianificare il lavoro sui plugin nativi, collegalo a Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Alternative ai plugin Ionic Enterprise per il workflow del prodotto nelle alternative ai plugin Ionic Enterprise, Capgo Native Build per il workflow del prodotto in Capgo Native Builds, e Plugin Capacitor: cosa devi sapere per il contesto pratico in Plugin Capacitor: cosa devi sapere.