Aller au contenu

Ajouter ou mettre à jour des plugins

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

Lors de l’ajout d’un nouveau plugin à l’écosystème Capgo, vous devez mettre à jour plusieurs fichiers et emplacements sur le site web afin que le plugin s’affiche 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 par catégorie
  3. Navigation latérale - Ajouter le plugin à la barre latérale de la documentation
  4. Documentation du plugin - Créer les pages d’aperçu et de démarrage
  5. Tutoriel du plugin - Créer un tutoriel complet
FichierObjectif
/src/config/plugins.tsListe principale des plugins avec métadonnées
/src/content/docs/docs/plugins/index.mdxPage d'index des plugins avec catégories
/astro.config.mjsConfiguration de la navigation latérale
/src/content/docs/docs/plugins/[plugin-name]/Répertoire de la documentation des plugins
/src/content/plugins-tutorials/en/Fichiers du tutoriel en anglais
  1. Ouvrez /src/config/plugins.ts et ajoutez votre plugin au 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érifier /node_modules/astro-heroicons/mini/ pour les icônes disponibles.

  2. Ouvrez /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 appareil & système
    • 🎥 Plugins média & caméra
    • 🛠️ Plugins utilitaires
    • 🤖 IA et médias avancés
    • 📍 Localisation et services en arrière-plan
    • 📞 Communication et analytics
    • 🔐 Sécurité et système
    • 📊 Fonctionnalités spécifiques à Android
    • 📥 Téléchargement et navigation
  3. Ouvrez /astro.config.mjs et ajoutez votre plugin à la configuration de la barre latérale (vers 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,
    }

    Plugins are listed alphabetically in the sidebar.

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

    Fenêtre de terminal
    mkdir -p /src/content/docs/docs/plugins/your-plugin-name/
  5. 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 /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 /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]
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

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
  • Soyez concis: Gardez les descriptions sous les 100 caractères
  • Soyez précis: Expliquez ce que le plugin fait, pas ce qu’il est
  • Utilisez des verbes d’action: Commencez par des verbes comme « Control », « Integrate », « Enable »

Bonnes pratiques:

  • « Control device flashlight and torch with simple on/off toggle »
  • « Integrate Crisp live chat and customer support into your app »
  • « Enable secure authentication using Face ID and Touch ID »

Mauvaises pratiques:

  • « A plugin for flash »
  • « This is a Crisp plugin »
  • « Biometric plugin »
  1. Commencez par l’installation: Commencez toujours par des étapes d’installation claires
  2. Fournir la configuration: Inclure les prérequis de configuration par plateforme
  3. Afficher des exemples d'utilisation: Fournir des exemples code fonctionnels
  4. Inclure la référence API: Documenter toutes les méthodes et paramètres
  5. Ajouter des exemples complets: Montrer des cas d'usage réels
  6. Lister les bonnes pratiques: Partager des conseils pour une utilisation optimale
  7. Documenter les différences entre plateformes: Clarifier le comportement iOS vs Android
  8. Ajouter une section de dépannage: Résoudre les problèmes courants
  • Utiliser TypeScript pour tous les exemples code
  • Inclure les imports en haut
  • Add comments explaining key steps
  • Montrer la gestion des erreurs
  • Démontrer l’usage basique et avancé

Use this checklist when adding a new plugin:

  • Plugin ajouté à /src/config/plugins.ts
  • Icône appropriée sélectionnée dans Heroicons
  • Plugin ajouté à /src/content/docs/docs/plugins/index.mdx sous la bonne catégorie
  • Entrée de la barre latérale ajoutée dans /astro.config.mjs
  • Répertoire de documentation du plugin créé
  • Créé index.mdx page de présentation
  • Créé getting-started.mdx guide
  • Tutoriel créé dans /src/content/plugins-tutorials/en/
  • Instructions d'installation incluses
  • Configuration iOS documentée
  • Configuration Android documentée
  • Exemples d’utilisation fournis
  • Référence API ajoutée
  • Exemple complet et fonctionnel inclus
  • Bonnes pratiques listées
  • Notes spécifiques à la plateforme ajoutées
  • Tous les liens testés et fonctionnels

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

IcôneCas d’usage
BoltIconFlash, alimentation, énergie
CameraIconCaméra, photo, vidéo
ChatBubbleLeftIconChat, messagerie, communication
FingerPrintIconBiométrie, sécurité, authentification
MapPinIconLocalisation, géolocalisation, cartes
SpeakerWaveIconAudio, son, musique
VideoCameraIconVidéo, enregistrement, streaming
CreditCardIconPaiements, achats
PlayCircleIconLecteurs multimédias, lecteurs vidéo
SignalIconConnectivité, réseau, balise
RadioIconBalise, diffusion, sans fil
ChatBubbleOvalLeftIconRéseaux sociaux, WeChat

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 y a des breaking changes
  3. Mettre à jour la référence API avec les nouvelles méthodes
  4. Ajouter de nouveaux exemples pour les nouvelles fonctionnalités
  5. Mettre à jour les prérequis plateforme si modifié
  6. Réviser les bonnes pratiques en fonction des nouvelles fonctionnalités
  7. Garder le tutoriel à jour avec la dernière version de API

Rédigez et relisez la documentation des plugins en anglais. Les chemins localisés sont générés par les métadonnées du site et traduits à l’edge par le Worker de traduction.

Après avoir ajouté ou mis à jour la documentation d’un plugin :

  1. Compiler le site localement:

    Fenêtre de terminal
    bun run build
  2. Vérifier les erreurs:

    • Vérifier que tous les liens fonctionnent
    • S'assurer que les images se chargent correctement
    • Confirmer que les exemples code sont valides
    • Tester la navigation
  3. Prévisualiser le site:

    Fenêtre de terminal
    bun run dev
  4. Vérifier que votre plugin apparaît:

    • Vérifier la page de listing des plugins
    • Vérifier la navigation latérale
    • Tester toutes les pages de documentation
    • Vérifier que la page du tutoriel fonctionne

Besoin d’aide pour ajouter ou mettre à jour la documentation d’un plugin ?

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épart)
  • Connexion sociale: /src/content/docs/docs/plugins/social-login/ (plugin avec sous-pages)

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

  1. Ajout de métadonnées à la configuration principale
  2. Ajouter le plugin à la page d'index par catégories
  3. Configuration de la navigation latérale
  4. Créer des pages de documentation complètes
  5. Rédiger un tutoriel détaillé
  6. Tester tous les changements en local

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

Continuer après l'ajout ou la mise à jour de plugins

Section intitulée « Continuer après l'ajout ou la mise à jour de plugins »

Si vous utilisez Ajouter ou mettre à jour des plugins pour planifier le travail sur les plugins natifs, connectez-l’à Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, Capgo Native Build pour le flux de travail du produit dans Capgo Native Builds, et Plugins Capacitor : ce que vous devez savoir pour le contexte pratique dans Capacitor Plugins : ce qu'il faut savoir.