Ajouter ou mettre à jour des plugins

Cette guide explique comment ajouter de nouveaux Capacitor plugins au site Capgo ou mettre à jour la documentation d'un plugin existant. Cela est utile pour les contributeurs, les gestionnaires et les agents AI aidant à maintenir la documentation.

Vue d'ensemble

Lorsque vous ajoutez un nouveau plugin à l'écosystème Capgo, vous devez mettre à jour plusieurs fichiers et emplacements sur le site Web pour vous assurer que le plugin apparaisse correctement dans tous les endroits pertinents :

1. Configuration de la liste des plugins - Ajouter les métadonnées du plugin à la liste principale
2. Page d'index des plugins - Ajouter le plugin à la page de liste des plugins catégorisés
3. Navigation latérale Ajoutez le plugin au menu de documentation
4. Documentation du plugin - Créez des pages d'aperçu et de démarrage
5. Tutoriel du Plugin - Créez un tutoriel complet

Emplacements de fichiers

Fichiers clés à mettre à jour

Fichier	But
/src/config/plugins.ts	Liste des plugins maîtres avec métadonnées
/src/content/docs/docs/plugins/index.mdx	Page d'index des plugins avec catégories
/astro.config.mjs	Configuration de navigation du menu latéral
/src/content/docs/docs/plugins/[plugin-name]/	Répertoire de documentation des plugins
/src/content/plugins-tutorials/en/	Fichiers de tutoriel en anglais

Guide étape par étape

1. Ajouter un plugin à la liste principale

   Ouvrir /src/config/plugins.ts et ajoutez votre plugin à la actions tableau :

   // 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,
   }

   Icônes disponibles: Vérifiez /node_modules/astro-heroicons/mini/ pour les icônes disponibles.

2. Ajouter un plugin à la page d'index

   Ouvrir /src/content/docs/docs/plugins/index.mdx et ajoutez votre plugin dans la catégorie appropriée :

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

   Catégories:

   • ⭐ Plugins en vedette
   • 📱 Plugins de périphérique et de système
   • 🎥 Plugins multimédia et de caméra
   • 🛠️ Plugins d'utilité
   • 🤖 Plugins IA et multimédia avancés
   • 📍 Localisation & Services d'arrière-plan
   • 📞 Communication & Analytics
   • 🔐 Sécurité & Système
   • 📊 Fonctionnalités spécifiques à Android
   • 📥 Téléchargement & Navigation

3. Ajouter à la navigation latérale

   Ouvrir /astro.config.mjs et ajoutez votre plugin à la configuration de la navigation latérale (environ ligne 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,
   }

   Les plugins sont listés alphabétiquement dans la navigation latérale.

4. Créer le répertoire de documentation du plugin

   Créez un nouveau répertoire pour la documentation de votre plugin :

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

5. Créer la page d'accueil du plugin

   Créer /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. Créer le guide de démarrage

   Créer /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. Créer le Fichier de Tutoriel

   Créer /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]

Structure de la Documentation du Plugin

Fichiers Obligatoires

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

Fichiers Facultatifs

Pour les plugins complexes, vous pouvez ajouter des pages de documentation supplémentaires :

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

Lignes directrices du contenu

Écrire les descriptions des plugins

• Sois concis : Garde les descriptions sous 100 caractères
• Sois spécifique : Explique ce que fait le plugin, et non ce qu'il est
• Utilise les verbes d'action : Commence par des verbes comme « Contrôler », « Intégrer », « Activer »

Exemples de bonne pratique:

• “Contrôlez la lumière de votre appareil avec un simple bouton d'allumage”
• “Intégrez le chat en direct Crisp et le support client dans votre application”
• “Activez l'authentification sécurisée à l'aide de Face ID et de Touch ID”

“Exemples non recommandés”:

• “Un plugin pour la lumière”
• “Ce est un plugin Crisp”
• “Plugin biométrique”

“Écrire la documentation”

1. Commencez par l'installationToujours commencer par des étapes d'installation claires
2. Section intitulée “Écrire la documentation”: Incluez les exigences de configuration spécifiques à la plateforme
3. Afficher les Exemples d'utilisation: Fournir des exemples de travail code
4. Inclure la référence API: Documentez tous les méthodes et paramètres
5. Ajouter des Exemples complets: Montrez des modèles d'utilisation dans le monde réel
6. Lister les Meilleures Pratiques: Partagez des conseils pour un usage optimal
7. Documenter les Différences de plateforme: Clarifiez le comportement iOS vs Android
8. Ajouter des Résolutions de problèmes: Résoudre les problèmes courants

Code Exemples

• Utilisez TypeScript pour tous les code exemples
• Incluez les importations en haut
• Add comments explaining key steps
• Affichez la gestion des erreurs
• Démontrer les deux utilisations de base et avancées

Checklist

Use this checklist when adding a new plugin:

• Plugin ajouté à /src/config/plugins.ts
• Sélectionné l'icône appropriée de Heroicons
• Ajouté le plugin à /src/content/docs/docs/plugins/index.mdx sous la catégorie correcte
• Ajouté une entrée de côté-bar dans /astro.config.mjs
• Créé le répertoire de documentation du plugin
• Créé index.mdx page d'aperçu
• Créé getting-started.mdx guide
• Créé un tutoriel dans /src/content/plugins-tutorials/en/
• Inclu les instructions d'installation
• Documenté la configuration iOS
• Configuration Android documentée
• Exemples d'utilisation fournis
• Référence ajoutée à API
• Exemple fonctionnel complet inclus
• Meilleures pratiques listées
• Notes spécifiques au plateau ajoutées
• Tous les liens testés et fonctionnels

Référence d'icône

Icônes courantes utilisées pour les plugins (de astro-heroicons/mini/):

Icône	Utilisation
BoltIcon	Éclairage, puissance, énergie
CameraIcon	Caméra, photo, vidéo
ChatBubbleLeftIcon	Chat, messagerie, communication
FingerPrintIcon	Biométrie, sécurité, authentification
MapPinIcon	Localisation, géolocalisation, cartes
SpeakerWaveIcon	Audio, son, musique
VideoCameraIcon	Vidéo, enregistrement, streaming
CreditCardIcon	Paiements, achats
PlayCircleIcon	Joueurs multimédia, lecteurs vidéo
SignalIcon	Connectivité, réseau, balise
RadioIcon	Balise, diffusion, sans fil
ChatBubbleOvalLeftIcon	Réseaux sociaux, WeChat

Mise à jour des Plugins Existants

Lorsque vous mettez à jour un plugin existant :

1. Mise à jour des numéros de version dans la documentation
2. Ajouter des guides de migration si des changements de rupture existent
3. Mettre à jour la référence API avec de nouvelles méthodes
4. Ajouter de nouveaux exemples pour de nouvelles fonctionnalités
5. Mettre à jour les exigences de plateforme Si modifié
6. Réviser les meilleures pratiques Sur la base de nouvelles fonctionnalités
7. Tenir le tutoriel à jour Avec les derniers API

Chemins de Langue

Écrire et réviser les documents de plugins en anglais. Les chemins localisés sont générés par les métadonnées du site et traduits en bordure par le Worker de traduction.

Testez vos modifications

Après avoir ajouté ou mis à jour la documentation du plugin :

1. Construire le site localement:

   bun run build

2. Vérifier les erreurs:

   • Vérifier que tous les liens fonctionnent
   • S'assurer que les images chargent correctement
   • Confirmer que les exemples code sont valides
   • Tester la navigation fonctionne

3. Prévisualiser le site:

   bun run dev

4. Vérifier que votre plugin est affiché:

   • Vérifier la page de liste des plugins
   • Vérifiez la navigation du côté gauche
   • Testez toutes les pages de documentation
   • Confirmez que la page de tutoriel fonctionne

Pitfalls courantes

Attention

Évitez ces erreurs courantes :

1. Oublier de synchroniser: Exécutez toujours bunx cap sync dans les exemples
2. Nommage incohérent: Utilisez le même nom de plugin partout
3. Configuration de plateforme manquante: Documentez à la fois la configuration iOS et Android
4. Liens brisés: Utilisez des liens relatifs et vérifiez qu'ils fonctionnent
5. Aucun traitement d'erreur: Affichez toujours un try-catch dans les exemples
6. Importations manquantes: Incluez toutes les importations nécessaires dans les exemples
7. Descriptions obscures: Soyez spécifique sur ce que fait le plugin

Obtenir de l'aide

If you need help adding or updating plugin documentation:

• Discord: Rejoignez notre communauté Discord
• GitHub: Ouvrez un problème sur le répertoire de dépôt du site
• Courriel: Contactez l'équipe à support@capgo.app

Exemples

Pour référence, consultez ces plugins bien documentés :

• Updater: /src/content/docs/docs/plugins/updater/ (plugin complexe avec plusieurs pages)
• Flash: /src/content/docs/docs/plugins/flash/ (plugin simple, bon exemple de démarrage)
• Connexion sociale: /src/content/docs/docs/plugins/social-login/ Ajouter des plugins

Summary

Ajouter un plugin à la documentation Capgo implique :

1. Ajouter des métadonnées à la configuration principale
2. Ajouter le plugin à la page d'index catégorisée
3. Configuration de la navigation du côté
4. Création de pages de documentation complètes
5. Écriture d'un tutoriel détaillé
6. Test de toutes les modifications localement

En suivant ce guide, vous assurez que les plugins sont documentés de manière cohérente et facilement repérables par les utilisateurs.

Continuez à ajouter ou à mettre à jour des plugins

Si vous utilisez Ajouter ou Mettre à Jour des Plugins pour planifier le travail de plugin natif, connectez-l’avec Répertoire de plugin Capgo pour le flux de travail du produit dans le répertoire de plugin Capgo les plugins Capacitor par Capgo pour le détail d'implémentation dans les plugins Capacitor par Capgo Alternatives de plugins Ionic Enterprise Pour le flux de travail du produit dans les alternatives Ionic Enterprise Plugin. les builds natives Capgo pour le flux de travail du produit dans les builds natives Capgo. les plugins Capacitor : ce que vous devez savoir pour le contexte pratique dans les plugins Capacitor : ce que vous devez savoir.