roi-theme/wp-content/themes/apus-theme/docs/02-theme-options.md

Guía del Panel de Opciones - Apus Theme

Versión: 1.0.0 Última actualización: Noviembre 2024

Esta guía detalla todas las opciones disponibles en el panel de administración del tema Apus.

---

Tabla de Contenidos

1. Acceder al Panel
2. Estructura del Panel
3. Tab 1: General Settings
4. Tab 2: Performance
5. Tab 3: SEO Settings
6. Tab 4: Typography
7. Tab 5: Content Settings
8. Tab 6: Advanced
9. Guardar y Gestionar Opciones
10. Mejores Prácticas

---

Acceder al Panel

1. Inicia sesión en WordPress como administrador
2. Ve a Apariencia > Theme Options en el menú lateral
3. Verás el panel dividido en 6 tabs (pestañas)

Nota: Solo los administradores pueden acceder a este panel.

---

Estructura del Panel

El panel está organizado en 6 tabs principales:

1. General Settings - Logo, favicon, información básica
2. Performance - Optimizaciones de rendimiento
3. SEO Settings - Configuraciones SEO
4. Typography - Fuentes y tipografía
5. Content Settings - TOC, posts relacionados, contenido
6. Advanced - CSS/JS custom, tracking codes

Cada tab agrupa opciones relacionadas para facilitar la navegación.

---

Tab 1: General Settings

Configuraciones generales del sitio.

Site Logo

Opción: apus_site_logo Tipo: Media Upload

Descripción: Sube el logo principal del sitio que aparecerá en el header.

Recomendaciones:

• Tamaño: 200-250px de ancho máximo
• Formato: PNG con transparencia o SVG
• Altura: 40-60px recomendada
• Versión @2x para Retina displays

Uso desde código:

$logo_id = apus_get_option('apus_site_logo');
$logo_url = wp_get_attachment_image_url($logo_id, 'full');

Favicon

Opción: apus_favicon Tipo: Media Upload

Descripción: Icono que aparece en la pestaña del navegador.

Recomendaciones:

• Tamaño: 32x32px o 64x64px
• Formato: .ico, .png
• Diseño simple (se ve muy pequeño)

Nota: WordPress también permite configurar favicon en Apariencia > Personalizar > Identidad del sitio > Icono del sitio

Site Tagline

Opción: apus_site_tagline Tipo: Text

Descripción: Lema o descripción breve del sitio.

Ejemplo:

• "Análisis de Precios Unitarios Profesionales"
• "Tu fuente confiable de información"

Uso desde código:

$tagline = apus_get_option('apus_site_tagline', 'Default tagline');

Copyright Text

Opción: apus_copyright_text Tipo: Textarea

Descripción: Texto de copyright que aparece en el footer.

Valores por defecto:

© 2024 Apus Theme. Todos los derechos reservados.

Variables disponibles:

• {year} - Año actual (automático)
• {site_name} - Nombre del sitio

Ejemplo:

© {year} {site_name}. Todos los derechos reservados.

Timezone

Opción: apus_timezone Tipo: Select

Descripción: Zona horaria del sitio.

Opciones comunes:

• America/Mexico_City (GMT-6)
• America/Bogota (GMT-5)
• America/Buenos_Aires (GMT-3)
• Etc/UTC (GMT+0)

Nota: También se puede configurar en Ajustes > Generales > Zona horaria

---

Tab 2: Performance

Optimizaciones de rendimiento y Core Web Vitals.

Enable Lazy Loading

Opción: apus_enable_lazy_loading Tipo: Checkbox Default: Activado ✓

Descripción: Activa lazy loading nativo del navegador para imágenes e iframes.

Efecto:

• Las imágenes fuera del viewport no se cargan inmediatamente
• Mejora LCP (Largest Contentful Paint)
• Reduce uso de ancho de banda

Recomendación: Mantener activado siempre.

Enable Image Optimization

Opción: apus_enable_image_optimization Tipo: Checkbox Default: Activado ✓

Descripción: Activa el módulo de optimización de imágenes del tema.

Características:

• Genera srcset responsive automáticamente
• Lazy loading condicional
• Preload para imágenes críticas (featured images)

Recomendación: Mantener activado. Combinar con plugin de optimización como Smush.

Enable WebP Support

Opción: apus_enable_webp Tipo: Checkbox Default: Activado ✓

Descripción: Activa soporte para imágenes WebP.

Requisitos:

• Servidor con soporte WebP
• O plugin de conversión (ShortPixel, Smush Pro)

Beneficios:

• Imágenes 25-35% más ligeras
• Mejor performance
• Misma calidad visual

Recomendación: Activar si tu servidor/plugin soporta WebP.

Enable CSS Minification

Opción: apus_enable_css_minification Tipo: Checkbox Default: Desactivado

Descripción: Minifica los archivos CSS del tema.

Nota: Si usas un plugin de cache (WP Rocket, Autoptimize), déjalo desactivado para evitar doble minificación.

Enable JS Minification

Opción: apus_enable_js_minification Tipo: Checkbox Default: Desactivado

Descripción: Minifica los archivos JavaScript del tema.

Nota: Similar a CSS, si usas plugin de cache, déjalo desactivado.

Enable Resource Hints

Opción: apus_enable_resource_hints Tipo: Checkbox Default: Activado ✓

Descripción: Activa resource hints (dns-prefetch, preconnect, preload).

Beneficios:

• Precarga de recursos críticos
• Mejora tiempos de carga
• Optimiza Core Web Vitals

Recomendación: Mantener activado.

AdSense Delay Loading

Opción: apus_enable_adsense_delay Tipo: Checkbox Default: Desactivado

Descripción: Retrasa la carga de AdSense hasta la primera interacción del usuario (scroll, touch, click).

Beneficios:

• Mejora dramática en LCP
• Mejora TBT (Total Blocking Time)
• AdSense se carga, pero sin afectar performance

Cómo usar:

1. Activa esta opción
2. Agrega tu código de AdSense normalmente
3. El tema interceptará y retrasará la carga

Recomendación: Activar siempre si usas AdSense.

Cache Settings

Opción: apus_cache_duration Tipo: Number Default: 3600 (1 hora)

Descripción: Duración del cache en segundos para assets del tema.

Valores comunes:

• 3600 = 1 hora
• 86400 = 1 día
• 604800 = 1 semana
• 31536000 = 1 año (para producción)

Recomendación: 31536000 (1 año) en producción, 3600 durante desarrollo.

---

Tab 3: SEO Settings

Configuraciones SEO básicas (Rank Math maneja el SEO avanzado).

Default Meta Description

Opción: apus_default_meta_description Tipo: Textarea Max: 160 caracteres

Descripción: Meta descripción por defecto para páginas sin descripción específica.

Ejemplo:

Encuentra información profesional sobre análisis de precios unitarios,
costos de construcción y presupuestos detallados.

Nota: Rank Math sobrescribe esto si está configurado.

Twitter Handle

Opción: apus_twitter_handle Tipo: Text

Descripción: Tu usuario de Twitter/X (sin @).

Ejemplo:

• Correcto: apustheme
• Incorrecto: @apustheme

Uso: Para Twitter Cards en meta tags.

Facebook App ID

Opción: apus_facebook_app_id Tipo: Text

Descripción: ID de tu aplicación de Facebook para Open Graph.

Cómo obtenerlo:

1. Ve a https://developers.facebook.com/
2. Crea una app
3. Copia el App ID

Default Open Graph Image

Opción: apus_default_og_image Tipo: Media Upload

Descripción: Imagen por defecto para compartir en redes sociales.

Recomendaciones:

• Tamaño: 1200 x 630px
• Formato: JPG o PNG
• Peso: < 300KB
• Sin texto pequeño (se ve en thumbnail)

Enable Breadcrumbs

Opción: apus_enable_breadcrumbs Tipo: Checkbox Default: Desactivado

Descripción: Activa breadcrumbs (migas de pan) en posts y páginas.

Nota: El brief original indica "sin breadcrumbs" debido a títulos largos. Activar solo si necesitas.

Schema.org Type

Opción: apus_schema_type Tipo: Select Default: Organization

Descripción: Tipo de schema para tu sitio.

Opciones:

• Organization (empresa, sitio corporativo)
• Person (blog personal)
• LocalBusiness (negocio local)

Nota: Rank Math maneja schema avanzado.

---

Tab 4: Typography

Configuración de fuentes del tema.

Font Provider

Opción: apus_font_provider Tipo: Radio Default: System Fonts

Descripción: Elige el proveedor de fuentes.

Opciones:

System Fonts (Recomendado)

• Ventajas:
  • Rendimiento óptimo (0 requests externos)
  • Privacy-friendly
  • Siempre disponible
• Desventajas:
  • Menos opciones de diseño
  • Se ve diferente en cada SO

Google Fonts

• Ventajas:
  • Miles de fuentes disponibles
  • Fácil de usar
• Desventajas:
  • Request externo
  • Privacy concerns en Europa

Bunny Fonts

• Ventajas:
  • GDPR-compliant
  • Clon de Google Fonts
  • Privacy-friendly
• Desventajas:
  • Request externo (pero menor latencia que Google en EU)

Heading Font Family

Opción: apus_heading_font_family Tipo: Select Default: Depends on provider

Descripción: Fuente para títulos (H1-H6).

System Fonts disponibles:

• System Default
• -apple-system
• Georgia
• Times New Roman

Google/Bunny Fonts: Lista dinámica de fuentes populares.

Body Font Family

Opción: apus_body_font_family Tipo: Select Default: Depends on provider

Descripción: Fuente para texto del cuerpo (párrafos, etc.).

Base Font Size

Opción: apus_base_font_size Tipo: Number Default: 16 Unit: px

Descripción: Tamaño de fuente base en píxeles.

Recomendaciones:

• 16px: Estándar, muy legible
• 18px: Para sitios con mucho texto
• 14px: Solo para UIs compactas (no recomendado)

Heading Font Weight

Opción: apus_heading_font_weight Tipo: Select Default: 700 (Bold)

Opciones:

• 300 (Light)
• 400 (Regular)
• 500 (Medium)
• 600 (Semi-bold)
• 700 (Bold)
• 800 (Extra-bold)

Body Font Weight

Opción: apus_body_font_weight Tipo: Select Default: 400 (Regular)

Recomendación: 400 para texto normal, 500 si usas font size pequeña.

Line Height

Opción: apus_line_height Tipo: Number Default: 1.6 Range: 1.2 - 2.0

Descripción: Altura de línea (interlineado).

Recomendaciones:

• 1.4: Texto muy compacto
• 1.6: Estándar, muy legible (recomendado)
• 1.8: Para textos largos, blogs
• 2.0: Muy espaciado

---

Tab 5: Content Settings

Configuraciones de contenido y funcionalidades.

Table of Contents (TOC)

Enable TOC

Opción: apus_enable_toc Tipo: Checkbox Default: Activado ✓

Descripción: Activa tabla de contenidos automática en posts.

TOC Title

Opción: apus_toc_title Tipo: Text Default: "Tabla de Contenidos"

Descripción: Título que aparece encima del TOC.

Ejemplos:

• "Contenido"
• "En este artículo"
• "Índice"

TOC Position

Opción: apus_toc_position Tipo: Select Default: "before_content"

Opciones:

• before_content - Antes del contenido (arriba del post)
• sidebar - En el sidebar (sticky)

Recomendación: before_content para posts cortos, sidebar para posts largos.

Minimum Headings

Opción: apus_toc_min_headings Tipo: Number Default: 3

Descripción: Número mínimo de headings para mostrar el TOC.

Lógica:

• Si post tiene menos headings que este número, no se muestra TOC
• Evita TOC en posts cortos

Recomendación: 3-4 headings mínimo.

Heading Depth

Opción: apus_toc_heading_depth Tipo: Select Default: "h2,h3"

Opciones:

• h2 - Solo H2
• h2,h3 - H2 y H3
• h2,h3,h4 - H2, H3 y H4
• h2,h3,h4,h5,h6 - Todos

Recomendación: h2,h3 para mayoría de posts.

Related Posts

Enable Related Posts

Opción: apus_enable_related_posts Tipo: Checkbox Default: Activado ✓

Descripción: Muestra posts relacionados al final del post.

Criterio: Posts de la misma categoría.

Related Posts Title

Opción: apus_related_posts_title Tipo: Text Default: "Artículos Relacionados"

Ejemplos:

• "También te puede interesar"
• "Más sobre este tema"
• "Lectura recomendada"

Number of Related Posts

Opción: apus_related_posts_count Tipo: Number Default: 4 Range: 2-12

Descripción: Cuántos posts relacionados mostrar.

Recomendaciones:

• 3-4: Para layouts estrechos
• 6: Estándar
• 8-12: Para sitios con mucho contenido

Related Posts Order

Opción: apus_related_posts_order Tipo: Select Default: "date"

Opciones:

• date - Más recientes primero
• random - Orden aleatorio (bueno para SEO interno)
• comment_count - Más comentados primero
• modified - Recientemente actualizados

Recomendación: random para variar el contenido mostrado.

Show Thumbnails in Related Posts

Opción: apus_related_posts_show_thumbnail Tipo: Checkbox Default: Activado ✓

Descripción: Muestra imagen destacada en cada post relacionado.

Show Excerpt in Related Posts

Opción: apus_related_posts_show_excerpt Tipo: Checkbox Default: Desactivado

Descripción: Muestra excerpt breve debajo del título.

Nota: Activar solo si tienes excerpts bien escritos.

Show Date in Related Posts

Opción: apus_related_posts_show_date Tipo: Checkbox Default: Activado ✓

Descripción: Muestra fecha de publicación.

Other Content Settings

Excerpt Length

Opción: apus_excerpt_length Tipo: Number Default: 55 Unit: words

Descripción: Longitud del excerpt en número de palabras.

Recomendaciones:

• 30-40: Muy corto, para grids compactos
• 55: Estándar (WordPress default)
• 80-100: Para layouts amplios

Read More Text

Opción: apus_read_more_text Tipo: Text Default: "Leer más"

Ejemplos:

• "Continuar leyendo"
• "Ver más"
• "Leer artículo completo"

Show Featured Images in Archives

Opción: apus_show_featured_in_archives Tipo: Checkbox Default: Activado ✓

Descripción: Muestra imágenes destacadas en listados de posts.

Show Author Bio

Opción: apus_show_author_bio Tipo: Checkbox Default: Desactivado

Descripción: Muestra biografía del autor al final del post.

Requisito: El autor debe tener información biográfica en su perfil.

---

Tab 6: Advanced

Configuraciones avanzadas para usuarios experimentados.

Custom CSS

Opción: apus_custom_css Tipo: Code Editor (CSS)

Descripción: CSS personalizado que se carga después de todos los estilos del tema.

Ejemplo:

/* Cambiar color del header */
.site-header {
    background-color: #333;
}

/* Aumentar tamaño de títulos */
h1.entry-title {
    font-size: 3rem;
}

Nota: Usa el Customizer para CSS simple. Esta opción es para CSS avanzado.

Custom JavaScript

Opción: apus_custom_js Tipo: Code Editor (JavaScript)

Descripción: JavaScript personalizado que se carga en el footer.

Ejemplo:

// Log cuando la página carga
console.log('Página cargada completamente');

// Agregar funcionalidad custom
document.addEventListener('DOMContentLoaded', function() {
    // Tu código aquí
});

Advertencia: JavaScript mal escrito puede romper el sitio. Prueba en entorno de desarrollo primero.

Header Scripts

Opción: apus_header_scripts Tipo: Textarea

Descripción: Scripts que se insertan en el <head>. Útil para meta tags, verification codes, etc.

Usos comunes:

• Google Site Verification
• Facebook Domain Verification
• Pinterest Site Verification
• Schema markup adicional

Ejemplo:

<!-- Google Site Verification -->
<meta name="google-site-verification" content="tu-codigo-aqui" />

Footer Scripts

Opción: apus_footer_scripts Tipo: Textarea

Descripción: Scripts que se insertan antes del cierre de </body>.

Usos comunes:

• Códigos de tracking
• Chat widgets
• Widgets de redes sociales

Google Analytics ID

Opción: apus_google_analytics_id Tipo: Text Placeholder: G-XXXXXXXXXX o UA-XXXXXXXXX-X

Descripción: Tu Google Analytics Measurement ID.

Cómo obtenerlo:

1. Ve a https://analytics.google.com/
2. Admin > Propiedad > Detalles de la propiedad
3. Copia el Measurement ID

Formatos:

• GA4: G-XXXXXXXXXX
• Universal Analytics (legacy): UA-XXXXXXXXX-X

Nota: El tema insertará automáticamente el código de tracking.

Facebook Pixel ID

Opción: apus_facebook_pixel_id Tipo: Text Placeholder: Número de 15-16 dígitos

Descripción: Tu Facebook Pixel ID para tracking de eventos.

Cómo obtenerlo:

1. Ve a https://business.facebook.com/events_manager
2. Selecciona tu pixel
3. Copia el Pixel ID

Custom Tracking Codes

Opción: apus_custom_tracking Tipo: Textarea

Descripción: Otros códigos de tracking (Hotjar, Microsoft Clarity, etc.).

Ejemplo - Hotjar:

<!-- Hotjar Tracking Code -->
<script>
    (function(h,o,t,j,a,r){
        h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
        h._hjSettings={hjid:YOUR_HOTJAR_ID,hjsv:6};
        a=o.getElementsByTagName('head')[0];
        r=o.createElement('script');r.async=1;
        r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
        a.appendChild(r);
    })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
</script>

---

Guardar y Gestionar Opciones

Guardar Cambios

1. Haz tus cambios en cualquier tab
2. Haz clic en "Save Changes" al final de la página
3. Verás un mensaje de confirmación: "Settings saved successfully"

Nota: Los cambios se guardan inmediatamente y afectan el sitio en vivo.

Reset to Defaults

1. Haz clic en el botón "Reset to Defaults"
2. Confirma la acción en el popup
3. Todas las opciones volverán a sus valores por defecto

Advertencia: Esta acción no se puede deshacer.

Import/Export Settings

Export (Preparado para futuro)

1. Haz clic en "Export Settings"
2. Se descargará un archivo JSON con todas tus opciones
3. Guárdalo como backup

Import (Preparado para futuro)

1. Haz clic en "Import Settings"
2. Selecciona un archivo JSON previamente exportado
3. Confirma la importación
4. Las opciones se sobrescriben con las del archivo

Uso común:

• Backup antes de cambios grandes
• Copiar configuración entre sitios
• Restaurar configuración anterior

---

Mejores Prácticas

Performance

1. Activa lazy loading y WebP siempre
2. AdSense delay si usas anuncios
3. System fonts para mejor performance
4. Resource hints activados
5. No minifiques CSS/JS si usas plugin de cache (evita conflictos)

SEO

1. Deja que Rank Math maneje el SEO avanzado
2. Usa el panel solo para defaults
3. Configura Open Graph image default
4. Agrega tracking codes en Advanced tab

Content

1. TOC: Activar con mínimo 3-4 headings
2. Related Posts: 4-6 posts, orden aleatorio
3. Excerpts: 55-80 palabras
4. Featured images: Activar en archives

Typography

1. System fonts para mejor performance
2. Base font size: 16-18px
3. Line height: 1.6-1.8 para legibilidad
4. Heading weight: 700 (bold)

Development

1. Prueba en staging antes de producción
2. Exporta settings antes de cambios grandes
3. Custom CSS/JS: Usar con precaución
4. Header/Footer scripts: Validar código antes de insertar

---

Acceso desde Código

Todos los helpers están disponibles en inc/theme-options-helpers.php:

// Obtener cualquier opción
$value = apus_get_option('apus_option_name', 'default_value');

// Ejemplos específicos
$enable_toc = apus_enable_toc(); // bool
$toc_title = apus_get_toc_title(); // string
$related_count = apus_get_related_posts_count(); // int
$logo_id = apus_get_option('apus_site_logo'); // attachment ID

// Verificaciones
if (apus_enable_lazy_loading()) {
    // Agregar lazy loading
}

if (apus_enable_related_posts()) {
    // Mostrar related posts
}

---

Soporte

Si tienes dudas sobre alguna opción:

1. Lee esta documentación completa
2. Revisa 01-initial-setup.md para configuración básica
3. Revisa 03-performance-seo.md para optimizaciones
4. Reporta issues en GitHub si algo no funciona

---

Tip final: No actives todas las opciones a la vez. Ve agregando funcionalidades gradualmente y verifica que funcionen correctamente antes de agregar más.