Ajout ou mise à jour de plugins

Ce guide explique comment ajouter de nouveaux plugins Capacitor au site Web Capgo ou mettre à jour la documentation des plugins existants. Ceci est utile pour les contributeurs, les responsables et les agents IA qui aident à maintenir la documentation.

Aperçu

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 garantir que le plugin apparaît correctement à tous les endroits pertinents :

1. Configuration de la liste des plugins - Ajoutez les métadonnées du plugin à la liste principale
2. Page d’index du plugin - Ajoutez un plugin à la page de liste des plugins catégorisés
3. Navigation dans la barre latérale - Ajouter un plugin à la barre latérale de la documentation
4. Documentation du plugin - Créez des pages de présentation et de démarrage
5. Tutoriel du plugin - Créez un didacticiel complet

Emplacements des fichiers

Fichiers clés à mettre à jour

Fichier	Objectif
/src/config/plugins.ts	Liste principale des plugins avec métadonnées
/src/content/docs/docs/plugins/index.mdx	Page d’index du plugin avec catégories
/astro.config.mjs	Configuration de la navigation dans la barre latérale
/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

   Ouvrez /src/config/plugins.ts et ajoutez votre plugin au tableau actions :

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

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

   <LinkCard
     title="Votre nom de plugin"
     description="Brief description of what the plugin does"
     href="/docs/plugins/your-plugin-name/"
   />

   Catégories :

   • ⭐ Plugins en vedette
   • 📱 Plugins pour appareils et systèmes
   • 🎥 Plugins multimédia et caméra
   • 🛠️ Plugins utilitaires
   • 🤖 IA et médias avancés
   • 📍 Services de localisation et d’arrière-plan
   • 📞Communication et analyses
   • 🔐 Sécurité et système
   • 📊 Android-Fonctionnalités spécifiques
   • 📥 Téléchargement et navigation

3. Ajouter à la navigation dans la barre latérale

   Ouvrez /astro.config.mjs et ajoutez votre plugin à la configuration de la barre latérale (autour de la 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 répertoriés par ordre alphabétique dans la barre latérale.

4. Créer un répertoire de documentation des plugins

   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 une page de présentation du plugin

   Créez /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="Caractéristique 1" icon="puzzle">
       Description of first key feature
     </Card>
     <Card title="Caractéristique 2" icon="rocket">
       Description of second key feature
     </Card>
     <Card title="Cross-platform" icon="puzzle">
       Works on both iOS and Android 📱
     </Card>
     <Card title="Documentation complète" icon="open-book">
       Check the [Documentation](/docs/plugins/your-plugin-name/getting-started/) to master the plugin.
     </Card>
   </CardGrid>

6. Créer un guide de démarrage

   Créez /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 un fichier didacticiel

   Créez /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

Directives relatives au contenu

Rédaction de descriptions de plugins

• Soyez concis : gardez les descriptions de moins de 100 caractères
• Soyez précis : expliquez ce que fait le plugin, pas ce que c’est
• Utilisez des mots d’action : commencez par des verbes tels que “Contrôler”, “Intégrer”, “Activer”

Bons exemples :

• “Contrôlez la lampe de poche et la torche avec une simple bascule marche/arrêt”
• “Intégrez le chat en direct Crisp et le support client dans votre application”
• “Activer l’authentification sécurisée à l’aide de Face ID et Touch ID”

Mauvais exemples :

• “Un plugin pour flash”
• “Ceci est un plugin Crisp”
• “Plugin biométrique”

Rédaction de documentation1. Commencez par l’installation : commencez toujours par des étapes d’installation claires

2. Fournir la configuration : inclure les exigences de configuration spécifiques à la plate-forme
3. Afficher des exemples d’utilisation : fournissez des exemples de code de travail
4. Inclure la référence API : documenter toutes les méthodes et paramètres
5. Ajouter des exemples complets : affichez des modèles d’utilisation réels
6. Liste des meilleures pratiques : partagez des conseils pour une utilisation optimale
7. Différences entre les plates-formes de documents : clarifiez le comportement de iOS par rapport à Android
8. Ajouter un dépannage : résoudre les problèmes courants

Exemples de codes

• Utilisez TypeScript pour tous les exemples de code
• Inclure les importations en haut
• Ajouter des commentaires expliquant les étapes clés
• Afficher la gestion des erreurs
• Démontrer une utilisation de base et avancée

Liste de contrôle

Utilisez cette liste de contrôle lors de l’ajout d’un nouveau plugin :

• Ajout du plugin à /src/config/plugins.ts
• Icône appropriée sélectionnée parmi Heroicons
• Ajout du plugin à /src/content/docs/docs/plugins/index.mdx sous la bonne catégorie
• Ajout d’une entrée dans la barre latérale dans /astro.config.mjs
• Création du répertoire de documentation du plugin -[ ] Création de la page de présentation index.mdx
• Création du guide getting-started.mdx -[ ] Tutoriel créé dans /src/content/plugins-tutorials/en/
• Instructions d’installation incluses -[ ] Configuration iOS documentée -[ ] Configuration Android documentée
• Exemples d’utilisation fournis
• Ajout de la référence API
• Exemple de travail complet inclus
• Meilleures pratiques répertoriées
• Ajout de notes spécifiques à la plateforme
• Testé, tous les liens fonctionnent correctement

Référence de l’icône

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

Icône	Cas d’utilisation
BoltIcon	Flash, puissance, énergie
CameraIcon	Appareil photo, 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	Lecteurs multimédias, lecteurs vidéo
SignalIcon	Connectivité, réseau, balise
RadioIcon	Balise de diffusion sans fil
ChatBubbleOvalLeftIcon	Médias sociaux, WeChat

Mise à jour des plugins existants

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

1. Mettre à jour les numéros de version dans la documentation
2. Ajoutez des guides de migration si des modifications importantes existent
3. Mettre à jour la référence API avec de nouvelles méthodes
4. Ajouter de nouveaux exemples pour les nouvelles fonctionnalités
5. Mettre à jour les exigences de la plate-forme si elles sont modifiées
6. Réviser les meilleures pratiques en fonction des nouvelles fonctionnalités
7. Gardez le didacticiel à jour avec le dernier API

Prise en charge multilingue

Le site Web prend en charge plusieurs langues. Après avoir créé la documentation en anglais :

1. Exécutez le script de traduction :

   bun run plugins:translate_all

2. Examinez les traductions générées dans :

   • /src/content/plugins-tutorials/de/ (allemand)
   • /src/content/plugins-tutorials/es/ (espagnol)
   • /src/content/plugins-tutorials/fr/ (français)
   • /src/content/plugins-tutorials/it/ (italien)
   • /src/content/plugins-tutorials/ja/ (japonais)
   • /src/content/plugins-tutorials/ko/ (coréen)
   • /src/content/plugins-tutorials/id/ (indonésien)

Tester vos modifications

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

1. Créez le site localement :

   npm run build
   ```2. **Vérifiez les erreurs** :
   - Vérifiez que tous les liens fonctionnent
   - Assurez-vous que les images se chargent correctement
   - Confirmer que les exemples de code sont valides
   - Tester les travaux de navigation

2. Prévisualisez le site :

   npm run dev

3. Vérifiez que votre plugin apparaît :

   • Vérifiez la page de liste des plugins
   • Vérifier la navigation dans la barre latérale
   • Tester toutes les pages de documentation
   • Confirmer que la page du didacticiel fonctionne

Pièges courants

Attention

Évitez ces erreurs courantes :

1. Oublier la synchronisation : exécutez toujours npx cap sync dans les exemples
2. Nom incohérent : utilisez le même nom de plugin partout
3. Configuration de plate-forme manquante : documentez la configuration de iOS et Android
4. Liens brisés : utilisez des liens relatifs et vérifiez qu’ils fonctionnent
5. Aucune gestion des erreurs : affichez toujours try-catch dans les exemples
6. Importations manquantes : incluez toutes les importations nécessaires dans les exemples
7. Descriptions peu claires : soyez précis 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 : ouvrez un ticket sur le dépôt du site Web
• E-mail : 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. Ajout de métadonnées à la configuration principale
2. Ajout du plugin à la page d’index catégorisée
3. Configuration de la navigation dans la barre latérale
4. Création de pages de documentation complètes
5. Rédaction d’un tutoriel détaillé
6. Tester toutes les modifications localement

En suivant ce guide, vous vous assurez que les plugins sont systématiquement documentés et facilement détectables par les utilisateurs.