Tema Apacible: Guía Completa de Características

Esta guía completa demuestra todas las características y capacidades del tema Apacible para Hugo. Desde markdown básico hasta shortcodes avanzados, procesamiento de imágenes y contenido técnico—todo lo que necesitas saber está aquí.

Introducción

El tema Apacible es un tema minimalista para Hugo que prioriza la accesibilidad y los principios de smolweb, con soporte único para imágenes difuminadas. Esta guía cubre cada característica con ejemplos prácticos.

Características de Markdown

El tema soporta todas las características estándar de Markdown con un estilo hermoso.

Encabezados

Los encabezados crean una jerarquía clara en tu contenido:

Encabezado Nivel 2

Encabezado Nivel 3

Encabezado Nivel 4

Énfasis

Texto normal, texto en negrita, texto en cursiva, texto en negrita y cursiva, y texto tachado.

Listas

Listas desordenadas:

• Primer elemento
• Segundo elemento
• Tercer elemento

Listas ordenadas:

1. Primer elemento
   1. Elemento con sangría
   2. Elemento con sangría
2. Segundo elemento
3. Tercer elemento

Enlaces

Hay un enlace y otro enlace a example.com.

Tablas

Tabla básica:

Con alineación:

Citas

Lorem ipsum dolor sit, amet consectetur adipisicing elit. Praesentium, nisi saepe dolor unde iusto dolore nam, vero optio consequuntur repudiandae et! Atque libero expedita laudantium cupiditate, sit explicabo sequi ipsa!

Lorem ipsum dolor sit, amet consectetur adipisicing elit.

Cita anidada: Praesentium, nisi saepe dolor unde iusto dolore nam, vero optio consequuntur repudiandae et! Atque libero expedita laudantium cupiditate, sit explicabo sequi ipsa!

Notas al pie

Lorem ipsum dolor sit, amet¹ palabras consectetur² adipisicing elit.

Regla horizontal

Shortcodes

Los shortcodes extienden Markdown con funcionalidad personalizada potente.

Llamadas de atención

Las llamadas de atención son útiles para resaltar información importante.

Citas

Citas con estilo hermoso para resaltar declaraciones importantes.

Contenido Detalle/Expandible

Combinando Shortcodes

Puedes combinar shortcodes para contenido rico:

Imágenes Difuminadas

El tema incluye funcionalidad única para imágenes difuminadas. Las imágenes se muestran en su forma difuminada por defecto, lo que reduce el tamaño del archivo mientras mantiene una estética única. Haz clic en el enlace “→ mostrar original” debajo de cada imagen para alternar entre las versiones difuminada y original.

Imagen Difuminada Individual

Image not found: example-dithered-images/musician.jpeg

El efecto de difuminado reduce la imagen a una paleta de colores limitada, creando una estética retro distintiva mientras reduce significativamente el tamaño del archivo—perfecto para la filosofía smolweb.

Comparación Lado a Lado

Para una comparación directa, aquí está la misma imagen mostrada en ambas formas:

Image not found:

Cómo Funciona

Procesamiento: Las imágenes se difuminan usando el algoritmo de difuminado ordenado de ImageMagick:

magick input.jpg \
    -colorspace gray \
    -contrast-stretch 5%x5% \
    -normalize \
    -posterize 2 \
    -ordered-dither o4x4 \
    output_dithered.jpg

Mecanismo de Alternancia: El shortcode genera HTML con ambas versiones. JavaScript alterna la visibilidad cuando se hace clic en el enlace:

function toggleOriginal(element) {
  const container = element.closest('.image-container') || 
                    element.closest('figure').querySelector('.image-container');
  const dithered = container.querySelector('.dithered-img');
  const original = container.querySelector('.original-img');
  const showText = element.querySelector('.show-text');
  const hideText = element.querySelector('.hide-text');
  
  // Toggle visibility
  dithered.classList.toggle('active');
  original.style.display = dithered.classList.contains('active') ? 'none' : 'block';
  
  // Toggle link text
  showText.style.display = dithered.classList.contains('active') ? 'inline' : 'none';
  hideText.style.display = dithered.classList.contains('active') ? 'none' : 'inline';
}

Beneficios:

• Archivos Más Pequeños: Las imágenes difuminadas son típicamente 40-60% más pequeñas
• Carga Más Rápida: Uso reducido de ancho de banda
• Mejora Progresiva: Original disponible bajo demanda
• Estilo Único: Identidad visual distintiva
• Atractivo Retro: Estética nostálgica de 8 bits
• Alto Contraste: A menudo más legible
• Alineado con Smolweb: Transferencia mínima de datos
• Elección del Usuario: Original disponible cuando se necesita
• Accesibilidad: Alto contraste mejora la legibilidad

Uso:

{{< img 
    src="image.jpg" 
    alt="Descripción" 
    caption="Tu leyenda aquí" 
    dithered="true" 
    width="800" 
    height="600" 
>}}

Nota: Debes tener tanto la imagen original como su versión difuminada (con el sufijo _dithered) en tu carpeta de assets. Usa el script scripts/dither_images.sh para generar versiones difuminadas automáticamente.

Detalles Técnicos:

• Algoritmo: Difuminado ordenado (patrón 4x4) con alto contraste y posterización
• Espacio de Color: Conversión a escala de grises antes del difuminado
• Formato: Soporta JPEG, PNG, WebP
• Responsive: El procesamiento de imágenes de Hugo crea tamaños optimizados
• Respaldo: Si falta la versión difuminada, muestra solo la original

Bloques de Código y Resaltado de Sintaxis

El tema soporta resaltado de sintaxis para muchos lenguajes de programación.

HTML

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <main>
        <h1>Hello World</h1>
        <p>Welcome to my site.</p>
    </main>
    <script src="script.js"></script>
</body>
</html>

CSS

:root {
    --primary-color: #3498db;
    --secondary-color: #2ecc71;
    --font-stack: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}

.container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 2rem;
}

@media (prefers-color-scheme: dark) {
    :root {
        --primary-color: #5dade2;
        --secondary-color: #58d68d;
    }
}

Python

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional

app = FastAPI()

class Item(BaseModel):
    id: int
    name: str
    description: Optional[str] = None
    price: float

items_db = []

@app.get("/items", response_model=List[Item])
async def get_items():
    return items_db

@app.post("/items", response_model=Item)
async def create_item(item: Item):
    items_db.append(item)
    return item

JavaScript

function binarySearch(arr, target) {
  let left = 0;
  let right = arr.length - 1;
  
  while (left <= right) {
    const mid = Math.floor((left + right) / 2);
    
    if (arr[mid] === target) {
      return mid; // Found!
    } else if (arr[mid] < target) {
      left = mid + 1;
    } else {
      right = mid - 1;
    }
  }
  
  return -1; // Not found
}

SQL

-- Create a users table
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Query with joins
SELECT 
    u.username,
    u.email,
    COUNT(p.id) as post_count
FROM users u
LEFT JOIN posts p ON u.id = p.user_id
GROUP BY u.id, u.username, u.email
HAVING COUNT(p.id) > 5
ORDER BY post_count DESC;

Bash

#!/bin/bash
set -e

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m' # No Color

echo -e "${GREEN}Starting deployment...${NC}"

# Run tests
if npm test; then
    echo -e "${GREEN}Tests passed!${NC}"
else
    echo -e "${RED}Tests failed!${NC}"
    exit 1
fi

El tema soporta muchos más lenguajes incluyendo Go, Ruby, PHP, Java, C++, Rust, y más. Todo el código se muestra con resaltado de sintaxis apropiado basado en el identificador de lenguaje en la cerca de código.

Notación Matemática (KaTeX)

Ecuaciones matemáticas renderizadas hermosamente con KaTeX.

Matemáticas en Línea

La fórmula cuadrática es $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$ cuando $a \ne 0$.

La famosa ecuación de Einstein: $E = mc^2$

Matemáticas en Bloque

La transformada de Fourier:

La Desigualdad de Cauchy-Schwarz:

Para habilitar el renderizado de matemáticas, agrega math = true al frontmatter de tu publicación.

Diagramas Mermaid

Potenciado por Mermaid

Los diagramas Mermaid son geniales para visualizar procesos, flujos de trabajo y relaciones.

Diagrama de Secuencia

sequenceDiagram
    participant web as Web Browser
    participant blog as Blog Service
    participant account as Account Service
    participant mail as Mail Service
    participant db as Storage

    Note over web,db: The user must be logged in to submit blog posts
    web->>+account: Logs in using credentials
    account->>db: Query stored accounts
    db->>account: Respond with query result

    alt Credentials not found
        account->>web: Invalid credentials
    else Credentials found
        account->>-web: Successfully logged in

        Note over web,db: When the user is authenticated, they can now submit new posts
        web->>+blog: Submit new post
        blog->>db: Store post data

        par Notifications
            blog--)mail: Send mail to blog subscribers
            blog--)db: Store in-site notifications
        and Response
            blog-->>-web: Successfully posted
        end
    end
  

Diagrama de Flujo

graph LR
    A[Square Rect] -- Link text --> B((Circle))
    A --> C(Round Rect)
    B --> D{Rhombus}
    C --> D
  

Gráfico Git

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': false}} }%%
gitGraph
  commit id: "feat(api): ..."
  commit id: "a"
  commit id: "b"
  commit id: "fix(client): .extra long label.."
  branch c2
  commit id: "feat(modules): ..."
  commit id: "test(client): ..."
  checkout main
  commit id: "fix(api): ..."
  commit id: "ci: ..."
  branch b1
  commit
  branch b2
  commit
  

Gráfico de Cuadrantes

quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]
  

Contenido de Forma Larga y Estructura

El contenido de forma larga sirve un propósito importante en la era digital. Si bien el contenido corto y directo tiene su lugar, la exploración más profunda de temas requiere espacio para respirar y desarrollar ideas completamente.

Tabla de Contenidos

Habilita la tabla de contenidos automática agregando toc = true a tu frontmatter. Esta página lo tiene habilitado—¡revisa la barra lateral!

Estructura y Organización

El contenido de forma larga efectivo requiere una estructura cuidadosa:

Jerarquía Clara: Usa encabezados y subencabezados para crear un esquema claro. Los lectores deberían poder escanear la estructura y entender el flujo de ideas de un vistazo.

Progresión Lógica: Las ideas deben construirse unas sobre otras. Cada sección debe conectarse naturalmente con la siguiente, creando una narrativa o argumento cohesivo.

Pausas Visuales: Divide el texto con:

• Subencabezados
• Citas destacadas
• Listas
• Imágenes
• Bloques de código
• Espacios en blanco

Transiciones: Buenas transiciones entre secciones ayudan a los lectores a seguir tu línea de pensamiento. Proporcionan contexto y mantienen el impulso.

Técnicas de Escritura

Narrativa: Incluso el contenido técnico o educativo se beneficia de elementos narrativos. Las historias hacen que los conceptos abstractos sean concretos y memorables.

Estructura de Oraciones Variada: Mezcla oraciones cortas y directas con otras más largas y complejas. Esto crea ritmo y mantiene a los lectores comprometidos.

Las oraciones cortas enfatizan puntos. Crean impacto. Las oraciones más largas, por otro lado, te permiten desarrollar ideas más matizadas y explorar las relaciones entre conceptos, creando una comprensión más sofisticada y en capas del tema en cuestión.

Voz Activa: La voz activa crea escritura más clara y directa. En lugar de “se cometieron errores,” di “cometimos errores.” Es más honesto y más fácil de leer.

Ejemplos Concretos: Los conceptos abstractos se vuelven más claros con ejemplos específicos. No solo le digas a los lectores algo—muéstrales con casos del mundo real, datos o escenarios.

Alerta de Contenido Desactualizado

El tema puede alertar automáticamente a los lectores cuando el contenido está desactualizado. Habilítalo agregando a tu frontmatter:

outdate_alert = true
outdate_alert_days = 90

Cuando una publicación es más antigua que el número especificado de días, se mostrará una alerta en la parte superior de la publicación. Esto ayuda a mantener la calidad del contenido e informa a los lectores cuando la información puede estar desactualizada.

Ejemplos Técnicos

El tema sobresale en mostrar contenido técnico con formato adecuado y resaltado de sintaxis.

Ejemplos de Algoritmos

Quick Sort (Python):

def quicksort(arr):
    """
    Quick sort algorithm implementation.
    Time complexity: O(n log n) average case
    Space complexity: O(log n)
    """
    if len(arr) <= 1:
        return arr
    
    pivot = arr[len(arr) // 2]
    left = [x for x in arr if x < pivot]
    middle = [x for x in arr if x == pivot]
    right = [x for x in arr if x > pivot]
    
    return quicksort(left) + middle + quicksort(right)

# Example usage
numbers = [3, 6, 8, 10, 1, 2, 1]
sorted_numbers = quicksort(numbers)
print(f"Sorted: {sorted_numbers}")

Archivos de Configuración

Configuración TOML:

base_url = "https://example.com"
title = "My Site"
description = "A demo site"

compile_sass = true
minify_html = false

[markdown]
highlight_code = true
highlight_theme = "base16-ocean-dark"
render_emoji = false

Configuración JSON:

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "A sample project",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "build": "webpack --mode production"
  },
  "dependencies": {
    "express": "^4.18.0",
    "dotenv": "^16.0.0"
  }
}

Características Adicionales

Modo Oscuro

El tema incluye modo oscuro automático con persistencia en localStorage. Los usuarios pueden alternar entre temas claro y oscuro, y su preferencia se guarda.

Diseño Responsive

Todas las características son completamente responsive y funcionan hermosamente en dispositivos móviles, tabletas y escritorio.

Accesibilidad

El tema prioriza la accesibilidad con:

• Contrastes de color compatibles con WCAG
• HTML semántico
• Soporte de navegación por teclado
• Marcado amigable para lectores de pantalla

Rendimiento

• Procesamiento de imágenes optimizado
• JavaScript mínimo
• Cargas de página rápidas
• Filosofía smolweb

Conclusión

El tema Apacible proporciona un conjunto completo de características para crear sitios web hermosos, accesibles y de alto rendimiento. Desde markdown básico hasta contenido técnico avanzado, todo está diseñado para funcionar juntos sin problemas.

Ya sea que estés escribiendo publicaciones de blog, documentación técnica o artículos de forma larga, el tema tiene las herramientas que necesitas para crear contenido atractivo y legible.

Para más información, consulta el README del tema o explora el código fuente.