Añadir o actualizar plugins

Esta guía explica cómo añadir nuevos plugins de Capacitor al sitio web de Capgo o actualizar la documentación de plugins existentes. Es útil para colaboradores, mantenedores y agentes de IA que ayudan con la documentación.

Resumen

Al añadir un nuevo plugin al ecosistema de Capgo, debes actualizar varios archivos y secciones del sitio web para asegurar que el plugin aparezca correctamente en todos los lugares pertinentes:

1. Configuración de la lista de plugins - Añadir metadatos del plugin a la lista maestra
2. Página de índice de plugins - Añadir el plugin a la página de listado categorizado
3. Navegación lateral - Añadir el plugin a la barra lateral de documentación
4. Documentación del plugin - Crear páginas de descripción y de inicio rápido
5. Tutorial del plugin - Crear un tutorial completo

Ubicación de archivos

Archivos clave a 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 por categorías
/astro.config.mjs	Configuración de la navegación lateral
/src/content/docs/docs/plugins/[plugin-name]/	Directorio de documentación de plugins
/src/content/plugins-tutorials/en/	Archivos del tutorial en inglés

Guía paso a paso

1. Añadir plugin a la lista maestra

   Abrir /src/config/plugins.ts y añade tu plugin al 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: Revisa /node_modules/astro-heroicons/mini/ para los iconos disponibles.

2. Añadir plugin a la página de índice

   Abrir /src/content/docs/docs/plugins/index.mdx y añade tu 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 multimedia y cámara
   • 🛠️ Plugins de utilidad
   • 🤖 IA y multimedia avanzada
   • 📍 Ubicación y servicios en segundo plano
   • 📞 Comunicación y analíticas
   • 🔐 Seguridad y sistema
   • 📊 Funciones específicas de Android
   • 📥 Descarga y navegación

3. Añadir a la navegación lateral

   Abrir /astro.config.mjs y añade tu plugin a la configuración del sidebar (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 listan alfabéticamente en el sidebar.

4. Crear directorio de documentación del plugin

   Crea 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 tutorial

   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, puedes añadir 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

Pautas de contenido

Escribir descripciones de plugins

• Sé conciso: Mantén las descripciones bajo los 100 caracteres
• Sé específico: Explica qué hace el plugin, no qué es
• Usa verbos de acción: Empieza con verbos como “Controlar”, “Integrar” o “Habilitar”

Buenos ejemplos:

• “Controla el flash y la linterna con un simple interruptor de encendido/apagado”
• “Integra el chat en vivo y el soporte al cliente de Crisp en tu app”
• “Habilita la autenticación segura mediante Face ID y Touch ID”

Malos ejemplos:

• “Un plugin para el flash”
• “Este es un plugin de Crisp”
• “Plugin biométrico”

Escribir documentación

1. Empieza con la instalación: Empieza siempre con pasos de instalación claros
2. Proporciona la configuración: Incluir requisitos de configuración por plataforma
3. Mostrar ejemplos de uso: Proporcionar ejemplos de code funcionales
4. Incluir referencia de API: Documentar todos los métodos y parámetros
5. Añadir ejemplos completos: Mostrar patrones de uso reales
6. Listar mejores prácticas: Compartir consejos para un uso óptimo
7. Documentar diferencias de plataforma: Clarificar el comportamiento en iOS vs Android
8. Añadir resolución de problemas: Soluciona problemas comunes

Ejemplos de Code

• Usa TypeScript en todos los ejemplos de code
• Incluye los imports al principio
• Añade comentarios explicando los pasos clave
• Muestra el manejo de errores
• Demuestra usos básicos y avanzados

Checklist

Usa esta checklist al añadir un nuevo plugin:

• Plugin añadido a /src/config/plugins.ts
• Se seleccionó el icono adecuado de Heroicons
• Se añadió el plugin a /src/content/docs/docs/plugins/index.mdx bajo la categoría correcta
• Se añadió la entrada en la barra lateral de /astro.config.mjs
• Directorio de documentación de plugins creado
• Se creó la index.mdx página de descripción general
• Se creó la getting-started.mdx guía
• Se creó el tutorial en /src/content/plugins-tutorials/en/
• Se incluyeron las instrucciones de instalación
• Se documentó la configuración de iOS
• Configuración de Android documentada
• Ejemplos de uso incluidos
• Referencia a API añadida
• Ejemplo completo y funcional
• Mejores prácticas listadas
• Notas específicas de la plataforma
• Todos los enlaces verificados

Referencia de iconos

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

Icono	Caso de uso
BoltIcon	Flash, 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 multimedia, reproductores de video
SignalIcon	Conectividad, red, beacon
RadioIcon	Beacon, broadcast, inalámbrico
ChatBubbleOvalLeftIcon	Redes sociales, WeChat

Actualizar plugins existentes

Al actualizar un plugin existente:

1. Actualiza los números de versión en la documentación
2. Añade guías de migración si hay breaking changes
3. Actualiza las referencias a API con los nuevos métodos
4. Añade nuevos ejemplos para las nuevas funcionalidades
5. Actualiza los requisitos de plataforma si hubo cambios
6. Revisar las mejores prácticas según las nuevas funciones
7. Mantener el tutorial actualizado con lo último de API

Rutas de idioma

Escribe y revisa la documentación de los plugins en inglés. Las rutas localizadas se generan mediante los metadatos del sitio y se traducen en el edge por el translation Worker.

Probar tus cambios

Tras añadir o actualizar la documentación del plugin:

1. Genera el sitio localmente:

   bun run build

2. Revisa si hay errores:

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

3. Previsualiza el sitio:

   bun run dev

4. Verifica que tu plugin aparezca:

   • Revisa la página de listado de plugins
   • Verificar la navegación lateral
   • Probar todas las páginas de la documentación
   • Confirmar que la página del tutorial funciona

Errores comunes

Precaución

Evita estos errores frecuentes:

1. Olvidar hacer el sync: Ejecutar siempre bunx cap sync en los ejemplos
2. Nombres inconsistentes: Usa el mismo nombre de plugin en todas partes
3. Falta configuración de plataforma: Documenta la configuración de iOS y Android
4. Enlaces rotos: Usa enlaces relativos y verifica que funcionen
5. Sin manejo de errores: Incluye siempre try-catch en los ejemplos
6. Faltan imports: Incluye todos los imports necesarios en los ejemplos
7. Descripciones poco claras: Sé específico sobre lo que hace el plugin

Obtener ayuda

Si necesitas ayuda para añadir o actualizar la documentación de un plugin:

• Discord: Únete a nuestro Comunidad de Discord
• GitHub: Abre un issue en el repositorio del sitio web
• Email: Contacta al equipo en support@capgo.app

Ejemplos

Para referencia, consulta estos plugins bien documentados:

• Actualizador: /src/content/docs/docs/plugins/updater/ (plugin complejo con múltiples páginas)
• Flash: /src/content/docs/docs/plugins/flash/ (plugin sencillo, buen ejemplo para empezar)
• Social Login: /src/content/docs/docs/plugins/social-login/ (plugin con subpáginas)

Resumen

Añadir un plugin a la documentación de Capgo implica:

1. Añadir metadatos a la configuración maestra
2. Añadir el plugin a la página de índice categorizada
3. Configuración de la navegación lateral
4. Crear páginas de documentación completas
5. Escribir un tutorial detallado
6. Probar todos los cambios localmente

Al seguir esta guía, garantizas que los plugins estén documentados de forma consistente y que los usuarios puedan encontrarlos fácilmente.

Continuar desde Añadir o actualizar plugins

Si estás usando Añadir o actualizar plugins para planificar el trabajo con plugins nativos, conéctalo con Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise, Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds, y Plugins Capacitor: lo que debes saber para el contexto práctico en Capacitor Plugins: lo que necesitas saber.