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. Índice de Plugins - Agregar plugin a la página de listado de plugins categorizados
3. Barra de Navegación del Lado - Agregar plugin a la barra de navegación de la documentación
4. Documentación del Plugin - Crear páginas de resumen y de inicio rápido
5. Tutoriales de Plugin - Crear un tutorial integral

Ubicaciones de Archivos

Archivos Clave para Actualizar

Archivo	Objetivo
/src/config/plugins.ts	context: Página/área: Sitio web de marketing de Capgo. Rol: Etiqueta de IU o elemento de navegación corto. Clave de mensaje `subprocessors_table_purpose` (Objetivo de la tabla de subprocesos).
/src/content/docs/docs/plugins/index.mdx	Lista de plugins maestros con metadatos
/astro.config.mjs	Página de índice de plugins con categorías
/src/content/docs/docs/plugins/[plugin-name]/	Configuración de navegación en el menú lateral
/src/content/plugins-tutorials/en/	Directorio de documentación de plugins

Archivos de tutoriales en inglés

1. Sección titulada “Guía paso a paso”

   Sección titulada “Agregar plugin a la lista maestra” /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/ 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 📊
   • Descarga y navegación 📥

3. Agregar a la navegación lateral

   Abre /astro.config.mjs y agrega tu 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 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 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
• Sean Precisos: Explique qué hace el complemento, no qué es
• Usar Verbos de Acción: Comience 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 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 complemento para flash”
• “Este es un complemento de Crisp”
• “Complemento biométrico”

Escribir 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 recomendadas para la lista: Compartir consejos para un uso óptimo
7. Diferencias de la 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
• Muestra el 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 complemento:

• Complemento agregado a /src/config/plugins.ts
• Seleccionó el icono apropiado de Heroicons
• Complemento agregado a /src/content/docs/docs/plugins/index.mdx bajo la categoría correcta
• Entrada de lateral agregada en /astro.config.mjs
• Crear directorio de documentación del complemento
• Crear index.mdx página de resumen
• Creado getting-started.mdx guía
• Creado tutorial 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 completo y funcional
• Listó 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 breve 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	Relámpago, potencia, energía
ChatBubbleLeftIcon	Cámara, foto, video
FingerPrintIcon	Chatear, 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 los últimos 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.

Prueba tus 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 todos los 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:

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

Pitfalls comunes

Cuidado

Evita estos errores comunes:

1. Olvidar sincronizar: Siempre ejecuta bunx cap sync en ejemplos
2. Nomenclatura inconsistente: Utiliza el mismo nombre de plugin en todas partes
3. Configuración de plataforma faltante: Documenta tanto la configuración de iOS como Android
4. Enlaces rotos: Utiliza enlaces relativos y verifica que funcionen
5. Falta de manejo de errores: Siempre muestra try-catch en ejemplos
6. Importes faltantes: Incluye todos los importes necesarios en los ejemplos
7. Descripciones poco claras: 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
• GitHub: Abre un problema en el repositorio del sitio web
• Correo electrónico: Contacta con el equipo en support@capgo.app

Ejemplos

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

Resumen

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

1. Agregar metadatos a la configuración maestra
2. Agregar el plugin 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, 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 los detalles 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: Lo que debes saber para el contexto práctico en Capacitor Plugins: Lo que debes saber.