# 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](#acceder-al-panel)
2. [Estructura del Panel](#estructura-del-panel)
3. [Tab 1: General Settings](#tab-1-general-settings)
4. [Tab 2: Performance](#tab-2-performance)
5. [Tab 3: SEO Settings](#tab-3-seo-settings)
6. [Tab 4: Typography](#tab-4-typography)
7. [Tab 5: Content Settings](#tab-5-content-settings)
8. [Tab 6: Advanced](#tab-6-advanced)
9. [Guardar y Gestionar Opciones](#guardar-y-gestionar-opciones)
10. [Mejores Prácticas](#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:**
```php
$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:**
```php
$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:**
```css
/* 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:**
```javascript
// 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:**
```html
<!-- 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:**
```html
<!-- 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`:

```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](01-initial-setup.md) para configuración básica
3. Revisa [03-performance-seo.md](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.