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, es necesario 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. Página de índice de plugins - Agregar el plugin a la página de lista de plugins categorizados
3. Navegación en el lateral - Agregar plugin al menú lateral de documentación
4. Documentación del Plugin - Crear páginas de introducción y de inicio
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 del 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,
   }

   Íconos Disponibles: Ver /node_modules/astro-heroicons/mini/ para ver los íconos 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
   • 🛠️ Herramientas de plugins
   • 🤖 Inteligencia artificial y medios avanzados
   • 📍 Ubicación y servicios de fondo
   • 📞 Comunicación y análisis
   • 🔐 Seguridad y sistema
   • 📊 Características específicas de Android
   • 📥 Descargar y navegación

3. Agregar a navegación de barra lateral

   Abrir /astro.config.mjs y agregar su plugin a la configuración de 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 el panel lateral.

4. Crear directorio de documentación del plugin

   Crear un nuevo directorio para la documentación de tu 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 tutoriales

   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 de plugins

Archivos obligatorios

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

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 bajo 100 caracteres
• Sé Específico: Explique qué hace el plugin, no qué es
• Utilice Verbos de Acción: Comience con verbos como “Control”, “Integrate”, “Enable”

Ejemplos buenos:

• “Control el encendido de la linterna y la luz de emergencia con un simple interruptor de encendido/apagado”
• “Integrar el chat en vivo de Crisp y el soporte al cliente en tu aplicación”
• “Habilitar 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. Comience con la InstalaciónSiempre comienza con pasos de instalación claros
2. Proporcionar ConfiguraciónIncluir requisitos de configuración específicos de plataforma
3. Mostrar ejemplos de usoProporcionar ejemplos de trabajo code
4. Incluir referencia APIDocumentar todos los métodos y parámetros
5. Agregar ejemplos completosMostrar patrones de uso en el mundo real
6. Enumerar mejores prácticasCompartir 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

• 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

Utilice 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 en la categoría correcta
• Agregado entrada de menú lateral en /astro.config.mjs
• Crear directorio de documentación del plugin
• Crear index.mdx página de visión general
• Crear getting-started.mdx guía
• Crear tutorial en /src/content/plugins-tutorials/en/
• Incluidas instrucciones de instalación
• Documentado configuración de iOS
• Documentado configuración de Android
• Se proporcionaron ejemplos de uso
• Se agregó referencia a API
• Incluido ejemplo de trabajo completo
• Se listaron las mejores prácticas
• Se agregaron notas específicas de plataforma
• Se probó que todos los enlaces funcionan correctamente

Referencia de iconos

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

Icónica	Uso de caso
BoltIcon	Relámpago, potencia, energía
CameraIcon	Cámara, foto, video
ChatBubbleLeftIcon	Chatear, mensajería, comunicación
FingerPrintIcon	Biometría, seguridad, autenticación
MapPinIcon	Ubicación, geolocalización, mapas
SpeakerWaveIcon	Audio, sonido, música
VideoCameraIcon	Video, grabación, transmisión
CreditCardIcon	Pagos, compras
PlayCircleIcon	Reproductores de medios, reproductores de video
SignalIcon	Conectividad, red, beacon
RadioIcon	Beacon, transmisor inalámbrico, 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 disruptivos
3. Actualice la referencia API con nuevos métodos
4. Agregue nuevos ejemplos para nuevas características
5. Actualizar requisitos de plataforma si se modificó
6. Revisar mejores prácticas basado en nuevas características
7. Mantener la tutoría actualizada con el último API

Rutas de idioma

Escrebir y revisar documentación de plugins en inglés. Las rutas localizadas se generan por los metadatos del sitio y se traducen en la nube por el trabajador de traducción.

Pruebas de cambios

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

1. Construye el sitio localmente:

   bun run build

2. Revisa errores:

   • Verifica que todos los enlaces funcionen
   • Asegúrate de que las imágenes se carguen correctamente
   • Confirma que los ejemplos code son válidos
   • Prueba que la navegación funcione

3. Previsualiza el sitio:

   bun run dev

4. Verifique que su plugin aparece:

   • Revisa la página de lista de plugins
   • Verifica la navegación del menú lateral
   • Prueba todas las páginas de documentación
   • Confirma que la página del tutorial funciona

Pitfalls comunes

Cuidado

Evite estos errores comunes:

1. Olvidar sincronizarSiempre ejecuta bunx cap sync In ejemplos
2. Nombres inconsistentes: Utiliza el mismo nombre de plugin en todas partes
3. Falta de configuración de plataforma: Documenta 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: Muestra siempre try-catch en los ejemplos
6. Faltan importaciones: Incluye todas las importaciones necesarias en los ejemplos
7. Descripciones poco claras: Sé específico sobre qué hace el plugin

Ayuda

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

• Discord: Únete a nuestra comunidad de Discord
• GitHub: Abra una incidencia en el repositorio del sitio web
• Correo electrónico: Contacte 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)
• Ingreso de Redes Sociales: /src/content/docs/docs/plugins/social-login/ (plugin con sub-páginas)

Resumen

Agregar un complemento a la documentación de Capgo implica:

1. Agregar metadatos a la configuración principal
2. Agregar el complemento a la página de índice categorizada
3. Configurar 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, asegura que los complementos estén documentados de manera consistente y sean fácilmente descubribles por los usuarios.

Sigue adelante desde Agregar o Actualizar Complementos

Si estás utilizando Agregar o Actualizar Complementos para planificar el trabajo de plugin nativo, conectarlo 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 Empresa de Ionic para el flujo de trabajo del producto en Alternativas de Plugins de Empresa de Ionic, 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.