Hinzufügen oder Aktualisieren von Plugins

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

Übersicht

Wenn Sie ein neues Plugin in das Capgo-Ökosystem einfü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. Plugin-Listeneinstellungen - Hinzufügen von Plugin-Metadaten zur Masterliste
2. Plugin-Index-Seite - Plugin zur Kategorisierung hinzufügen
3. Seitenleiste - Plugin zur Seitenleiste hinzufügen
4. Plugin-Dokumentation - Überblicks- und Anfängerschritte erstellen
5. Tutorial zum Plugin - Umfassendes Tutorial erstellen

Dateilokationen

Dateien zum Aktualisieren

Datei	Zweck
/src/config/plugins.ts	Master-Plugin-Liste mit Metadaten
/src/content/docs/docs/plugins/index.mdx	Plugin-Index-Seite mit Kategorien
/astro.config.mjs	Konfiguration der Seitenleiste
/src/content/docs/docs/plugins/[plugin-name]/	Dokumentationsverzeichnis des Plugins
/src/content/plugins-tutorials/en/	englische Tutorial-Dateien

Schritt-für-Schritt-Anleitung

1. Hinzufügen von Plugin zur Master-Liste

   Öffnen /src/config/plugins.ts und fügen Sie Ihr Plugin der actions array:

   // 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 IconsCheck /node_modules/astro-heroicons/mini/ für verfügbare Icons.

2. Plugin zur Index-Seite hinzufügen

   Ö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:

   • ⭐ Hervorragende Plugins
   • Geräte- & System-Plugins
   • Medien- & Kamera-Plugins
   • Werkzeug-Plugins
   • Künstliche Intelligenz- & Advanced Media
   • Ort- & Hintergrunddienste
   • Kommunikation- & Analytics
   • Sicherheit- & System
   • Android-spezifische Funktionen
   • Herunterladen- & Navigation

3. Zum Seitenleisten-Navigation hinzufügen

   Öffnen /astro.config.mjs und fügen Sie Ihre Erweiterung zur Sidebar-Konfiguration (um die Zeile 540 herum) ein:

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

   Erweiterungen werden in der Sidebar alphabetisch aufgelistet.

4. Erweiterungsdokumentationsverzeichnis erstellen

   Erstellen Sie ein neues Verzeichnis für die Dokumentation Ihrer Erweiterung:

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

5. Erweiterungsvoransicht erstellen

   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. Erstelle Anleitung zum Starten

   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. Erstelle Tutorial-Datei

   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]

Dokumentationsstruktur des Plugins

Benötigte 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

Optionale 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

Inhaltliche Richtlinien

Beschreiben Sie Plugins

• Seien Sie BündigBeschreibungen sollten unter 100 Zeichen bleiben
• Seien Sie SpezifischBeschreiben Sie, was das Plugin tut, und nicht, was es ist
• Verwenden Sie HandlungsverbenBeginnen Sie mit Verben wie 'Steuerung', 'Integration', 'Aktivierung'

Gute Beispiele:

• ‚Steuerung des Geräte-Blitzlichts und des Taschenlampenlichts mit einfacher An/ Aus-Schalterfunktion‘
• ‚Integration der Crisp-Lebend-Chat- und Kundendienstfunktion in Ihre App‘
• ‚Aktivierung einer sicheren Authentifizierung mit Face ID und Touch ID‘

Schlechte Beispiele:

• ‚Ein Blitzlicht-Plugin‘
• ‚Dies ist ein Crisp-Plugin‘
• ‚Ein Biometrie-Plugin‘

Schreiben von Dokumentation

1. Mit der Installation beginnen: Beginnen Sie immer mit klaren Installationsanweisungen
2. Konfiguration bereitstellen: Fügen Sie Plattform-spezifische Einrichtungsanforderungen hinzu
3. Verwendung beispielhaft darstellen: Bereitstellen Sie funktionierende code Beispiele
4. Referenz mit API einbeziehen: Dokumentieren Sie alle Methoden und Parameter
5. Vollständige Beispiele hinzufügen: Zeigen Sie realistische Verwendungsmuster
6. Best Practices auflisten: Teile Tipps für optimale Verwendung
7. Dokumentiere Plattformunterschiede: Kläre das Verhalten von iOS gegenüber Android
8. Füge Fehlerbehebungsanleitungen hinzu: Beantworte häufige Probleme

Code Beispiele

• Verwende TypeScript für alle code Beispiele
• Füge Importe an der Spitze hinzu
• Füge Kommentare hinzu, die wichtige Schritte erklären
• Zeige Fehlerbehandlung
• Zeige sowohl grundlegende als auch fortgeschrittene Verwendung an

Überprüfungsliste

Verwende diese Überprüfungsliste, wenn du ein neues Plugin hinzufügst:

• 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 Seitenleiste /astro.config.mjs
• Erstellte Plugin-Dokumentationsverzeichnis
• Erstellte index.mdx Übersichtsseite
• Erstellte getting-started.mdx Leitfaden
• In /src/content/plugins-tutorials/en/
• Einstellungen installiert
• iOS-Konfiguration dokumentiert
• Android-Konfiguration dokumentiert
• Verwendung beispiel gegeben
• API Referenz hinzugefügt
• Vollständiges Arbeitsbeispiel enthalten
• Best Practices aufgelistet
• Plattform-spezifische Hinweise hinzugefügt
• Überprüft, dass alle Links korrekt funktionieren

Icon-Referenz

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

Icon	Verwendung
BoltIcon	Blitz, Strom, Energie
CameraIcon	Kamera, Foto, Video
ChatBubbleLeftIcon	Chat, Nachrichten, Kommunikation
FingerPrintIcon	Biometrische, Sicherheit, Authentifizierung
MapPinIcon	Ort, Geolocation, Karten
SpeakerWaveIcon	Audio, Ton, Musik
VideoCameraIcon	Video, Aufzeichnung, Streaming
CreditCardIcon	Zahlungen, Kauf
PlayCircleIcon	Multimedia-Player, Video-Player
SignalIcon	Verbindung, Netzwerk, Beacon
RadioIcon	Beacon, Übertragung, drahtlos
ChatBubbleOvalLeftIcon	Soziale Medien, WeChat

Bestehende Plugins aktualisieren

Wenn Sie ein bestehendes Plugin aktualisieren:

1. Versionen aktualisieren im Dokumentation
2. Migrationsanleitungen hinzufügen bei existierenden Änderungen
3. Update API-Referenz mit neuen Methoden
4. Neue Beispiele hinzufügen für neue Funktionen
5. Plattformanforderungen aktualisieren wenn geändert
6. Best Practices überarbeiten basierend auf neuen Funktionen
7. Tutorials halten aktuell 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.

Deine Änderungen testen

Nachdem du Dokumentation für Plugins hinzugefügt oder aktualisiert hast:

1. Das Projekt lokal bauen:

   bun run build

2. Fehler überprüfen:

   • Überprüfe, dass alle Links funktionieren
   • Stelle sicher, dass Bilder korrekt geladen werden
   • Bestätige, dass code-Beispiele gültig sind
   • Überprüfe, ob die Navigation funktioniert

3. Das Projekt voranschauen:

   bun run dev

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

   • Überprüfen Sie die Plugin-Listenseite
   • Überprüfen Sie die Seitenleiste
   • Testen Sie alle Dokumentationsseiten
   • Bestätigen Sie, dass die Tutorialseite funktioniert

Häufige Falle

Vorsicht

Vermeiden Sie diese häufigen Fehler:

1. Vergessen, synchronisiert zu werden: Immer ausführen bunx cap sync in Beispielen
2. Inkonsistente Namensgebung: Verwende überall denselben Plugin-Namen
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
6. Fehlende Imports: Alle notwendigen Importe in Beispielen einfügen
7. Unklare Beschreibungen: Seien Sie spezifisch darüber, was der Plugin tut

Hilfe finden

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

• Discord: Beitritt zu unserem Discord-Community
• GitHub: Öffnen Sie ein Issue im Repository des Websites
• E-Mail: Kontaktiere das Team bei 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)
• Soziale Anmeldung: /src/content/docs/docs/plugins/social-login/ (Plugin mit Unterseiten)

Zusammenfassung

Das Hinzufügen eines Plugins zur Capgo Dokumentation umfasst:

1. Hinzufügen von Metadaten zur Master-Konfiguration
2. Hinzufügen des Plugins zur kategoriellen Indexseite
3. Konfigurieren der Seitenleiste-Navigation
4. Erstellen umfassender Dokumentationsseiten
5. Schreiben eines detaillierten Tutorials
6. Testen aller Änderungen lokal

Durch das Folgen dieser Anleitung stellen Sie sicher, dass Plugins konsistent dokumentiert und leicht von Benutzern entdeckt werden können.

Weitergehen von Hinzufügen oder Aktualisieren von Plugins

Wenn Sie Hinzufügen oder Aktualisieren von Plugins für die Planung von nativen Plugin-Arbeiten, 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.