Aggiungere o Aggiornare Plugin

Questa guida spiega come aggiungere nuovi plugin Capacitor al sito web Capgo o aggiornare la documentazione dei plugin esistenti. Questo è utile per contributori, manutentori e agenti AI che aiutano a mantenere la documentazione.

Panoramica

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

Configurazione Elenco Plugin - Aggiungi i metadati del plugin all’elenco principale
Pagina Indice Plugin - Aggiungi il plugin alla pagina elenco plugin categorizzato
Navigazione Sidebar - Aggiungi il plugin alla sidebar della documentazione
Documentazione Plugin - Crea pagine panoramica e guida introduttiva
Tutorial Plugin - Crea un tutorial completo

Posizioni dei File

File Chiave da Aggiornare

File	Scopo
`/src/config/plugins.ts`	Elenco principale plugin con metadati
`/src/content/docs/docs/plugins/index.mdx`	Pagina indice plugin con categorie
`/astro.config.mjs`	Configurazione navigazione sidebar
`/src/content/docs/docs/plugins/[nome-plugin]/`	Directory documentazione plugin
`/src/content/plugins-tutorials/en/`	File tutorial inglese

Guida Passo-Passo

Aggiungi Plugin all’Elenco Principale

Apri /src/config/plugins.ts e aggiungi il tuo plugin all’array actions:

// Prima, importa un'icona Heroicon appropriata
import YourIconName from 'astro-heroicons/mini/IconName.astro'

// Poi aggiungi all'array actions
{
  name: '@capgo/your-plugin-name',
  author: 'github.com/Cap-go',
  description: 'Breve descrizione di ciò che fa il plugin',
  href: 'https://github.com/Cap-go/your-plugin-name/',
  title: 'Nome Visualizzato',
  icon: YourIconName,
}

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

Aggiungi Plugin alla Pagina Indice
Section titled “Aggiungi Plugin alla Pagina Indice”

Apri /src/content/docs/docs/plugins/index.mdx e aggiungi il tuo plugin sotto la categoria appropriata:
```
<LinkCard
  title="Nome del Tuo Plugin"
  description="Breve descrizione di ciò che fa il plugin"
  href="/docs/plugins/your-plugin-name/"
/>
```
Categorie:
- ⭐ Plugin in Evidenza
- 📱 Plugin Dispositivo e Sistema
- 🎥 Plugin Media e Fotocamera
- 🛠️ Plugin Utilità
- 🤖 AI e Media Avanzati
- 📍 Servizi Posizione e Background
- 📞 Comunicazione e Analytics
- 🔐 Sicurezza e Sistema
- 📊 Funzionalità Specifiche Android
- 📥 Download e Navigazione

Apri /astro.config.mjs e aggiungi il tuo plugin alla configurazione sidebar (circa riga 540):

{
  label: 'Nome del Tuo Plugin',
  items: [
    { label: 'Panoramica', link: '/docs/plugins/your-plugin-name/' },
    { label: 'Guida introduttiva', link: '/docs/plugins/your-plugin-name/getting-started' },
  ],
  collapsed: true,
}

I plugin sono elencati in ordine alfabetico nella sidebar.

Crea Directory Documentazione Plugin
Section titled “Crea Directory Documentazione Plugin”

Crea una nuova directory per la documentazione del tuo plugin:
Terminal window
```
mkdir -p /src/content/docs/docs/plugins/your-plugin-name/
```

Crea Pagina Panoramica Plugin

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

---
title: "@capgo/your-plugin-name"
description: Breve descrizione dello scopo del plugin
tableOfContents: false
next: false
prev: false
sidebar:
  order: 1
  label: "Introduzione"
hero:
  tagline: Tagline dettagliata che spiega cosa fa il plugin
  image:
    file: ~public/your-plugin-icon.svg
  actions:
    - text: Inizia
      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="Funzionalità 1" icon="puzzle">
    Descrizione della prima funzionalità chiave
  </Card>
  <Card title="Funzionalità 2" icon="rocket">
    Descrizione della seconda funzionalità chiave
  </Card>
  <Card title="Multi-piattaforma" icon="puzzle">
    Funziona sia su iOS che Android 📱
  </Card>
  <Card title="Documentazione Completa" icon="open-book">
    Consulta la [Documentazione](/docs/plugins/your-plugin-name/getting-started/) per padroneggiare il plugin.
  </Card>
</CardGrid>

Crea Guida Introduttiva

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

---
title: Guida Introduttiva
description: Impara come installare e utilizzare il plugin nella tua app Capacitor.
sidebar:
  order: 2
---

import { Steps } from '@astrojs/starlight/components';
import { PackageManagers } from 'starlight-package-managers'

<Steps>
1. **Installa il pacchetto**
   <PackageManagers pkg="@capgo/your-plugin-name" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />

2. **Sincronizza con i progetti nativi**
   <PackageManagers type="exec" pkg="cap" args="sync" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
</Steps>

## Configurazione

### Configurazione iOS
[Istruzioni di configurazione specifiche per iOS]

### Configurazione Android
[Istruzioni di configurazione specifiche per Android]

## Utilizzo

[Esempi di utilizzo base]

## Riferimento API

[Documentazione API dettagliata]

## Esempio Completo

[Esempio funzionante completo]

## Migliori Pratiche

[Pratiche raccomandate e suggerimenti]

## Note sulla Piattaforma

[Note e limitazioni specifiche della piattaforma]

Crea File Tutorial

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

---
locale: en
---
# Utilizzo del Pacchetto @capgo/your-plugin-name

Il pacchetto `@capgo/your-plugin-name` [breve descrizione]. In questo tutorial, ti guideremo attraverso l'installazione, la configurazione e l'utilizzo di questo pacchetto nella tua app Ionic Capacitor.

## Installazione

[Passi di installazione]

## Configurazione

[Passi di configurazione per iOS e Android]

## Utilizzo API

[Esempi dettagliati di utilizzo API]

## Esempio Completo

[Esempio funzionante completo]

## Migliori Pratiche

[Suggerimenti e migliori pratiche]

## Risoluzione dei Problemi

[Problemi comuni e soluzioni]

## Conclusione

[Riepilogo e link a risorse aggiuntive]

Struttura Documentazione Plugin

File Richiesti

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx           # Pagina panoramica con hero e card funzionalità
└── getting-started.mdx # Guida installazione e utilizzo

src/content/plugins-tutorials/en/
└── your-plugin-name.md # Tutorial completo

File Opzionali

Per plugin complessi, puoi aggiungere pagine di documentazione aggiuntive:

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx
├── getting-started.mdx
├── api-reference.mdx   # Documentazione API dettagliata
├── examples.mdx        # Esempi aggiuntivi
├── troubleshooting.mdx # Guida risoluzione problemi
└── migrations.mdx      # Guide migrazione

Linee Guida Contenuto

Scrivere Descrizioni Plugin

Sii Conciso: Mantieni le descrizioni sotto 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 la torcia e il flash del dispositivo con semplice on/off”
“Integra chat live Crisp e supporto clienti nella tua app”
“Abilita autenticazione sicura usando Face ID e Touch ID”

Esempi Cattivi:

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

Scrivere Documentazione

Inizia con l’Installazione: Inizia sempre con passaggi di installazione chiari
Fornisci Configurazione: Includi requisiti di configurazione specifici della piattaforma
Mostra Esempi di Utilizzo: Fornisci esempi di codice funzionanti
Includi Riferimento API: Documenta tutti i metodi e parametri
Aggiungi Esempi Completi: Mostra modelli di utilizzo nel mondo reale
Elenca Migliori Pratiche: Condividi suggerimenti per un utilizzo ottimale
Documenta Differenze Piattaforma: Chiarisci comportamento iOS vs Android
Aggiungi Risoluzione Problemi: Affronta problemi comuni

Esempi di Codice

Usa TypeScript per tutti gli esempi di codice
Includi importazioni in cima
Aggiungi commenti per spiegare i passaggi chiave
Mostra gestione errori
Dimostra utilizzo base e avanzato

Checklist

Usa questa checklist quando aggiungi un nuovo plugin:

Riferimento Icone

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

Icona	Caso d’Uso
`BoltIcon`	Flash, energia, potenza
`CameraIcon`	Fotocamera, 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 media, lettori video
`SignalIcon`	Connettività, rete, beacon
`RadioIcon`	Beacon, broadcast, wireless
`ChatBubbleOvalLeftIcon`	Social media, WeChat

Aggiornamento Plugin Esistenti

Quando aggiorni un plugin esistente:

Aggiorna numeri di versione nella documentazione
Aggiungi guide migrazione se esistono modifiche incompatibili
Aggiorna riferimento API con nuovi metodi
Aggiungi nuovi esempi per nuove funzionalità
Aggiorna requisiti piattaforma se modificati
Rivedi migliori pratiche basate su nuove funzionalità
Mantieni tutorial aggiornato con l’ultima API

Supporto Multi-lingua

Il sito web supporta più lingue. Dopo aver creato la documentazione inglese:

Esegui lo script di traduzione:
Terminal window
```
bun run plugins:translate_all
```
Rivedi le traduzioni generate in:
- /src/content/plugins-tutorials/de/ (Tedesco)
- /src/content/plugins-tutorials/es/ (Spagnolo)
- /src/content/plugins-tutorials/fr/ (Francese)
- /src/content/plugins-tutorials/it/ (Italiano)
- /src/content/plugins-tutorials/ja/ (Giapponese)
- /src/content/plugins-tutorials/ko/ (Coreano)
- /src/content/plugins-tutorials/id/ (Indonesiano)

Testare le Tue Modifiche

Dopo aver aggiunto o aggiornato la documentazione dei plugin:

Compila il sito localmente:
Terminal window
```
npm run build
```
Controlla errori:
- Verifica che tutti i link funzionino
- Assicurati che le immagini si carichino correttamente
- Conferma che gli esempi di codice siano validi
- Testa che la navigazione funzioni
Anteprima del sito:
Terminal window
```
npm run dev
```
Verifica che il tuo plugin appaia:
- Controlla pagina elenco plugin
- Verifica navigazione sidebar
- Testa tutte le pagine documentazione
- Conferma che la pagina tutorial funzioni

Errori Comuni

Ottenere Aiuto

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

Discord: Unisciti alla nostra community Discord
GitHub: Apri un issue sul repository del sito web
Email: Contatta il team a support@capgo.app

Esempi

Per riferimento, controlla 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 iniziale)
Social Login: /src/content/docs/docs/plugins/social-login/ (plugin con sotto-pagine)

Riepilogo

Aggiungere un plugin alla documentazione Capgo comporta:

Aggiungere metadati alla configurazione principale
Aggiungere il plugin alla pagina indice categorizzato
Configurare navigazione sidebar
Creare pagine documentazione complete
Scrivere un tutorial dettagliato
Testare tutte le modifiche localmente

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