Plugins hinzufügen oder aktualisieren

Diese Anleitung erklärt, wie du neue Capacitor Plugins zur Capgo Website hinzufügst oder bestehende Plugin-Dokumentation aktualisierst. Das ist nützlich für Contributors, Maintainer und KI-Agenten, die helfen, die Dokumentation zu pflegen.

Übersicht

Wenn du ein neues Plugin zum Capgo Ökosystem hinzufügst, musst du mehrere Dateien und Stellen auf der Website aktualisieren, damit das Plugin an allen relevanten Stellen korrekt angezeigt wird:

1. Plugin-Listen-Konfiguration - Plugin-Metadaten zur Master-Liste hinzufügen
2. Plugin-Indexseite - Plugin zur kategorisierten Plugin-Übersichtsseite hinzufügen
3. Sidebar-Navigation - Plugin zur Dokumentations-Sidebar hinzufügen
4. Plugin-Dokumentation - Übersichts- und Getting-started-Seiten erstellen
5. Plugin-Tutorial - Ein umfassendes Tutorial erstellen

Dateispeicherorte

Wichtige Dateien zum Aktualisieren

Datei	Zweck
/src/config/plugins.ts	Master-Pluginliste mit Metadaten
/src/content/docs/docs/plugins/index.mdx	Plugin-Indexseite mit Kategorien
/astro.config.mjs	Konfiguration der Sidebar-Navigation
/src/content/docs/docs/plugins/[plugin-name]/	Plugin-Dokumentationsverzeichnis
/src/content/plugins-tutorials/en/	Englische Tutorial-Dateien

Schritt-für-Schritt-Anleitung

1. Plugin zur Master-Liste hinzufügen

   Öffne /src/config/plugins.ts und füge dein Plugin zum actions Array hinzu:

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

2. Plugin zur Index-Seite hinzufügen

   Öffne /src/content/docs/docs/plugins/index.mdx und füge dein Plugin der passenden Kategorie hinzu:

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

   Kategorien:

   • ⭐ Empfohlene Plugins
   • 📱 Device- & System-Plugins
   • 🎥 Media- & Kamera-Plugins
   • 🛠️ Utility-Plugins
   • 🤖 KI & Advanced Media
   • 📍 Standort & Hintergrunddienste
   • 📞 Kommunikation & Analytics
   • 🔐 Sicherheit & System
   • 📊 Android-spezifische Features
   • 📥 Download & Navigation

3. Zur Sidebar-Navigation hinzufügen

   Öffne /astro.config.mjs und füge dein Plugin zur Sidebar-Konfiguration hinzu (ca. Zeile 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 werden in der Sidebar alphabetisch aufgelistet.

4. Plugin-Dokumentationsverzeichnis erstellen

   Erstelle ein neues Verzeichnis für deine Plugin-Dokumentation:

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

5. Plugin-Übersichtsseite 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. Getting Started Guide erstellen

   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

Optionale Dateien

Bei komplexen Plugins kannst du weitere 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

Content-Richtlinien

Plugin-Beschreibungen schreiben

• Kurz fassen: Beschreibungen unter 100 Zeichen halten
• Präzise sein: Erkläre, was das Plugin tut, nicht was es ist
• Aktionsverben nutzen: Beginne mit Verben wie „Steuern“, „Integrieren“, „Ermöglichen“

Gute Beispiele:

• „Steuere die Taschenlampe des Geräts mit einem einfachen On/Off-Toggle“
• „Integriere Crisp Live-Chat und Kundensupport in deine App“
• „Ermögliche sichere Authentifizierung via Face ID und Touch ID“

Schlechte Beispiele:

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

Dokumentation schreiben

1. Beginne mit der Installation: Beginne immer mit klaren Installationsschritten
2. Konfiguration bereitstellen: Plattformspezifische Setup-Anforderungen angeben
3. Nutzungsbeispiele zeigen: Funktionierende code Beispiele bereitstellen
4. API Referenz einbinden: Alle Methoden und Parameter dokumentieren
5. Vollständige Beispiele hinzufügen: Praxisnahe Nutzungsmuster zeigen
6. Best Practices auflisten: Tipps für die optimale Nutzung teilen
7. Plattformunterschiede dokumentieren: Verhalten von iOS vs. Android klären
8. Troubleshooting hinzufügen: Häufige Probleme beheben

Code Beispiele

• Verwende TypeScript für alle code Beispiele
• Imports ganz oben einfügen
• Kommentare zu wichtigen Schritten hinzufügen
• Error Handling zeigen
• Sowohl Basis- als auch fortgeschrittene Nutzung zeigen

Checkliste

Nutze diese Checkliste beim Hinzufügen eines neuen Plugins:

• Plugin hinzugefügt zu /src/config/plugins.ts
• Passendes Icon aus Heroicons ausgewählt
• Plugin hinzugefügt zu /src/content/docs/docs/plugins/index.mdx unter der richtigen Kategorie
• Sidebar-Eintrag in /astro.config.mjs
• Plugin-Dokumentationsverzeichnis erstellt
• Erstellt index.mdx Übersichtsseite
• Erstellt getting-started.mdx Guide
• Tutorial in erstellt /src/content/plugins-tutorials/en/
• Installationsanleitung hinzugefügt
• iOS-Konfiguration dokumentiert
• Android-Konfiguration dokumentiert
• Anwendungsbeispiele bereitgestellt
• API-Referenz hinzugefügt
• Vollständiges funktionierendes Beispiel enthalten
• Best Practices aufgelistet
• Plattformspezifische Hinweise hinzugefügt
• Getestet, dass alle Links funktionieren

Icon-Referenz

Häufig verwendete Icons für Plugins (aus astro-heroicons/mini/):

Icon	Anwendungsfall
BoltIcon	Blitz, Strom, Energie
CameraIcon	Kamera, Foto, Video
ChatBubbleLeftIcon	Chat, Messaging, Kommunikation
FingerPrintIcon	Biometrie, Sicherheit, Authentifizierung
MapPinIcon	Standort, Geolocation, Maps
SpeakerWaveIcon	Audio, Sound, Musik
VideoCameraIcon	Video, Aufnahme, Streaming
CreditCardIcon	Zahlungen, Käufe
PlayCircleIcon	Media Player, Videoplayer
SignalIcon	Konnektivität, Netzwerk, Beacon
RadioIcon	Beacon, Broadcast, Wireless
ChatBubbleOvalLeftIcon	Social Media, WeChat

Bestehende Plugins aktualisieren

Wenn du ein bestehendes Plugin aktualisierst:

1. Versionsnummern aktualisieren in der Dokumentation
2. Migration Guides hinzufügen falls Breaking Changes vorliegen
3. API Referenzen aktualisieren mit neuen Methoden
4. Neue Beispiele hinzufügen für neue Features
5. Plattform-Anforderungen aktualisieren falls geändert
6. Best Practices überarbeiten basierend auf neuen Features
7. Tutorials aktuell halten mit dem neuesten API

Sprachpfade

Schreibe und prüfe Plugin-Docs auf Englisch. Lokalisierte Pfade werden über die Website-Metadaten generiert und durch den Translation Worker am Edge übersetzt.

Änderungen testen

After adding or updating plugin documentation:

1. Die Website lokal builden:

   bun run build

2. Auf Fehler prüfen:

   • Alle Links auf Funktion prüfen
   • Sicherstellen, dass Bilder korrekt laden
   • Prüfen, ob die code-Beispiele gültig sind
   • Prüfen, ob die Navigation funktioniert

3. Website-Vorschau ansehen:

   bun run dev

4. Prüfen, ob dein Plugin erscheint:

   • Plugin-Übersichtsseite prüfen
   • Sidebar-Navigation prüfen
   • Alle Dokumentationsseiten testen
   • Tutorial-Seite auf Funktion prüfen

Häufige Fehler

Achtung

Vermeide diese typischen Fehler:

1. Sync vergessen: Immer ausführen bunx cap sync in Beispielen
2. Inkonsistente Benennung: Verwende überall denselben Plugin-Namen
3. Fehlende Plattform-Konfiguration: Dokumentiere das Setup für iOS und Android
4. Defekte Links: Nutze relative Links und prüfe deren Funktion
5. Keine Fehlerbehandlung: Zeige in Beispielen immer try-catch
6. Fehlende Imports: Füge alle notwendigen Imports in die Beispiele ein
7. Unklare Beschreibungen: Beschreibe präzise, was das Plugin macht

Hilfe erhalten

Wenn du Hilfe beim Hinzufügen oder Aktualisieren der Plugin-Dokumentation benötigst:

• Discord: Komm in unseren Discord-Community
• GitHub: Erstelle ein Issue im Website-Repository
• E-Mail: Kontaktiere das Team unter support@capgo.app

Beispiele

Zur Orientierung findest du hier gut dokumentierte Plugins:

• Updater: /src/content/docs/docs/plugins/updater/ (komplexes Plugin mit mehreren Seiten)
• Flash: /src/content/docs/docs/plugins/flash/ (einfaches Plugin, ideal als Einstieg)
• Social Login: /src/content/docs/docs/plugins/social-login/ (Plugin mit Unterseiten)

Zusammenfassung

Um ein Plugin zur Capgo Dokumentation hinzuzufügen, gehen Sie wie folgt vor:

1. Metadaten zur Master-Konfiguration hinzufügen
2. Plugin zur kategorisierten Indexseite hinzufügen
3. Sidebar-Navigation konfigurieren
4. Umfassende Dokumentationsseiten erstellen
5. Ein detailliertes Tutorial schreiben
6. Alle Änderungen lokal testen

Mit diesem Guide stellst du sicher, dass Plugins konsistent dokumentiert und für Nutzer leicht auffindbar sind.

Weiterlesen nach Plugins hinzufügen oder aktualisieren

Wenn du es nutzt Plugins hinzufügen oder aktualisieren Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow in Ionic Enterprise Plugin-Alternativen, Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds, und Capacitor Plugins: Das musst du wissen für den praktischen Kontext in Capacitor Plugins: Was du wissen musst.