Aggiungere o aggiornare plugin

Questa guida spiega come aggiungere nuovi Capacitor plugin al Capgo sito web o aggiornare la documentazione dei plugin esistenti. 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 garantire che il plugin sia visualizzato correttamente in tutti i luoghi pertinenti:

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

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 indice plugin con categorie
/astro.config.mjs	Configurazione della navigazione del lato
/src/content/docs/docs/plugins/[plugin-name]/	Directory documentazione plugin
/src/content/plugins-tutorials/en/	File tutorial in inglese

Guida Passo-dopo-Passo

1. Aggiungi Plugin all'elenco principale

   Apre /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 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 in evidenza
   • 📱 Plugin per dispositivi e sistema
   • 🎥 Plugin Media e Camera
   • 🛠️ Plugin di Utilità
   • 🤖 AI e Media Avanzati
   • 📍 Servizi di Posizione e Background
   • 📞 Comunicazione e Analisi
   • 🔐 Sicurezza e Sistema
   • 📊 Caratteristiche Specifiche per Android
   • 📥 Download e Navigazione

3. Aggiungi alla Navigazione del Lato

   Apri /astro.config.mjs e aggiungi il tuo plugin alla configurazione della navigazione del lato (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 per la documentazione del plugin

   Crea un nuovo 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. Crea 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 Opzionali

Per 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 Breve: Mantieni le descrizioni sotto i 100 caratteri
• Sii Preciso: Spiega cosa fa il plugin, non cosa è
• Usa parole d'azione: Inizia con verbi come “Controllo”, “Integrazione”, “Abilita”

Esempi buoni:

• “Controllo il dispositivo flashlight e torch con un semplice toggle on/off”
• “Integra il live chat e il supporto clienti di Crisp nella tua app”
• “Abilita l'autenticazione sicura utilizzando Face ID e Touch ID”

Esempi cattivi:

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

Scrivere la documentazione

1. Inizia con l'Installazione: Inizia sempre con istruzioni di installazione chiare
2. Fornisci Configurazione: Includi requisiti di configurazione specifici per piattaforma
3. Mostra Esempi di Utilizzo: Fornisci esempi di lavoro code funzionanti
4. Includi Riferimento API: Documenta tutti i metodi e i parametri
5. Aggiungi Esempi Completi: Mostra modelli di utilizzo realistici
6. Elenca le Migliori Pratiche: Condividi consigli per un utilizzo ottimale
7. Documentare le differenze di piattaforma: chiarire il comportamento iOS vs Android
8. Aggiungi la risoluzione dei problemi: affrontare le questioni comuni

Code Esempi

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

Checklist

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 la categoria corretta
• Aggiunto voce di navigazione nella /astro.config.mjs
• Creato directory di documentazione del plugin
• Creato 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

Riferimento all'icona

Icône comune utilizzata per i plugin (da astro-heroicons/mini/):

Icône	Utilizzo
BoltIcon	Energia, potenza, lampo
CameraIcon	Flash, potenza, energia
ChatBubbleLeftIcon	Comunicazione, messaggistica, chat
FingerPrintIcon	Chat, messaggistica, comunicazione
MapPinIcon	Biometrico, sicurezza, autenticazione
SpeakerWaveIcon	Posizione, geolocalizzazione, mappe
VideoCameraIcon	Audio, suono, musica
CreditCardIcon	Video, registrazione, streaming
PlayCircleIcon	Risultati dei player multimediali, player 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. Aggiornare i numeri di versione nella documentazione
2. Aggiungere guide di migrazione se esistono cambiamenti dirompenti
3. Aggiornare la API reference con nuove metodi
4. Aggiungi nuovi esempi per nuove funzionalità
5. Aggiorna le richieste della piattaforma se cambiate
6. Rivedi le migliori pratiche basate su nuove funzionalità
7. Mantieni il tutorial aggiornato con le ultime API

Percorsi di Lingua

Scrivi e recensisci i documenti del 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 del 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 il sito:

   bun run dev

4. Verifica che il tuo plugin sia presente:

   • Controlla la pagina di elenco plugin
   • Verifica la navigazione laterale
   • Testa tutte le pagine di documentazione
   • Verifica che la pagina del tutorial funzioni

Pitfall comune

Attenzione

Evita questi errori comuni:

1. Dimenticare di sincronizzareEsegui sempre bunx cap sync in esempi
2. Nomina incoerenteEsegui sempre il nome del plugin in ogni luogo
3. Mancanza di configurazione della piattaformaEsegui sempre la documentazione di iOS e Android
4. Collegamenti rottiUsa collegamenti relativi e verifica che funzionino
5. Assenza di gestione degli erroriEsegui sempre try-catch negli esempi
6. Mancanza di importazioniEsegui sempre le importazioni necessarie negli esempi
7. Descrizioni poco chiare: Sii specifico sulle azioni del plugin

Ottenere Aiuto

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

• DiscordUnisciti a noi Community di Discord
• GitHub: Apri un issue sul Repository del sito web
• Email: Contattare il team a support@capgo.app

Esempi

Per riferimento, controlla questi plugin ben documentati:

• Updater: /src/content/docs/docs/plugins/updater/ Aggiungere plugin complesso con più pagine
• Flash: /src/content/docs/docs/plugins/flash/ Esempio di plugin semplice (buon esempio di partenza)
• Login Sociale: /src/content/docs/docs/plugins/social-login/ Aggiungere plugin

Summary

Aggiungere un plugin alla Capgo documentazione comporta:

1. Aggiungere metadati alla configurazione principale
2. Aggiungere il plugin alla pagina di indice categorizzata
3. Configurare la navigazione 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.

Continua da Aggiungere o Aggiornare Plugin

Se stai utilizzando Aggiungere o Aggiornare Plugin per pianificare il lavoro di plugin nativo, connettilo con Directory dei Plugin Capgo per il workflow del prodotto nella Capgo Directory dei Plugin Plugin Capacitor sviluppati da Capgo per i dettagli di implementazione in Plugin Capacitor sviluppati da Capgo Sostituti di Plugin Enterprise Ionic per il flusso di lavoro del prodotto nelle Alternative Plugin Enterprise Ionic Costruzioni Native Capgo per il flusso di lavoro del prodotto in Costruzioni Native Capgo, e Plugin Capacitor: Cosa Devi Sapere per il contesto pratico in Plugin Capacitor: Cosa Devi Sapere