Plugins hinzufügen oder aktualisieren

Dieses Leitfaden erklärt, wie man neue Capacitor-Plugins zur Capgo-Website hinzufügt oder bestehende Plugin-Dokumentation aktualisiert. Dies ist nützlich für Beiträger, Maintainer und KI-Agenten, die dabei helfen, die Dokumentation zu pflegen.

Übersicht

Wenn Sie ein neues Plugin in das Capgo-Ökosystem hinzufügen, müssen Sie mehrere Dateien und Orte auf der Website aktualisieren, um sicherzustellen, dass das Plugin in allen relevanten Bereichen richtig angezeigt wird:

1. Konfiguration des Plugin-Listen - Hinzufügen von Plugin-Metadaten zur Masterliste
2. Plugin-Index-Seite - Hinzufügen des Plugins zur kategorierte Plugin-Auflistung
3. Seitenleiste-Navigation - Plugin zur Dokumentationsleiste hinzufügen
4. Plugin-Dokumentation - Überblicks- und Anfängerschritte erstellen
5. Plugin-Tutorial - Umfassendes Tutorial erstellen

Dateilagen

Wichtige Dateien zum Aktualisieren

Datei	Zweck
/src/config/plugins.ts	Haupt-Plugin-Liste mit Metadaten
/src/content/docs/docs/plugins/index.mdx	Plugin-Index-Seite mit Kategorien
/astro.config.mjs	Konfiguration der Seitenleiste für die Navigation
/src/content/docs/docs/plugins/[plugin-name]/	Verzeichnis für Plugin-Dokumentation
/src/content/plugins-tutorials/en/	Englische Tutorial-Dateien

Schritt-für-Schritt-Anleitung

1. Hinzufügen von Plugin zur Masterliste

   Öffnen /src/config/plugins.ts und fügen Sie Ihr Plugin zur actions __CAPGO_KEEP_0__

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

   Verfügbare Icons: Überprüfen /node_modules/astro-heroicons/mini/ Für verfügbare Icons.

2. Hinzufügen zum Index-Seiten

   Öffnen /src/content/docs/docs/plugins/index.mdx und fügen Sie Ihr Plugin unter der entsprechenden Kategorie ein:

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

   Kategorien:

   • ⭐ Hervorhebungs-Plugins
   • 📱 Geräte- und System-Plugins
   • 🎥 Medien- und Kamera-Plugins
   • 🛠️ Hilfsfunktionen
   • 🤖 KI & Advanced Media
   • 📍 Standort & Hintergrunddienste
   • 📞 Kommunikation & Analytics
   • 🔐 Sicherheit & System
   • 📊 Android-Spezifische Funktionen
   • 📥 Herunterladen & Navigation

3. Zum Seitenleisten-Navigation hinzufügen

   Öffnen /astro.config.mjs und fügen Sie Ihren Plugin zur Seitenleisten-Konfiguration (um Zeile 540 herum) hinzu:

   {
     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 werden alphabetisch in der Seitenleiste aufgelistet.

4. Erstellen Sie den Plugin-Dokumentationsordner

   Erstellen Sie einen neuen Ordner für Ihre Plugin-Dokumentation:

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

5. Erstellen Sie die Übersichtsseite für Ihr Plugin

   Erstellen /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. Erstellen Sie eine Anleitung für den Einstieg

   Erstellen /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. Tutorial-Datei erstellen

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

Struktur der Plugin-Dokumentation

Erforderliche Dateien

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

Optional Dateien

Für komplexe Plugins können Sie zusätzliche Dokumentationsseiten hinzufügen:

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

Richtlinien für Inhalte

Erstellung von Pluginbeschreibungen

• Seien Sie Bündig: Beschreibungen sollten unter 100 Zeichen bleiben
• Seien Sie Spezifisch: Erklären Sie, was das Plugin tut, und nicht, was es ist
• Verwenden Sie Handlungsverben: Beginnen Sie mit Verben wie „Steuerung“, „Integrations“ und „Aktivieren“

Beispiele:

• „Steuerung des Geräte-Flash und der Taschenlampe mit einfacher Ein/Aus-Schaltfläche“
• „Integrieren Sie Crisp-Lebenslauf und Kundenunterstützung in Ihre App“
• „Aktivieren Sie sichere Authentifizierung mit Face ID und Touch ID“

Fehlerbeispiele:

• „Ein Plugin für Flash“
• „Dies ist ein Crisp-Plugin“
• „Biometrisches Plugin“

Dokumentation schreiben

1. Beginnen Sie mit der Installation: Beginnen Sie immer mit klaren Installationsanweisungen
2. Konfiguration bereitstellen: Fügen Sie Plattform-spezifische Einrichtungsanforderungen hinzu
3. Zeigen Sie Beispiele für die Verwendung an: Bieten Sie funktionierende code-Beispiele an
4. Fügen Sie API-Referenz hinzu: Dokumentieren Sie alle Methoden und Parameter
5. Fügen Sie vollständige Beispiele hinzu: Zeigen Sie realistische Verwendungsmuster an
6. Listen Sie die besten Praktiken auf: Teilen Sie Tipps für den optimalen Einsatz
7. Dokumentieren Sie Plattform-spezifische Unterschiede: iOS- und Android-Verhalten klären
8. Hinzufügen von Fehlersuche: Häufige Probleme angehen

Code Beispiele

• Verwenden von TypeScript für alle code Beispiele
• Importe am Anfang einfügen
• Hinzufügen von Kommentaren, die wichtige Schritte erklären
• Fehlerbehandlung zeigen
• Beide grundlegende und fortgeschrittene Verwendung demonstrieren

Überprüfungsliste

Verwenden Sie diese Liste, wenn Sie ein neues Plugin hinzufügen:

• Hinzugefügtes Plugin zu /src/config/plugins.ts
• Wählte geeigneten Icon aus Heroicons
• Hinzugefügtes Plugin zu /src/content/docs/docs/plugins/index.mdx unter der richtigen Kategorie
• Hinzugefügtes Eintrag in die Sidebar /astro.config.mjs
• Erstellte Verzeichnis für Plugin-Dokumentation
• Erstellte index.mdx Übersichtsseite
• Erstellte getting-started.mdx Richtlinie
• Erstellte Tutorial in /src/content/plugins-tutorials/en/
• Eingeschlossene Installationsanweisungen
• Dokumentierte iOS-Konfiguration
• Dokumentierte Android-Konfiguration
• Bereitgestellte Verwendungsexempel
• Hinzugefügter API-Verweis
• Eingeschlossenes vollständiges Arbeitsbeispiel
• Aufgelistete Best Practices
• Hinzugefügte Plattform-spezifische Hinweise
• Alle Links korrekt getestet

Icon-Referenz

Gemeinsam verwendete Icons für Plugins (aus astro-heroicons/mini/):

Symbol	Anwendungsbereich
BoltIcon	Blitz, Energie, Kraft
CameraIcon	Kamera, Foto, Video
ChatBubbleLeftIcon	Chat, Nachrichten, Kommunikation
FingerPrintIcon	Biometrische, Sicherheit, Authentifizierung
MapPinIcon	Ort, Standort, Karten
SpeakerWaveIcon	Audio, Ton, Musik
VideoCameraIcon	Video, Aufzeichnung, Streaming
CreditCardIcon	Zahlungen, Kauf
PlayCircleIcon	Mediaplayer, Videoplayer
SignalIcon	Verbindung, Netzwerk, Beacon
RadioIcon	Beacon, broadcast, wireless
ChatBubbleOvalLeftIcon	Soziale Medien, WeChat

Bestehende Plugins aktualisieren

Wenn ein bestehender Plugin aktualisiert wird:

1. Versionen aktualisieren in der Dokumentation
2. Migrationstutorials hinzufügen wenn sich Änderungen ergeben
3. Update API reference mit neuen Methoden
4. Neue Beispiele hinzufügen für neue Funktionen
5. Plattformanforderungen aktualisieren wenn geändert
6. Best Practices anpassen basierend auf neuen Funktionen
7. Tutorial auf dem neuesten Stand halten mit den neuesten API

Sprachpfade

Plugin-Dokumentation in Englisch schreiben. Lokalisierte Pfade werden durch die Site-Metadaten generiert und an der Edge durch den Übersetzungswerker übersetzt.

Ihre Änderungen testen

Nachdem Sie eine oder mehrere Plugin-Dokumentationen hinzugefügt oder aktualisiert haben:

1. Bauen Sie das Site lokal:

   bun run build

2. Überprüfen Sie auf Fehler:

   • Stellen Sie sicher, dass alle Links funktionieren
   • Stellen Sie sicher, dass Bilder korrekt geladen werden
   • Bestätigen Sie, dass code-Beispiele gültig sind
   • Überprüfen Sie, ob die Navigation funktioniert

3. Vorschau der Site:

   bun run dev

4. Überprüfen Sie, ob Ihr Plugin erscheint:

   • Überprüfen Sie die Plugin-Verzeichnisseite
   • Überprüfen Sie die Seitenleiste
   • Testen Sie alle Dokumentationsseiten
   • Bestätigen Sie, dass die Tutorial-Seite funktioniert

Gemeinsame Fallstricke

Vorsicht

Vermeiden Sie diese häufigen Fehler:

1. Vergessen Sie, synchron zu machen: Immer ausführen bunx cap sync in Beispielen
2. Inkonsistente Namensgebung: Verwende überall denselben Pluginnamen
3. Fehlende Plattform-Konfiguration: Dokumentiere sowohl die iOS- als auch die Android-Einrichtung
4. Gebrochene Links: Verwende relative Links und überprüfe, ob sie funktionieren
5. Keine Fehlerbehandlung: Zeige immer try-catch in Beispielen an
6. Fehlende Importe: Fügen Sie alle notwendigen Importe in Beispielen ein
7. Unklare Beschreibungen: Seien Sie spezifisch über das, was der Plugin hinzufügt

Unterstützung erhalten

Wenn Sie Hilfe bei der Hinzufügung oder Aktualisierung der Plugin-Dokumentation benötigen:

• Discord: Beitritt zu unserem Discord-Community
• GitHub: Öffnen Sie ein Issue im Repository der Website
• Email: Kontaktieren Sie das Team unter support@capgo.app

Beispiele

Zur Referenz prüfen Sie diese gut dokumentierten Plugins:

• Updater: /src/content/docs/docs/plugins/updater/ (komplexer Plugin mit mehreren Seiten)
• Flash: /src/content/docs/docs/plugins/flash/ (einfaches Plugin, gute Anfangsbeispiel)
• Social Login: /src/content/docs/docs/plugins/social-login/ (Plugin mit Unterseiten)

Zusammenfassung

Ein Plugin zur Capgo Dokumentation hinzufügen beinhaltet:

1. Metadaten zur Master-Konfiguration hinzufügen
2. Das Plugin zur kategoriellen Index-Seite hinzufügen
3. Die Seitenleiste konfigurieren
4. Umfangreiche Dokumentationsseiten erstellen
5. Ein detailliertes Tutorial schreiben
6. Alle Änderungen lokal testen

Durch das Befolgen dieser Anleitung stellen Sie sicher, dass Plugins konsistent dokumentiert und leicht von Benutzern auffindbar sind.

Weitergehen von Plugins hinzufügen oder aktualisieren

Wenn Sie Plugins hinzufügen oder aktualisieren für die native Plugin-Arbeit zu planen, verbinden Sie es mit Capgo Plugin-Verzeichnis für den Produktworkflow in Capgo Plugin-Verzeichnis Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo, Ionic Enterprise Plugin Alternativen für den Produktworkflow in Ionic Enterprise Plugin Alternativen Capgo Native Builds für den Produktworkflow in Capgo Native Builds und Capacitor Plugins: Was Sie wissen müssen für den praktischen Kontext in Capacitor Plugins: Was Sie wissen müssen.