Aggiungere o Aggiornare Plugin

Questa guida spiega come aggiungere nuovi plugin Capacitor al sito web di Capgo o aggiornare la documentazione esistente dei 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 web per assicurarsi che il plugin apparisca correttamente in tutti i luoghi pertinenti:

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

Posizioni dei File

File Chiave da Aggiornare

File	Scopo
/src/config/plugins.ts	Elenco plugin principale con metadati
/src/content/docs/docs/plugins/index.mdx	Pagina di indice dei plugin con categorie
/astro.config.mjs	Configurazione della navigazione del lato
/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 all'elenco principale

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

   Iconici disponibili: Controlla /node_modules/astro-heroicons/mini/ per gli iconi disponibili.

2. Aggiungi Plugin alla Pagina di Indice

   Apre /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 principali
   • 📱 Plugin per dispositivi e sistema
   • 🎥 Plugin per media e fotocamera
   • 🛠️ Plugin di utilità
   • 🤖 Plugin AI e media avanzati
   • 📍 Plugin per ubicazione e servizi di background
   • 📞 Plugin di comunicazione e analisi
   • 🔐 Plugin di sicurezza e sistema
   • 📊 Caratteristiche specifiche per Android
   • 📥 Download e navigazione

3. Aggiungi alla navigazione laterale

   Apri /astro.config.mjs e aggiungi il tuo plugin alla configurazione del riquadro (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 nel riquadro.

4. Crea directory per la 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 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. Creare la Guida di Avvio

   Creare /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. Creare il File di Tutorial

   Creare /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 per il contenuto

Scrivere descrizioni dei plugin

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

Esempi Buoni:

• “Controlla il flash della fotocamera e della torcia con un semplice interruttore on/off”
• “Integra il servizio di chat live Crisp e il supporto ai clienti nel tuo app”
• “Abilita l'autenticazione sicura utilizzando Face ID e Touch ID”

Esempi Cattivi:

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

Scrivere la Documentazione

1. Inizia con l'Installazione: Inizia sempre con passaggi di installazione chiari
2. Fornisci Configurazione: Includi requisiti di configurazione specifici per piattaforma
3. Mostra Esempi di Utilizzo: Fornisci esempi di lavoro code
4. Include API Riferimento: Documenta tutti i metodi e i parametri
5. Aggiungi Esempi Completi: Mostra modelli di utilizzo realistici
6. Pratiche di Migliore Pratica: Condividi consigli per un utilizzo ottimale
7. Differenze tra le Piattaforme: Spiega il comportamento iOS vs Android
8. Aggiungi la Risoluzione dei Problemi: Affronta le questioni comuni

Code Esempi

• Usa TypeScript per tutti gli code esempi
• Includi le importazioni in alto
• Aggiungi commenti che spiegano i passaggi chiave
• Mostra il gestione degli errori
• Dimostrare entrambe le funzioni di base e avanzate

Elenco di controllo

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

• Aggiunto plugin a /src/config/plugins.ts
• Selezionato icona appropriata da Heroicons
• Aggiunto plugin a /src/content/docs/docs/plugins/index.mdx Sotto categoria corretta
• Aggiunto voce di navigazione laterale in /astro.config.mjs
• Creati il directory di documentazione del plugin
• Creati index.mdx pagina di panoramica
• Creato getting-started.mdx guida
• Creato tutorial in /src/content/plugins-tutorials/en/
• Incluso istruzioni di installazione
• Documentato la configurazione iOS
• Documentato la configurazione Android
• Fornito esempi di utilizzo
• Aggiunto riferimento a API
• Incluso esempio completo e funzionante
• Elencato le migliori pratiche
• Aggiunte note specifiche per piattaforma
• Testato che tutti i collegamenti funzionano correttamente

Icone di Riferimento

Icône comuni utilizzate per i plugin (da astro-heroicons/mini/):

Icône	Caso d'uso
BoltIcon	contexto
CameraIcon	Flash, potenza, energia
ChatBubbleLeftIcon	Camera, foto, video
FingerPrintIcon	Chat, messaggistica, comunicazione
MapPinIcon	Biometrico, sicurezza, autenticazione
SpeakerWaveIcon	Posizione, geolocalizzazione, mappe
VideoCameraIcon	Audio, suono, musica
CreditCardIcon	Pagamenti, acquisti
PlayCircleIcon	Lettori di media, lettori di video
SignalIcon	Connessione, 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 in documentazione
2. Aggiungi guide di migrazione se esistono cambiamenti di versione
3. Aggiorna la API reference con nuove metodi
4. Aggiungi nuovi esempi per nuove funzionalità
5. Aggiorna le richieste del sistema operativo se cambiate
6. Revisiona le migliori pratiche basate su nuove funzionalità
7. Tenere aggiornato il tutorial con le ultime API

Percorsi di linguaggio

Scrivi e revisiona le documentazioni dei plugin in inglese. Le percorrenze localizzate sono generate dai metadati del sito e tradotte 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. Controlla gli errori:

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

3. Visualizza il sito:

   bun run dev

4. Verifica che il tuo plugin sia presente:

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

Difficoltà comuni

Precauzione

Evitare questi errori comuni:

1. Omettere la sincronizzazione: Eseguire sempre bunx cap sync in esempi
2. Nomina incoerente: Utilizzare sempre lo stesso nome del plugin
3. Configurazione della piattaforma mancante: Documentare sia la configurazione iOS che Android
4. Collegamenti rotti: Utilizzare collegamenti relativi e verificarne il funzionamento
5. Assenza di gestione degli errori: Mostrare sempre il blocco try-catch negli esempi
6. Importi mancanti: Includi tutti gli import necessari negli esempi
7. Descrizioni poco chiare: Sii specifico su cosa fa il plugin

Aiuto

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

• Discord: Unisciti alla nostra Comunità Discord
• GitHub: Apri un issue sul repository del sito web
• Email: Contattate il team a support@capgo.app

Esempi

Per riferimento, controllate 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, buon esempio di partenza)
• Login sociale: /src/content/docs/docs/plugins/social-login/ Aggiungere un plugin alla documentazione di __CAPGO_KEEP_0__ comprende:

Aggiungere metadati alla configurazione principale

Adding a plugin to the Capgo documentation involves:

1. Creare pagine di documentazione esaustive
2. Scrivere un tutorial dettagliato
3. Testare tutte le modifiche localmente
4. Seguendo questa guida, si assicura che i plugin siano documentati in modo coerente e facilmente scopribili dagli utenti.
5. Continua da Aggiungere o Aggiornare i Plugin
6. Riepilogo

Sezione intitolata “Riepilogo”

Aggiungere un plugin alla documentazione di __CAPGO_KEEP_0__

Se stai utilizzando Aggiungere o Aggiornare Plugin per pianificare il lavoro sui plugin nativi, connettilo con Capgo Directory dei Plugin per il flusso di lavoro del prodotto in Capgo Directory dei Plugin Capacitor Plugin da Capgo per i dettagli di implementazione in Capacitor Plugin da Capgo Sostituti di Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Sostituti di Plugin Enterprise Ionic Capgo Costruzioni Native per il flusso di lavoro del prodotto in Capgo Costruzioni Native Capacitor Plugin: Cosa Devi Sapere per il contesto pratico in Capacitor Plugin: Cosa Devi Sapere.