roi-theme/wp-content/themes/apus-theme/README.md

# Apus Theme - Tema WordPress Profesional

**Version:** 1.0.0
**Author:** Apus Development Team
**License:** GPL v2 or later
**WordPress Version Required:** 6.0 o superior
**PHP Version Required:** 8.0 o superior

## Descripción

Apus Theme es un tema WordPress moderno, ligero y altamente optimizado para rendimiento, diseñado específicamente para el proyecto de Análisis de Precios Unitarios. Construido con las mejores prácticas de WordPress, ofrece una base sólida para sitios web profesionales con enfoque en SEO, accesibilidad y velocidad de carga.

El tema está desarrollado con HTML5 semántico, Bootstrap 5.3, y optimizaciones avanzadas de rendimiento incluyendo lazy loading, resource hints, minimización de assets y carga condicional de recursos.

## Características Principales

### Rendimiento y Optimización (Issues #1, #2, #3, #9, #11)

#### Core Web Vitals Optimizados
- **Lazy Loading Nativo**: Carga diferida de imágenes y iframes
- **Resource Hints**: Precarga y preconexión de recursos críticos (dns-prefetch, preconnect, preload)
- **Asset Optimization**: Minimización y combinación de CSS/JS
- **Cache-Control Headers**: Configuración optimizada de caché
- **Critical CSS Inline**: Estilos críticos en línea para primera carga
- **Sin jQuery**: JavaScript vanilla para mejor rendimiento
- **Defer de Scripts**: Carga diferida de scripts no críticos
- **WebP Support**: Soporte para imágenes WebP modernas
- **Módulo de Optimización de Imágenes** (inc/image-optimization.php):
  - Conversión automática a WebP
  - Lazy loading condicional
  - Compression inteligente
  - Generación de srcset responsive

#### Gestión de Fuentes (Issue #12)
- **Sistema de fuentes flexible** via Customizer
- Opciones: System Fonts, Google Fonts, Bunny Fonts (GDPR-compliant)
- **font-display: swap** para mejor rendimiento
- Preconnect automático a CDN de fuentes
- Configuración de fuentes para headings y body por separado

#### Carga Condicional de AdSense (Issue #9)
- **AdSense Delay Load**: Carga diferida de anuncios después de interacción del usuario
- Mejora LCP (Largest Contentful Paint)
- Configuración via Theme Options
- Script optimizado para mejor UX

### SEO y Marketing (Issues #2, #3, #18, #19)

#### SEO Avanzado
- **100% Compatible con Rank Math SEO**: Soporte completo para meta tags y schema
- **HTML5 Semántico**: Markup estructurado para mejor indexación
- **Open Graph Ready**: Meta tags para redes sociales
- **Schema.org Markup**: Datos estructurados integrados
- **Title Tag Support**: WordPress maneja los títulos automáticamente
- **Breadcrumbs Ready**: Preparado para migas de pan
- **Canonical URLs**: URLs canónicas automáticas
- **No meta tags duplicados**: Compatible con plugins SEO

#### Table of Contents (TOC) - Issue #18
- **Generación automática de tabla de contenidos** para posts
- Sticky sidebar con scroll suave
- Configuración via Theme Options:
  - Activar/desactivar globalmente
  - Posición (arriba/sidebar)
  - Número mínimo de headings
  - Profundidad de headings (H2-H6)
- Smooth scroll a secciones
- Indicador de progreso visual

#### Posts Relacionados - Issue #19
- **Sistema inteligente de posts relacionados**
- Basado en categorías compartidas
- Configuración completa via Theme Options:
  - Activar/desactivar
  - Número de posts a mostrar
  - Título personalizable
  - Orden (fecha, aleatorio, más comentados)
- Grid responsive
- Thumbnails optimizados
- Cache de queries para mejor rendimiento

### Diseño y UX (Issues #4, #5, #6, #7, #8, #10, #13, #14, #16)

#### Framework y Estructura
- **Bootstrap 5.3**: Framework CSS moderno y ligero
- **Mobile-First**: Diseño optimizado para móviles
- **Responsive Design**: Adaptable a todos los dispositivos
- **Grid System**: Sistema de grilla flexible
- **Modular CSS**: Archivos CSS organizados por funcionalidad:
  - accessibility.css
  - animations.css
  - footer.css
  - header.css
  - related-posts.css
  - responsive.css
  - theme.css
  - toc.css
  - utilities.css

#### Header y Navegación (Issues #4, #8)
- **Header sticky optimizado** con transición suave
- Menú responsive con hamburger menu
- Skip-to-content link para accesibilidad
- Logo personalizable via Customizer
- Búsqueda integrada en menú
- Navegación con ARIA labels
- Animaciones suaves de scroll
- JavaScript modularizado (assets/js/header.js)

#### Footer (Issue #5)
- **Footer profesional de 4 columnas**
- 4 áreas de widgets configurables
- Menú footer (1 nivel)
- Copyright dinámico
- Links de privacidad y términos
- Grid responsive (se adapta a mobile)
- Estilos dedicados (assets/css/footer.css)

#### Sidebar (Issue #6)
- **Sidebar modular** con área de widgets
- Sticky sidebar en desktop
- Se oculta en mobile para mejor UX
- Compatible con todos los widgets de WordPress
- Widget-ready con clases Bootstrap

#### Single Post Template (Issue #7)
- **Template optimizado para contenido**
- Featured image con lazy loading
- Categorías con badges de colores
- Meta información completa:
  - Fecha de publicación
  - Fecha de última actualización
  - Autor
  - Tiempo de lectura estimado
- Tags visuales
- Navegación entre posts (anterior/siguiente)
- Breadcrumbs ready
- Schema markup para Article
- Comentarios integrados

#### Archive Templates (Issue #10)
- **Templates para archivos optimizados**
- Títulos dinámicos según tipo de archivo
- Descripciones de categorías/tags
- Grid de posts con thumbnails
- Excerpts automáticos
- Read more links
- Paginación estilizada
- Meta info en cada post

#### 404 Error Page (Issue #13)
- **Página 404 profesional y útil**
- Mensaje claro de error
- Sugerencias de navegación
- Lista de posts recientes
- Lista de categorías con conteo
- Formulario de búsqueda
- Links útiles
- Diseño amigable

#### Search Results (Issue #14)
- **Resultados de búsqueda optimizados**
- Contador de resultados
- Highlight de términos buscados
- Grid de resultados con thumbnails
- Excerpts con contexto
- Mensaje cuando no hay resultados
- Sugerencias alternativas
- Paginación de resultados

#### Comments System (Issue #16)
- **Sistema de comentarios mejorado**
- Formulario responsive
- Campos optimizados
- Validación HTML5
- Respuestas anidadas (threaded comments)
- Avatar support
- Moderación de comentarios
- Anti-spam ready

### Accesibilidad (Issue #3)

#### WCAG 2.1 AA Compliant
- **Contrastes de color óptimos** (mínimo 4.5:1)
- **Skip-to-content link** visible al recibir focus
- **ARIA labels** en navegación y widgets
- **Screen reader text** para elementos visuales
- **role attributes** semánticos en toda la estructura
- **Keyboard navigation** completamente funcional
- **Focus states** visibles en todos los elementos interactivos
- **Alt text** automático en imágenes
- **Semantic HTML5**: nav, header, footer, main, article, aside
- Estilos dedicados (assets/css/accessibility.css)

### Panel de Opciones del Tema (Issue #15)

#### Theme Options Completo
- **Panel de administración profesional** en Apariencia > Theme Options
- **6 Tabs organizadas**:

##### 1. General Settings
- Logo upload
- Favicon
- Site tagline personalizado
- Copyright text
- Configuración de timezone

##### 2. Performance
- Lazy loading toggle
- Image optimization settings
- CSS/JS minification
- Cache settings
- WebP conversion
- AdSense delay load
- Resource hints configuration

##### 3. SEO Settings
- Meta description default
- Social media handles
- Open Graph defaults
- Schema.org settings
- Breadcrumbs enable/disable
- Canonical URLs

##### 4. Typography
- Google Fonts integration
- Bunny Fonts (GDPR-compliant)
- System fonts
- Font family para headings
- Font family para body
- Font sizes
- Line heights
- Font weights

##### 5. Content Settings
- Table of Contents (TOC):
  - Enable/disable
  - Posición
  - Mínimo de headings
  - Profundidad de headings
- Related Posts:
  - Enable/disable
  - Número de posts
  - Título personalizado
  - Orden
- Excerpt length
- Read more text
- Featured images en archives
- Author bio display

##### 6. Advanced
- Custom CSS
- Custom JavaScript
- Header scripts
- Footer scripts
- Google Analytics ID
- Facebook Pixel
- Custom tracking codes

#### Características del Panel
- **Save Settings** con AJAX
- **Reset to Defaults** con confirmación
- **Import/Export** settings
- **Visual feedback** de guardado
- **Validación de campos**
- **Color pickers** integrados
- **Media uploader** de WordPress
- **Code editors** con syntax highlighting
- **Help tooltips** en opciones complejas

### Funcionalidad WordPress (Issues #1, #6, #17)

#### Theme Support
- **add_theme_support('title-tag')**: Títulos dinámicos
- **add_theme_support('post-thumbnails')**: Imágenes destacadas
- **add_theme_support('html5')**: Markup HTML5 semántico
- **add_theme_support('automatic-feed-links')**: RSS feeds automáticos
- **add_theme_support('custom-logo')**: Logo personalizable
- **add_theme_support('customize-selective-refresh-widgets')**: Refresh de widgets

#### Tamaños de Imagen Personalizados
- `apus-thumbnail`: 400x300px (crop)
- `apus-medium`: 800x600px (crop)
- `apus-large`: 1200x900px (crop)
- `apus-featured-large`: 1200x600px (crop)
- `apus-featured-medium`: 800x400px (crop)

#### Menús de Navegación
- **Primary Menu**: Menú principal del header
- **Footer Menu**: Menú en el footer (1 nivel)

#### Widget Areas
- **Primary Sidebar**: Barra lateral principal
- **Footer Column 1**: Primera columna del footer
- **Footer Column 2**: Segunda columna del footer
- **Footer Column 3**: Tercera columna del footer
- **Footer Column 4**: Cuarta columna del footer

#### Internacionalización
- **Translation Ready**: Completamente traducible
- **Locale español México** (es_MX) por defecto
- **Formato de fecha**: d/m/Y
- **Text Domain**: apus-theme
- **POT file ready** para traducciones

#### Content Width
- 1200px configurable via filter

### Desarrollo (Issues #1, #15, #17)

#### Arquitectura Modular
- **Código organizado y mantenible**
- **WordPress Coding Standards** compliant
- **Hooks y Filters** extensibles
- **Child Theme Ready**
- **No dependencias pesadas**
- **Comentarios y documentación** en código

#### Archivos Inc Modulares
- **inc/enqueue-scripts.php**: Sistema de enqueue para CSS/JS
- **inc/performance.php**: Optimizaciones de rendimiento
- **inc/template-functions.php**: Funciones auxiliares del tema
- **inc/template-tags.php**: Template tags personalizados
- **inc/seo.php**: Funciones SEO
- **inc/image-optimization.php**: Optimización de imágenes
- **inc/customizer-fonts.php**: Sistema de fuentes
- **inc/featured-image.php**: Gestión de featured images
- **inc/category-badge.php**: Badges de categorías
- **inc/related-posts.php**: Posts relacionados
- **inc/toc.php**: Table of Contents
- **inc/adsense-delay.php**: AdSense delay load
- **inc/theme-options-helpers.php**: Helpers del panel de opciones
- **inc/admin/**: Panel de opciones del tema
  - theme-options.php
  - options-api.php
  - options-page-template.php
  - related-posts-options.php

#### Hooks Personalizados
```php
do_action('apus_before_post_content');
do_action('apus_after_post_content');
do_action('apus_before_header');
do_action('apus_after_header');
do_action('apus_before_footer');
do_action('apus_after_footer');
```

#### Filters Personalizados
```php
apply_filters('apus_content_width', 1200);
apply_filters('apus_excerpt_length', 55);
apply_filters('apus_read_more_text', 'Leer más');
apply_filters('apus_footer_columns', 4);
```

## Requisitos del Sistema

### Requisitos Mínimos
- **WordPress**: 6.0 o superior
- **PHP**: 8.0 o superior (7.4 funcionará pero no recomendado)
- **MySQL**: 5.7 o superior / MariaDB 10.2 o superior
- **Memoria PHP**: 128 MB mínimo (256 MB recomendado)
- **Espacio en Disco**: 50 MB para el tema
- **mod_rewrite**: Habilitado (para permalinks)

### Requisitos Recomendados
- **WordPress**: Última versión estable (6.4+)
- **PHP**: 8.1 o superior
- **MySQL**: 8.0 o superior / MariaDB 10.5 o superior
- **Memoria PHP**: 256 MB o más
- **HTTPS**: Certificado SSL instalado
- **Opcache**: Habilitado para mejor rendimiento
- **Gzip**: Compresión habilitada

### Compatibilidad de Navegadores
- Chrome (últimas 2 versiones)
- Firefox (últimas 2 versiones)
- Safari (últimas 2 versiones)
- Edge (últimas 2 versiones)
- Opera (últimas 2 versiones)
- Mobile browsers (iOS Safari, Chrome Mobile)

### Plugins Compatibles
- **Rank Math SEO**: 100% compatible
- **Yoast SEO**: Compatible
- **WP Rocket**: Totalmente compatible
- **Smush**: Optimización de imágenes
- **Contact Form 7**: Formularios
- **WPForms**: Formularios
- **Google Analytics**: Via Theme Options
- **AdSense**: Via Theme Options con delay load

## Instalación

### Instalación Estándar

#### Método 1: Via WordPress Dashboard
1. Ve a `Apariencia > Temas > Añadir nuevo`
2. Haz clic en "Subir tema"
3. Selecciona el archivo ZIP del tema
4. Haz clic en "Instalar ahora"
5. Activa el tema

#### Método 2: Via FTP
1. Descomprime el archivo ZIP del tema
2. Conecta por FTP a tu servidor
3. Sube la carpeta `apus-theme` a `/wp-content/themes/`
4. Ve a `Apariencia > Temas` en WordPress
5. Activa "Apus Theme"

#### Método 3: Via Git (Desarrollo)
```bash
cd wp-content/themes/
git clone [repository-url] apus-theme
```

### Después de la Instalación

#### 1. Configurar Permalinks
```
Ajustes > Enlaces permanentes > Nombre de la entrada
```
Esto es CRÍTICO para el correcto funcionamiento del tema.

#### 2. Configurar Lectura
```
Ajustes > Lectura
```
- Establece tu página de inicio (estática o últimas entradas)
- Configura el número de entradas por página (recomendado: 10-12)

#### 3. Regenerar Miniaturas (Si tienes contenido existente)
```bash
# Con WP-CLI
wp media regenerate --yes

# O usa el plugin "Regenerate Thumbnails"
```

## Configuración Inicial

Ver documentación detallada en [docs/01-initial-setup.md](docs/01-initial-setup.md)

### Quick Start

#### 1. Logo del Sitio
```
Apariencia > Personalizar > Identidad del sitio > Logo
```
- Tamaño recomendado: 200px de ancho máximo
- Formatos: PNG (transparente), SVG, JPG

#### 2. Menús de Navegación
```
Apariencia > Menús
```
- Crea un menú y asígnalo a "Primary Menu"
- Opcionalmente crea un menú footer y asígnalo a "Footer Menu"

#### 3. Widgets
```
Apariencia > Widgets
```
- Configura "Primary Sidebar" con widgets
- Configura las 4 columnas del footer si deseas

#### 4. Theme Options
```
Apariencia > Theme Options
```
- Configura las opciones básicas de rendimiento
- Activa/desactiva TOC y Related Posts
- Configura fuentes si deseas cambiar las del sistema
- Agrega códigos de tracking (GA, FB Pixel, etc.)

#### 5. Plugins Recomendados
- **Rank Math SEO**: Para SEO completo
- **WP Rocket**: Para cache y optimización (opcional pero recomendado)
- **Smush**: Para optimización de imágenes
- **Contact Form 7**: Para formularios de contacto

## Estructura de Archivos

```
apus-theme/
├── assets/
│   ├── css/
│   │   ├── accessibility.css      # Estilos de accesibilidad
│   │   ├── animations.css         # Animaciones y transiciones
│   │   ├── bootstrap.min.css      # Bootstrap 5.3
│   │   ├── fonts.css              # Sistema de fuentes
│   │   ├── footer.css             # Estilos del footer
│   │   ├── header.css             # Estilos del header
│   │   ├── print.css              # Estilos de impresión
│   │   ├── related-posts.css      # Posts relacionados
│   │   ├── responsive.css         # Media queries
│   │   ├── theme.css              # Estilos principales
│   │   ├── toc.css                # Table of Contents
│   │   └── utilities.css          # Utilidades
│   ├── js/
│   │   ├── adsense-loader.js      # Carga diferida de AdSense
│   │   ├── bootstrap.bundle.min.js # Bootstrap JS
│   │   ├── header.js              # Funcionalidad del header
│   │   └── toc.js                 # Table of Contents JS
│   └── admin/
│       ├── css/
│       │   └── theme-options.css  # Estilos del panel admin
│       └── js/
│           └── theme-options.js   # JS del panel admin
├── inc/
│   ├── admin/
│   │   ├── options-api.php        # API del panel de opciones
│   │   ├── options-page-template.php # Template del panel
│   │   ├── related-posts-options.php # Opciones de related posts
│   │   ├── theme-options.php      # Configuración del panel
│   │   └── USAGE-EXAMPLES.php     # Ejemplos de uso
│   ├── adsense-delay.php          # AdSense delay load
│   ├── category-badge.php         # Badges de categorías
│   ├── customizer-fonts.php       # Sistema de fuentes
│   ├── enqueue-scripts.php        # Enqueue de assets
│   ├── featured-image.php         # Gestión de featured images
│   ├── image-optimization.php     # Optimización de imágenes
│   ├── performance.php            # Optimizaciones
│   ├── related-posts.php          # Posts relacionados
│   ├── seo.php                    # Funciones SEO
│   ├── template-functions.php     # Funciones auxiliares
│   ├── template-tags.php          # Template tags
│   ├── theme-options-helpers.php  # Helpers de opciones
│   └── toc.php                    # Table of Contents
├── template-parts/
│   ├── content.php                # Template de contenido
│   └── content-none.php           # Sin resultados
├── languages/
│   └── es_MX.po                   # Traducción español
├── docs/
│   ├── 01-initial-setup.md        # Configuración inicial
│   ├── 02-theme-options.md        # Guía del panel de opciones
│   └── 03-performance-seo.md      # Performance y SEO
├── 404.php                        # Página 404
├── archive.php                    # Template de archivos
├── comments.php                   # Sistema de comentarios
├── footer.php                     # Footer del sitio
├── front-page.php                 # Página de inicio
├── functions.php                  # Funciones principales
├── header.php                     # Header del sitio
├── index.php                      # Template principal
├── page.php                       # Template de páginas
├── search.php                     # Resultados de búsqueda
├── sidebar.php                    # Barra lateral
├── single.php                     # Template de entradas
├── style.css                      # Estilos y metadata
├── CHANGELOG.md                   # Historial de cambios
├── CREDITS.md                     # Créditos y licencias
├── LICENSE                        # Licencia GPL v2
└── README.md                      # Este archivo
```

## Documentación Completa

### Guías Disponibles

1. **[01-initial-setup.md](docs/01-initial-setup.md)**
   - Activación del tema paso a paso
   - Configuración de portada estática
   - Configuración de menús y widgets
   - Ajustes básicos recomendados

2. **[02-theme-options.md](docs/02-theme-options.md)**
   - Guía completa del panel Theme Options
   - Explicación de cada tab y opción
   - Mejores prácticas de configuración

3. **[03-performance-seo.md](docs/03-performance-seo.md)**
   - Qué hace el tema por performance
   - Configuración de Rank Math
   - Recomendaciones de hosting
   - Best practices de SEO

## Personalización

### Crear un Child Theme

Para personalizar sin perder cambios en actualizaciones:

#### 1. Crear Estructura
```bash
mkdir wp-content/themes/apus-child
```

#### 2. Crear style.css
```css
/*
Theme Name: Apus Child Theme
Template: apus-theme
Version: 1.0.0
*/
```

#### 3. Crear functions.php
```php
<?php
/**
 * Apus Child Theme Functions
 */

// Enqueue parent styles
function apus_child_enqueue_styles() {
    wp_enqueue_style('apus-parent-style', get_template_directory_uri() . '/style.css');
    wp_enqueue_style('apus-child-style', get_stylesheet_uri(), array('apus-parent-style'), '1.0.0');
}
add_action('wp_enqueue_scripts', 'apus_child_enqueue_styles');
```

### Hooks Disponibles

#### Action Hooks
```php
// Header
do_action('apus_before_header');
do_action('apus_after_header');

// Content
do_action('apus_before_post_content');
do_action('apus_after_post_content');

// Footer
do_action('apus_before_footer');
do_action('apus_after_footer');
```

#### Filter Hooks
```php
// Modificar ancho del contenido
add_filter('apus_content_width', function($width) {
    return 1400;
});

// Modificar longitud del excerpt
add_filter('apus_excerpt_length', function($length) {
    return 80;
});

// Modificar texto "Leer más"
add_filter('apus_read_more_text', function($text) {
    return 'Continuar leyendo';
});

// Modificar columnas del footer
add_filter('apus_footer_columns', function($columns) {
    return 3; // Cambia a 3 columnas
});
```

## Soporte y Recursos

### Documentación
- [WordPress Theme Handbook](https://developer.wordpress.org/themes/)
- [Bootstrap 5 Documentation](https://getbootstrap.com/docs/5.3/)
- [Rank Math Documentation](https://rankmath.com/kb/)

### Reportar Issues
Si encuentras algún problema:
1. Verifica requisitos mínimos
2. Revisa la documentación
3. Desactiva otros plugins para descartar conflictos
4. Reporta en: [GitHub Issues](https://github.com/tu-repo/apus-theme/issues)

### Solución de Problemas Comunes

#### El menú no se muestra
- Ve a Apariencia > Menús
- Crea un menú y asígnalo a "Primary Menu"

#### Las imágenes no se ven
- Regenera miniaturas con WP-CLI o plugin
- Verifica permisos de la carpeta uploads

#### El tema se ve sin estilos
- Verifica que los permalinks estén configurados
- Limpia el cache del navegador
- Desactiva plugins de optimización temporalmente

## Créditos

Ver archivo [CREDITS.md](CREDITS.md) para listado completo.

### Principales Recursos
- **Bootstrap 5.3.0** - MIT License
- **WordPress** - GPL v2 or later
- **Font Awesome Icons** (si se usa)

### Desarrollado Por
Apus Development Team
Proyecto: Análisis de Precios Unitarios
Website: https://analisisdepreciosunitarios.com

## Licencia

Este tema está licenciado bajo GPL v2 o posterior.

```
Copyright (C) 2024 Apus Development Team

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
```

Ver el archivo [LICENSE](LICENSE) para más detalles.

## Changelog

Ver [CHANGELOG.md](CHANGELOG.md) para el historial completo de cambios y versiones.

## Roadmap Futuro

### v1.1.0 (Planificado)
- Gutenberg blocks personalizados
- Color scheme customizer
- Advanced typography options
- Page templates adicionales

### v1.2.0 (Planificado)
- WooCommerce support
- Mega menu functionality
- Advanced footer builder
- Dark mode toggle

---

**Última actualización:** Noviembre 2024
**Versión del documento:** 1.0.0
**Issues completados:** #1-#20