Aggiungere o aggiornare plugin

Questa guida spiega come aggiungere nuovi Capacitor plugin al sito Capgo o aggiornare la documentazione esistente di un plugin. Ciò è utile per i contributori, i mantenitori e gli agenti AI che aiutano a mantenere la documentazione.

Panoramica

Quando si aggiunge un nuovo plugin all'ecosistema Capgo, è necessario aggiornare diversi file e posizioni sul sito per assicurarsi che il plugin apparisca correttamente in tutti i luoghi pertinenti:

1. Configurazione della Lista dei Plugin - Aggiungi metadati del plugin alla lista principale
2. Pagina Indice dei Plugin - Aggiungi il plugin alla pagina di elenco dei plugin categorizzati
3. Navigazione del Lato - Aggiungi il plugin alla navigazione del lato della documentazione
4. Documentazione dei Plugin - Crea una panoramica e pagine di avvio
5. Tutorial del plugin - Crea un tutorial esaustivo

Posizioni dei file

File chiave da aggiornare

File	Scopo
/src/config/plugins.ts	Elenco completo dei plugin con metadati
/src/content/docs/docs/plugins/index.mdx	Pagina di indice dei plugin con categorie
/astro.config.mjs	Configurazione della navigazione del lato di navigazione
/src/content/docs/docs/plugins/[plugin-name]/	Directory dei documenti del plugin
/src/content/plugins-tutorials/en/	File di tutorial in inglese

Guida Passo Dopo Passo

1. Aggiungi Plugin alla Lista Principale

   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 icona disponibile.

2. Aggiungi Plugin alla Pagina di Indice

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

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

   Categorie:

   • ⭐ Plugin più Popolari
   • 📱 Plugin per Dispositivi e Sistema
   • 🎥 Plugin per Media e Camera
   • 🛠️ Plugin di Utilità
   • 🤖 Plugin AI e Media Avanzati
   • 📍 Posizione e Servizi di Background
   • 📞 Comunicazione e Analisi
   • 🔐 Sicurezza e Sistema
   • 📊 Caratteristiche Specifiche per Android
   • 📥 Download e Navigazione

3. Aggiungi alla Navigazione del Lato

   Apre /astro.config.mjs e aggiungi il tuo plugin alla configurazione della barra laterale (circa linea 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 barra laterale.

4. Crea Directory Documentazione 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 l'avvio

   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 File di 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 Facoltativi

Per i plugin complessi, potresti aggiungere pagine di documentazione aggiuntive:

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 del contenuto

Scrivere descrizioni dei plugin

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

Esempi buoni:

• “Controlla il dispositivo con la semplice attivazione/spenta della torcia”
• “Integra il live chat di Crisp e il supporto ai clienti nel tuo app”
• “Abilita l'autenticazione sicura utilizzando Face ID e Touch ID”

Esempi Cattivi:

• “Un plugin per la flash”
• “Questo è un plugin di Crisp”
• Plugin Biometrico

Scrivere la Documentazione

1. Inizia sempre con passaggi di installazione chiariFornisci la Configurazione
2. Esempi Cattivi: Includere requisiti di configurazione specifici per piattaforma
3. Mostra Esempi di Utilizzo: Fornisci esempi di lavoro code funzionanti
4. Includi API Riferimento: Documenta tutti i metodi e i parametri
5. Aggiungi Esempi Completi: Mostra modelli di utilizzo real-world
6. Elenco le Migliori Pratiche: Condividi consigli per un utilizzo ottimale
7. Documenta le Differenze di Piattaforma: Clarifica il comportamento iOS vs Android
8. Aggiungi la Risoluzione dei ProblemiRisolvere problemi comuni

Code Esempi

• Usare TypeScript per tutti gli code esempi
• Includere importazioni in alto
• Aggiungere commenti che spiegano i passaggi chiave
• Mostrare il trattamento degli errori
• Dimostrare sia l'uso base che avanzato

Elenco di controllo

Usare questo elenco di controllo quando si aggiunge un nuovo plugin:

• Aggiunto plugin a /src/config/plugins.ts
• Scegliuto l'icona appropriata da Heroicons
• Aggiunto plugin a /src/content/docs/docs/plugins/index.mdx sotto la categoria corretta
• Aggiunto voce di navigazione laterale in /astro.config.mjs
• Creati il directory di documentazione del plugin
• Creati index.mdx pagina di panoramica
• Creati getting-started.mdx guida
• Creato tutorial in /src/content/plugins-tutorials/en/
• Inclusi le istruzioni di installazione
• Documentato la configurazione di iOS
• Documentazione della configurazione Android
• Esempi di utilizzo forniti
• Aggiunto riferimento a API
• Esempio completo e funzionante incluso
• Elencate le migliori pratiche
• Aggiunte note specifiche per piattaforma
• Verificati tutti i collegamenti per garantire la correttezza

Riferimento alle icone

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

Icona	Utilizzo
BoltIcon	Luce, potenza, energia
CameraIcon	Camera, foto, video
ChatBubbleLeftIcon	Chat, messaggistica, comunicazione
FingerPrintIcon	Biometrico, sicurezza, autenticazione
MapPinIcon	Posizione, geolocalizzazione, mappe
SpeakerWaveIcon	Audio, suono, musica
VideoCameraIcon	Video, registrazione, streaming
CreditCardIcon	Pagamenti, acquisti
PlayCircleIcon	Lettori multimediali, lettori video
SignalIcon	Connettività, rete, beacon
RadioIcon	Beacon, broadcast, wireless
ChatBubbleOvalLeftIcon	Social media, WeChat

Aggiornamento dei Plugin Esistenti

Quando si aggiorna un plugin esistente:

1. Aggiorna i numeri di versione nella documentazione
2. Aggiungi guide di migrazione se esistono cambiamenti dirompenti
3. Aggiorna la API reference con nuove metodi
4. Aggiungi nuovi esempi per nuove funzionalità
5. Aggiorna le richieste del sistema se viene modificato
6. Rivedi le migliori pratiche basato su nuove funzionalità
7. Mantieni il tutorial aggiornato con le ultime API

Percorsi di lingua

Scrivi e revisiona le documentazioni dei plugin in inglese. I percorsi localizzati sono generati dai metadati del sito e tradotti all'edge dal Worker di traduzione.

Testa le tue modifiche

Dopo aver aggiunto o aggiornato la documentazione dei plugin:

1. Costruisci il sito localmente:

   bun run build

2. Verifica gli errori:

   • Verifica che tutti i collegamenti funzionino correttamente
   • Assicurati che le immagini si caricano correttamente
   • Conferma che gli esempi code sono validi
   • Testa la navigazione

3. Anteprima del sito:

   bun run dev

4. Verifica che il tuo plugin sia presente:

   • Verifica la pagina di elenco plugin
   • Verifica la navigazione del lato laterale
   • Testa tutte le pagine della documentazione
   • Conferma che la pagina del tutorial funziona

Percorsi comuni

Attenzione

Evita questi errori comuni:

1. Dimenticare di sincronizzare: Esegui sempre bunx cap sync in esempi
2. Nomi inconsistenti: Utilizza lo stesso nome del plugin in ogni luogo
3. Configurazione di piattaforma mancante: Documenta sia la configurazione di iOS che di Android
4. Collegamenti rotti: Utilizza collegamenti relativi e verifica che funzionino
5. Assenza di gestione degli errori: Mostra sempre il blocco try-catch negli esempi
6. Importazioni mancanti: Includi tutte le importazioni necessarie 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 del plugin:

• Discord: Unisciti alla nostra comunità di Discord
• GitHub: Apri un issue sul repository del sito web
• Email: Contattaci al supporto@capgo.app

Esempi

Per riferimento, controlla questi plugin ben documentati:

• Aggiornatore: /src/content/docs/docs/plugins/updater/ (plugin complesso con più pagine)
• Flash: /src/content/docs/docs/plugins/flash/ (plugin semplice, buon esempio di partenza)
• Login sociale: /src/content/docs/docs/plugins/social-login/ (plugin con sottopagine)

Riepilogo

Aggiungere un plugin alla documentazione Capgo comporta:

1. Aggiungere metadati alla configurazione principale
2. Aggiungere il plugin alla pagina di indice categorizzata
3. Configurare la navigazione del lato laterale
4. Creare pagine di documentazione esaustive
5. Scrivere un tutorial dettagliato
6. Testare tutte le modifiche localmente

Seguendo questa guida, si assicura che i plugin siano documentati in modo coerente e facilmente scopribili dagli utenti.