Agregue o actualice plugins

Esta guía explica cómo agregar nuevos plugins Capacitor a la página web Capgo o actualizar la documentación de plugins existentes. Esto es útil para contribuyentes, mantenedores y agentes de IA que ayudan a mantener la documentación.

Resumen

Al agregar un nuevo plugin al ecosistema Capgo, debe actualizar varios archivos y ubicaciones en el sitio web para asegurarse de que el plugin se muestre correctamente en todos los lugares relevantes:

1. Configuración de la lista de plugins - Agregar metadatos del plugin a la lista principal
2. Página de índice de plugins - Agregar plugin a la página de lista de plugins categorizados
3. Navegación en el lateral - Agregar plugin a la página de documentación en el lateral
4. Documentación del plugin - Crear páginas de resumen y de inicio rápido
5. Tutoriales del plugin - Crear un tutorial integral

Ubicaciones de archivos

Archivos clave para actualizar

Archivo	Propósito
/src/config/plugins.ts	Lista maestra de plugins con metadatos
/src/content/docs/docs/plugins/index.mdx	Página de índice de plugins con categorías
/astro.config.mjs	Configuración de navegación en el lateral
/src/content/docs/docs/plugins/[plugin-name]/	Directorio de documentación de plugins
/src/content/plugins-tutorials/en/	Archivos de tutoriales en inglés

Guía paso a paso

1. Agregar Plugin a la Lista Principal

   Abrir /src/config/plugins.ts y agregar tu plugin a la 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,
   }

   Iconos Disponibles: Ver /node_modules/astro-heroicons/mini/ iconos disponibles.

2. Agregar Plugin a la Página de Índice

   Abre /src/content/docs/docs/plugins/index.mdx y agrega tu plugin en la categoría adecuada:

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

   Categorías:

   • Plugins destacados ⭐
   • Plugins de dispositivos y sistemas 📱
   • Plugins de medios y cámara 🎥
   • Plugins de utilidad 🛠️
   • Plugins de inteligencia artificial y medios avanzados 🤖
   • Plugins de ubicación y servicios de fondo 📍
   • Plugins de comunicación y análisis 📞
   • Plugins de seguridad y sistema 🔐
   • Características específicas de Android 📊
   • Descargar & Navegación 📥

3. Agregar a Navegación de Lado

   Abrir /astro.config.mjs y agregar su plugin a la configuración de la barra lateral (alrededor de la línea 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,
   }

   Los plugins se enumeran alfabéticamente en la barra lateral.

4. Crear Directorio de Documentación del Plugin

   Crear un nuevo directorio para la documentación de su plugin:

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

5. Crear página de resumen del plugin

   Crear /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. Crear guía de inicio rápido

   Crear /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. Crear archivo de tutoría

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

Estructura de la documentación del plugin

Archivos requeridos

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

Archivos opcionales

Para plugins complejos, puede agregar páginas de documentación adicionales:

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

Directrices de contenido

Descripciones de Plugins

• Ser Conciso: Mantenga las descripciones bajo 100 caracteres
• Ser Preciso: Explique qué hace el plugin, no qué es
• Usar Verbos de Acción: Comience con verbos como “Control”, “Integre”, “Habilite”

Ejemplos Buenos:

• “Control la luz del dispositivo y la linterna con un simple interruptor de encendido/apagado”
• “Integre el chat en vivo de Crisp y el soporte al cliente en su aplicación”
• “Habilite la autenticación segura utilizando Face ID y Touch ID”

Ejemplos Malos:

• “Un plugin para flash”
• “Este es un plugin de Crisp”
• “Plugin de biometría”

Redactar Documentación

1. Iniciar con la Instalación: Siempre comienza con pasos de instalación claros
2. Proporcionar Configuración: Incluye requisitos de configuración específicos de plataforma
3. Mostrar Ejemplos de Uso: Proporciona ejemplos de trabajo code
4. Incluir API Reference: Documentar todos los métodos y parámetros
5. Agregar Ejemplos Completos: Mostrar patrones de uso en el mundo real
6. Lista de Mejores Prácticas: Compartir consejos para un uso óptimo
7. Documentar Diferencias de Plataforma: Aclarar el comportamiento de iOS vs Android
8. Agregar Solución de Problemas: Abordar problemas comunes

Code Ejemplos

• Use code con TypeScript para todos los ejemplos
• Incluir importaciones en la parte superior
• Agregar comentarios explicando los pasos clave
• Mostrar manejo de errores
• Demonstrar tanto el uso básico como avanzado

Lista de verificación

Utilice esta lista de verificación al agregar un nuevo plugin:

• Plugin agregado a /src/config/plugins.ts
• Seleccionó el icono adecuado de Heroicons
• Plugin agregado a /src/content/docs/docs/plugins/index.mdx en la categoría correcta
• Agregó entrada lateral en /astro.config.mjs
• Creó directorio de documentación del plugin
• Creó index.mdx página de visión general
• Creó getting-started.mdx guía
• Creó tutoriales en /src/content/plugins-tutorials/en/
• Incluyó instrucciones de instalación
• Documentó configuración de iOS
• Documentó configuración de Android
• Proporcionó ejemplos de uso
• Agregó referencia a API
• Ejemplo de trabajo completo incluido
• Se listan las mejores prácticas
• Se agregan notas específicas de plataforma
• Se prueban todos los enlaces para que funcionen correctamente

Referencia de iconos

Iconos comunes utilizados para plugins (desde astro-heroicons/mini/):

Icono	Uso
BoltIcon	Flash, energía, potencia
CameraIcon	Cámara, foto, video
ChatBubbleLeftIcon	Chat, mensajería, comunicación
FingerPrintIcon	Autenticación, seguridad, biometría
MapPinIcon	Ubicación, geolocalización, mapas
SpeakerWaveIcon	Audio, sonido, música
VideoCameraIcon	Video, grabación, streaming
CreditCardIcon	Pagos, compras
PlayCircleIcon	Reproductores de medios, reproductores de video
SignalIcon	Conectividad, red, beacon
RadioIcon	Beacon, emisión, inalámbrico
ChatBubbleOvalLeftIcon	Redes sociales, WeChat

Actualizando Plugins Existentes

Cuando se actualiza un plugin existente:

1. Actualice los números de versión en la documentación
2. Agregue guías de migración si existen cambios que rompen la compatibilidad
3. Actualice la referencia a API con nuevos métodos
4. Agregue nuevos ejemplos para nuevas características
5. Actualice los requisitos del plataforma si han cambiado
6. Revisar las mejores prácticas basadas en nuevas características
7. Mantén actualizado el tutorial con el último API

Rutas de idioma

Escreba y revise la documentación del plugin en inglés. Las rutas localizadas se generan mediante los metadatos del sitio y se traducen en la nube por el trabajador de traducción.

Prueba tus cambios

Después de agregar o actualizar la documentación del plugin:

1. Construye el sitio localmente:

   bun run build

2. Revisa errores:

   • Verificar que todos los enlaces funcionen
   • Asegurarse de que las imágenes se carguen correctamente
   • Confirmar que los ejemplos de code sean válidos
   • Probar que la navegación funciona

3. Previsualizar el sitio:

   bun run dev

4. Verificar que su plugin aparece:

   • Revisar la página de lista de plugins
   • Verificar la navegación del lado izquierdo
   • Probar todas las páginas de documentación
   • Confirmar que la página de tutoriales funciona

Trampas comunes

Cuidado

Evite estos errores comunes:

1. Olvidar sincronizar: Siempre ejecuta bunx cap sync en ejemplos
2. Nombre inconsistente: Utilice el mismo nombre de plugin en todas partes
3. Falta de configuración de plataforma: Documente tanto la configuración de iOS como la de Android
4. Enlaces rotos: Utiliza enlaces relativos y verifica que funcionen
5. Falta de manejo de errores: Siempre muestra try-catch en los ejemplos
6. Falta de importaciones: Incluye todas las importaciones necesarias en los ejemplos
7. Descripciones ambiguas: Sé específico sobre qué hace el plugin

Obtener Ayuda

Si necesitas ayuda para agregar o actualizar la documentación del plugin:

• Discord: Únete a nuestra comunidad de Discord Comunidad de Discord
• GitHub: Abre una incidencia en el repositorio del sitio web Repositorio del sitio web
• Correo electrónico: Contacta con el equipo en support@capgo.app

Ejemplos

Para referencia, revisa estos plugins bien documentados:

• Actualizador: /src/content/docs/docs/plugins/updater/ plugin complejo con varias páginas
• Flash: /src/content/docs/docs/plugins/flash/ plugin simple, buen ejemplo de inicio
• Iniciar sesión en redes sociales: /src/content/docs/docs/plugins/social-login/ Resumen

Sección titulada “Resumen”

Adding a plugin to the Capgo documentation involves:

1. Agregar el plugin a la página de índice categorizado
2. Configurar la navegación en el menú lateral
3. Crear páginas de documentación integral
4. Configurar la navegación en el menú lateral
5. Escribiendo un tutorial detallado
6. Probando todas las modificaciones localmente

Al seguir esta guía, asegúrate de que los complementos estén consistentemente documentados y sean fácilmente descubribles por los usuarios.

Sigue adelante desde Agregar o Actualizar Complementos

Si estás utilizando Agregando o Actualizando Complementos para planificar el trabajo de complemento nativo, conecta con Capgo Directorio de Complementos para el flujo de trabajo del producto en Capgo Directorio de Complementos, Capacitor Complementos por Capgo para el detalle de implementación en Capacitor Complementos por Capgo Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise, Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas, y Capacitor Plugins: Lo que Necesitas Saber para el contexto práctico en Capacitor Plugins: Lo que Necesitas Saber.