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ú 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 correspondiente:

   <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
   • 📍 Servicios de ubicación y 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 lateral

   Abrir /astro.config.mjs y agregar su plugin a la configuración de navegación 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 visión general 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 necesarios

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

Excelentes Ejemplos:

• “Control el encendido de la linterna y la luz de la torche 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”

Escritura de 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. Listar mejores prácticasCompartir consejos para un uso óptimo
7. Documentar diferencias de plataforma: Comprender el comportamiento de iOS vs Android
8. Agregar información de depuración: Resolver 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 this checklist when adding a new plugin:

• Agregado plugin a /src/config/plugins.ts
• Seleccionó el 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 resumen
• Crear getting-started.mdx guía
• Crear tutorial en /src/content/plugins-tutorials/en/
• Instrucciones de instalación incluidas
• Configuración de iOS documentada
• Configuración de Android documentada
• Ejemplos de uso proporcionados
• 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	Chat, 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, streaming
CreditCardIcon	Pagos, compras
PlayCircleIcon	Reproductores de medios, reproductores de video
SignalIcon	Conectividad, red, beacon
RadioIcon	Beacon, broadcast, inalámbrico
ChatBubbleOvalLeftIcon	Redes sociales, WeChat

Actualizando Plugins Existentes

Cuando se actualice 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. Actualizar referencia de API con nuevos métodos
4. Agregar nuevos ejemplos para nuevas características
5. Actualice los requisitos del plataforma si se modificó
6. Revisar las mejores prácticas basado en nuevas características
7. Mantenga el tutorial actualizado con el último API

Rutas de idioma

Escriba y revise la documentación de plugins 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.

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

Evita estos errores comunes:

1. Olvidar sincronizar : Siempre ejecuta bunx cap sync en ejemplos
2. Nombres inconsistentes: 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. Importaciones faltantes: Incluya todas las importaciones necesarias en los ejemplos
7. Descripciones poco claras: Sé 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 una incidencia 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)
• Ingreso de Redes Sociales: /src/content/docs/docs/plugins/social-login/ (plugin con sub-páginas)

Resumen

Al agregar un plugin a la Capgo documentación involucra:

1. Agregar metadatos a la configuración maestra
2. Agregar el plugin a la página de índice categorizado
3. Configurando la navegación del menú lateral
4. Creando páginas de documentación exhaustivas
5. Escribiendo un tutorial detallado
6. Probando todos los cambios localmente

Siguiendo esta guía, asegura 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, conectarlo con Capgo Directorio de Plugins para el flujo de trabajo del producto en Capgo Directorio de Plugins, Capacitor Plugins por Capgo para los detalles 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.