Hinzufügen oder Aktualisieren von Plugins

This guide explains how to add new Capacitor plugins to the Capgo website or update existing plugin documentation. This is useful for contributors, maintainers, and AI agents helping to maintain the documentation.

Abschnitt mit dem Titel „Übersicht“

When adding a new plugin to the Capgo ecosystem, you need to update several files and locations across the website to ensure the plugin appears correctly in all relevant places:

1. - Plugin-Metadaten zur Masterliste hinzufügen Plugin List Configuration
2. Plugin-Index-Seite - Plugin zur kategoriellen Plugin-Verzeichnisseite hinzufügen
3. Navi-Sidebar - Plugin zur Dokumentations-Sidebar hinzufügen
4. Plugin-Dokumentation - Übersichts- und Anfängerschritte erstellen
5. Plugin-Tutorial - Umfassenden Tutorial erstellen

Dateilagen

Schlüssel-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
/src/content/docs/docs/plugins/[plugin-name]/	Plugin-Dokumentationsverzeichnis
/src/content/plugins-tutorials/en/	Englische Tutorial-Dateien

Schritt-für-Schritt-Anleitung

1. Hinzufügen von Plugins zur Hauptliste

   Öffnen /src/config/plugins.ts und fügen Sie Ihr Plugin zu den 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 Icons: Überprüfen Sie /node_modules/astro-heroicons/mini/ für verfügbare Icons.

2. Hinzufügen von Plugin zur Indexseite

   Ö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- und System-Plugins
   • 🎥 Medien- und Kamera-Plugins
   • 🛠️ Werkzeug-Plugins
   • 🤖 KI- und fortgeschrittene Medien
   • 📍 Standort- und Hintergrunddienste
   • 📞 Kommunikation und Analytics
   • 🔐 Sicherheit und System
   • 📊 Android-spezifische Funktionen
   • 📥 Herunterladen und Navigation

3. Zum Seitenleisten-Navigation hinzufügen

   Öffnen /astro.config.mjs und fügen Sie Ihre Erweiterung der Seitenleiste-Konfiguration (um die 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,
   }

   Die Erweiterungen werden alphabetisch in der Seitenleiste aufgelistet.

4. Verzeichnis für Plugin-Dokumentation erstellen

   Einen neuen Ordner für Ihre Plugin-Dokumentation erstellen:

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

5. Übersichtsseite für Plugin 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 für Anfänger

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

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

Inhaltliche Richtlinien

Pluginbeschreibungen schreiben

• Seien Sie knapp: Beschreibungen sollten unter 100 Zeichen bleiben
• Sei Spezifisch: Erkläre, was das Plugin tut, nicht was es ist
• Verwende Handlungsverben: Beginne mit Verben wie „Steuerung“, „Integration“, „Aktivierung"

Gute Beispiele:

• “Steuerung des Geräte-Blitzlichts und des Taschenlampenlichts mit einfacher Ein/Aus-Schaltfläche”
• “Integriere Crisp-Lebenslauf und Kundenunterstützung in deine App”
• “Aktiviere sichere Authentifizierung mit Face ID und Touch ID”

Schlechte Beispiele:

• “Ein Plugin für Blitzlicht”
• “Dies ist ein Crisp-Plugin”
• “Biometrisches Plugin”

Dokumentation schreiben

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. API Referenz einbeziehen: Dokumentieren Sie alle Methoden und Parameter
5. Komplette Beispiele hinzufügen: Zeigen Sie realistische Verwendungsmuster
6. Liste der Best Practices: Teile Tipps für den optimalen Einsatz
7. Dokumentiere Plattformunterschiede: Kläre iOS vs Android-Verhalten
8. Fügen Sie Fehlersuche hinzu: Beantworte häufige Probleme

Code Beispiele

• Verwenden Sie TypeScript für alle code-Beispiele
• Fügen Sie Importe an der Spitze hinzu
• Fügen Sie Kommentare hinzu, die wichtige Schritte erklären
• Zeigen Sie Fehlerbehandlung an
• Beide grundlegende und fortgeschrittene Verwendung demonstrieren

Checkliste

Verwenden Sie diese Checkliste, 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 der Seitenleiste in /astro.config.mjs
• Erstellte Plugin-Dokumentationsverzeichnis
• Erstellte index.mdx Übersichtsseite
• Erstellt getting-started.mdx Richtlinie
• Erstellte Anleitung in /src/content/plugins-tutorials/en/
• Eingeschlossene Installationsanweisungen
• Dokumentierte iOS-Konfiguration
• Dokumentierte Android-Konfiguration
• Bereitgestellte Verwendungsexempel
• Hinzugefügte API-Referenz
• Eingeschlossene vollständige Arbeitsbeispiel
• Aufgelistete besten Praktiken
• Hinzugefügte Plattform-spezifische Hinweise
• Getestet, dass alle Links korrekt funktionieren

Iconenverweis

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

Icon	Anwendungsbereich
BoltIcon	context
CameraIcon	Seite/ Bereich: Capgo-Lösungen-Marketingseite. Rolle: Kurzer UI-Label oder Navigationselement. Gesehen in: Seite Lösungen/Cordova-to-Capacitor-AI.astro. Nachrichtenschlüssel `solutions_cordova_to_capacitor_ai_table_use_case` (Lösungen Cordova To Capacitor Ai Tabelle Anwendungsbereich).
ChatBubbleLeftIcon	Blitz, Energie, Leistung
FingerPrintIcon	Kamera, Foto, Video
MapPinIcon	Chat, Nachrichten, Kommunikation
SpeakerWaveIcon	Biometrische Daten, Sicherheit, Authentifizierung
VideoCameraIcon	Ort, Geolocation, Kartenanzeige
CreditCardIcon	Zahlungen, Kaufabwicklung
PlayCircleIcon	Mediaplayer, Videoplayer
SignalIcon	Verbindung, Netzwerk, Beacon
RadioIcon	Beacon, Sendebroadcast, drahtlos
ChatBubbleOvalLeftIcon	Soziale Medien, WeChat

aktualisieren Sie bestehende Plugins

Wenn Sie ein bestehendes Plugin aktualisieren:

1. aktualisieren Sie Versionsnummern in der Dokumentation
2. Hinzufügen von Migrationen falls sich Änderungen ergeben
3. API Aktualisierung mit neuen Methoden
4. Hinzufügen neuer Beispiele zur Unterstützung neuer Funktionen
5. Plattformanforderungen aktualisieren falls geändert
6. Best Practices überarbeiten basierend auf neuen Funktionen
7. Halten Sie die Anleitung aktuell mit den neuesten API

Sprachpfade

Schreiben und überprüfen Sie die Plugin-Dokumentation auf Englisch. Lokalisierte Pfade werden durch die Site-Metadaten generiert und an der Edge durch den Übersetzungswerker übersetzt.

Deine Änderungen testen

Nachdem Sie Plugin-Dokumentation hinzugefügt oder aktualisiert haben:

1. Das Projekt lokal bauen:

   bun run build

2. Nach Fehlern suchen:

   • Überprüfen, ob 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 Website:

   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 Fehler

Vorsicht

Vermeide diese häufigen Fehler:

1. Vergiss nicht zu synchronisieren: Führe immer 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 Importe: Fügen Sie alle notwendigen Importe in Beispielen ein
7. Unklare Beschreibungen: Seien Sie spezifisch darüber, was das Plugin tut

Hilfe holen

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

• Discord: Beitritt zu unserer Discord-Gemeinschaft
• : GitHub: Öffnen Sie ein Issue auf dem Webseite-Repository
• E-Mail: Kontaktiere das Team unter support@capgo.app

Beispiele

Zum Verweisen: Überprü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, guter 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
4. Erstellen umfassender Dokumentationsseiten
5. Schreiben eines detaillierten Tutorials
6. Testen aller Änderungen lokal

Durch das Befolgen 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" verwenden Hinzufügen oder Aktualisieren von Plugins um 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 Ionische Unternehmenseigenen Plugin-Alternativen für den Produktworkflow in Ionische Unternehmenseigenen 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.