Ajouter ou mettre à jour des plugins

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

Vue d'ensemble

Lors de l'ajout d'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 maîtresse
2. Page d'index des plugins - Ajouter un plugin à la page de liste des plugins catégorisés
3. Navigation de côté - Ajouter un plugin à la navigation de documentation de côté
4. Documentation du plugin - Créer des pages d'aperçu et de démarrage rapide
5. Tutoriel du plugin - Créer un tutoriel complet

Emplacements de fichiers

Fichiers clés à mettre à jour

File	Objectif
/src/config/plugins.ts	context":"Page/area: Site de marketing Capgo. Role: Petit élément d'interface utilisateur ou d'élément de navigation. Message clé `subprocessors_table_purpose` (Objectif de la table des sous-processus)."
/src/content/docs/docs/plugins/index.mdx	Liste des plugins maîtres avec métadonnées
/astro.config.mjs	Page d'index des plugins avec catégories
/src/content/docs/docs/plugins/[plugin-name]/	Configuration de navigation de côté
/src/content/plugins-tutorials/en/	Dossier de documentation des plugins

Fichiers de tutoriel en anglais

1. Section intitulée « Guide étape par étape »

   Section intitulée « Ajouter un plugin à la liste maîtres » /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 le Plugin à la Page d'Index

   Ouvrir /src/content/docs/docs/plugins/index.mdx et ajoutez votre plugin sous 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é
   • 🤖 Intelligence artificielle et médias avancés
   • 📍 Services de localisation et de fond
   • 📞 Communication et analytiques
   • 🔐 Sécurité et système
   • 📊 Fonctionnalités spécifiques à Android
   • 📥 Téléchargement et navigation

3. Ajouter à la navigation latérale

   Ouvrir /astro.config.mjs et ajoutez votre plugin à la configuration du côté gauche (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 le côté gauche.

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'aperçu 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 Getting Started

   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 requis

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 de contenu

Écrire des descriptions de plugins

• Soyez concis : Gardez les descriptions sous 100 caractères
• Étant Spécifique: Expliquez ce que le plugin fait, et non ce qu'il est
• Utilisez des Verbes d'Action: Commencez par des verbes comme “Contrôler”, “Intégrer”, “Activer”

Exemples de Bonnes Pratiques:

• “Contrôlez l'éclairage de la lampe-torche du dispositif avec un simple bouton d'allumage et d'éteignage”
• “Intégrez le chat en direct Crisp et le support client dans votre application”
• “Activez une authentification sécurisée à l'aide de Face ID et de Touch ID”

Exemples de Mauvaises Pratiques:

• “Un plugin pour l'éclairage de lampe-torche”
• “Ceci est un plugin Crisp”
• “Plugin biométrique”

Ecrire la documentation

1. Démarrer avec l'installation: Commencez toujours par des étapes d'installation claires
2. Fournir la configuration: Incluez les exigences de configuration spécifiques au système
3. Montrer des exemples d'utilisation: Fournissez des exemples code fonctionnels
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 du monde réel
6. Liste de bonnes pratiques: Partagez des conseils pour un usage optimal
7. Documenter les différences de plateforme: Clarifiez le comportement iOS par rapport à Android
8. Ajouter des solutions de rechange: Abordez les problèmes courants

Code Exemples

• Utilisez TypeScript pour tous les code exemples
• Incluez les importations en haut
• Ajoutez des commentaires expliquant les étapes clés
• Affichez la gestion des erreurs
• Démontrer à la fois les utilisations de base et avancées

Liste de vérification

Utilisez cette liste de vérification lors de l'ajout d'un nouveau plugin :

• Ajouter le plugin à /src/config/plugins.ts
• Sélectionner l'icône appropriée de Heroicons
• Ajouter le plugin à /src/content/docs/docs/plugins/index.mdx sous la catégorie correcte
• Ajouter une entrée de côté-bar dans /astro.config.mjs
• Créer le répertoire de documentation du plugin
• Créer index.mdx page d'aperçu
• Créé getting-started.mdx guide
• Créé un tutoriel dans /src/content/plugins-tutorials/en/
• Inclus les instructions d'installation
• Documenté la configuration iOS
• Documenté la configuration Android
• Fourni des exemples d'utilisation
• Ajouté une référence à API
• Inclus un exemple de travail complet
• Listé les meilleures pratiques
• Ajouté des notes spécifiques au plateforme
• Testé que tous les liens fonctionnent correctement

Référence des icônes

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

Icone	Utilisation
BoltIcon	context : Page/zone : Page de marketing des solutions Capgo. Rôle : Étiquette de navigation ou élément de l'interface utilisateur court. Vu dans : page solutions/cordova-to-capacitor-ai.astro. Clé de message `solutions_cordova_to_capacitor_ai_table_use_case` (Utilisation des solutions Cordova To Capacitor Ai Table).
CameraIcon	Éclair, puissance, énergie
ChatBubbleLeftIcon	Caméra, photo, vidéo
FingerPrintIcon	Chat, messagerie, communication
MapPinIcon	Biométrique, sécurité, authentification
SpeakerWaveIcon	Localisation, géolocalisation, cartes
VideoCameraIcon	Audio, son, musique
CreditCardIcon	Les paiements, les achats
PlayCircleIcon	Les lecteurs multimédias, les lecteurs vidéo
SignalIcon	La connectivité, le réseau, le beacon
RadioIcon	Le beacon, la diffusion, sans fil
ChatBubbleOvalLeftIcon	Les médias sociaux, WeChat

Mettre à jour les plugins existants

Lors de la mise à jour d'un plugin existant :

1. Mettre à jour les numéros de version Dans la documentation
2. Ajouter des guides de migration S'il existe des changements brisants
3. Mettre à jour la référence de API Avec de nouvelles méthodes
4. Ajouter de nouveaux exemples Pour de nouvelles fonctionnalités
5. Mettre à jour les exigences du plateforme Si modifiées
6. Réviser les meilleures pratiques Sur la base de nouvelles fonctionnalités
7. Tenir le tutoriel à jour Avec les dernières API

Chemins de Langue

Écrivez et révisez les documents de plugin en anglais. Les chemins localisés sont générés par les métadonnées du site et traduits à l'extrémité par le Worker de traduction.

Testez vos modifications

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

1. Construirez le site localement:

   bun run build

2. Vérifiez les erreurs:

   • Vérifiez que toutes les liens fonctionnent
   • Assurez-vous que les images chargent correctement
   • Confirmez que les exemples code sont valides
   • Testez la navigation

3. Prévisualiser le site:

   bun run dev

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

   • Page de liste des plugins
   • Vérifiez la navigation latérale
   • Testez toutes les pages de documentation
   • Confirmez que la page de tutoriel fonctionne

Problèmes courants

Attention

Évitez ces erreurs courantes :

1. Oublier de synchroniser: Exécutez toujours bunx cap sync dans les exemples
2. Nomination incohérente: 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

Si vous avez besoin d'aide pour ajouter ou mettre à jour la documentation du plugin :

• Discord: Rejoignez notre Communauté Discord
• GitHub__CAPGO_KEEP_0__ répertoire du site web
• Courriel: Contactez l'équipe à support@capgo.app

Exemples

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

• Mise à jour: /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/ (plugin avec sous-pages)

Résumé

L'ajout d'un plugin à la documentation Capgo implique :

1. Ajouter des métadonnées à la configuration principale
2. Ajouter le plugin à la page d'index de catégorisation
3. Configurer la navigation de côté
4. Créer des pages de documentation complètes
5. Écrire un tutoriel détaillé
6. Tester toutes les modifications localement

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

Continuez de l'ajout ou de la mise à jour des plugins

Si vous utilisez « Ajouter ou mettre à jour des plugins » pour planifier le travail de plugin natif, connectez-l’à Capgo Répertoire des plugins pour le flux de travail du produit dans Capgo Répertoire des plugins, Capacitor Plugins par Capgo pour les détails d'implémentation dans Capacitor Plugins par Capgo Alternatives de plugins d'entreprise Ionic pour le flux de travail du produit dans Alternatives de plugins d'entreprise Ionic, Capgo Bâtiments natifs pour le flux de travail du produit dans Capgo Bâtiments natifs, et Plugins Capacitor : Ce que vous devez savoir pour le contexte pratique dans Plugins Capacitor : Ce que vous devez savoir.