Agregar o actualizar plugins

Esta guía explica cómo agregar nuevos Capacitor plugins al sitio web de 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 de Capgo, necesita actualizar varios archivos y ubicaciones en el sitio web para asegurarse de que el plugin aparece correctamente en todos los lugares relevantes:

1. Configuración de la lista de plugins - Agregar metadatos del plugin a la lista maestra
2. Índice de Plugins - Agregar plugin a la página de lista de plugins categorizados
3. Navegación del Lado - Agregar plugin a la navegación del lado de la documentación
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	Objetivo
/src/config/plugins.ts	Lista de plugins maestros 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 menú 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 maestra

   Abrir /src/config/plugins.ts y agregar su 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: Verifique /node_modules/astro-heroicons/mini/ para los iconos disponibles.

2. Agregar Plugin a Página de Índice

   Abrir /src/content/docs/docs/plugins/index.mdx y agregar su 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 Dispositivo y Sistema
   • 🎥 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 y Navegación

3. Agregar a la Navegación de Lado

   Abrir /astro.config.mjs y agregar su plugin a la configuración del menú 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 en orden alfabético en el menú 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 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

Escribir Descripciones de Plugins

• Sé Conciso: Mantenga las descripciones debajo de 100 caracteres
• Sé Preciso: Explique qué hace el complemento, no qué es
• Usar Verbos de Acción: Comienza con verbos como “Controlar”, “Integrar”, “Habilitar”

Ejemplos Buenos:

• “Controlar el destello de la luz del dispositivo y la linterna con un simple interruptor de encendido/apagado”
• “Integrar Crisp para chat en vivo y soporte al cliente en tu aplicación”
• “Habilitar la autenticación segura utilizando Face ID y Touch ID”

Ejemplos Malos:

• “Un complemento para flash”
• “Este es un complemento de Crisp”
• “Complemento biométrico”

Escribiendo Documentación

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

Code Ejemplos

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

Lista de verificación

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

• Agregado plugin a /src/config/plugins.ts
• Seleccionado icono apropiado de Heroicons
• Agregado plugin a /src/content/docs/docs/plugins/index.mdx bajo la categoría correcta
• Agregado entrada de menú lateral en /astro.config.mjs
• Creado directorio de documentación del plugin
• Creado index.mdx página de resumen
• Creación getting-started.mdx Guía
• Creación de tutoriales en /src/content/plugins-tutorials/en/
• Incluyó instrucciones de instalación
• Documentó la configuración de iOS
• Documentó la configuración de Android
• Proporcionó ejemplos de uso
• Agregó referencia a API
• Incluyó ejemplo de trabajo completo
• Enumeró las mejores prácticas
• Agregó notas específicas de plataforma
• Probó que todos los enlaces funcionan correctamente

Referencia de iconos

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

Icono	Uso de caso
BoltIcon	contexto: Página de marketing de soluciones de Capgo. Rol: Etiqueta de IU corta o elemento de navegación. Visto en: página soluciones/cordova-to-capacitor-ai.astro. Clave de mensaje `solutions_cordova_to_capacitor_ai_table_use_case` (Uso de caso de la tabla de soluciones Cordova To Capacitor Ai).
CameraIcon	Flash, energía, potencia
ChatBubbleLeftIcon	Cámara, foto, video
FingerPrintIcon	Chat, mensajería, comunicación
MapPinIcon	Biometría, seguridad, autenticación
SpeakerWaveIcon	Ubicación, geolocalización, mapas
VideoCameraIcon	Audio, sonido, música
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. Actualizar números de versión en la documentación
2. Agregar guías de migración si existen cambios disruptivos
3. Actualice la referencia de 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. Mantenga la tutoría actualizada con las últimas API

Rutas de idioma

Escriba y revise la documentación de plugins en inglés. Los caminos localizados se generan mediante la información de metadatos del sitio y se traducen en la orilla por el trabajador de traducción.

Pruebas de cambios

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

1. Construya el sitio localmente:

   bun run build

2. Compruebe errores:

   • Verifique que todas las enlaces funcionen
   • Asegúrese de que las imágenes se carguen correctamente
   • Confirme que los ejemplos code son válidos
   • Pruebe que la navegación funciona

3. Vista previa del sitio:

   bun run dev

4. Verificar que tu plugin aparece:

   • Verificar página de lista de plugins
   • Verificar navegación en el menú lateral
   • Probar todas las páginas de documentación
   • Confirmar que la página de tutorial funciona

Pitfalls comunes

Cuidado

Evite estos errores comunes:

1. Olvidar sincronizar: Siempre ejecuta bunx cap sync en ejemplos
2. Nomenclatura inconsistente: Utilice el mismo nombre de plugin en todas partes
3. Configuración de plataforma faltante: Documente tanto la configuración de iOS como la de Android
4. Enlaces rotos: Utilice enlaces relativos y verifique que funcionen
5. Falta de manejo de errores: Muestre siempre try-catch en los ejemplos
6. Importes faltantes: Incluya todos los importes necesarios en los ejemplos
7. Descripciones poco claras: Sea específico sobre qué hace el plugin

Obtener Ayuda

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

• Discord: Únete a nuestra comunidad de Discord
• GitHub: Abra un problema en el repositorio del sitio web
• Correo electrónico: Contacte con el equipo en soporte@capgo.app

Ejemplos

Para referencia, consulte 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)
• Inicio de sesión social: /src/content/docs/docs/plugins/social-login/ (plugin con sub-páginas)

Resumen

Agregar un plugin al Capgo documentación implica:

1. Agregar metadatos a la configuración maestra
2. Agregar el plugin a la página de índice categorizada
3. Configurando la navegación en el menú lateral
4. Crear páginas de documentación exhaustivas
5. Escribir un tutorial detallado
6. Probar todos los cambios localmente

Siguiendo esta guía, aseguras que los plugins estén consistentemente documentados y sean fácilmente descubribles por los usuarios.

Sigue adelante desde Agregar o Actualizar Plugins

Si estás utilizando Agregar o Actualizar Plugins para planificar el trabajo de plugin nativo, conecta con Capgo Directorio de Plugins para el flujo de trabajo del producto en Capgo Directorio de Plugins, Capacitor Plugins por Capgo para el detalle de implementación en Capacitor Plugins 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: ¿Qué Necesitas Saber para el contexto práctico en Capacitor Plugins: ¿Qué Necesitas Saber.