Personalización

Hudocs organiza sus estilos utilizando capas en cascada CSS (@layer) y tokens de diseño semánticos definidos mediante propiedades personalizadas de CSS en _tokens.scss. Puedes personalizar la apariencia visual de tu documentación sin modificar los archivos originales del tema.

Sobrescribir estilos #

Para personalizar los estilos, crea un archivo assets/scss/_custom.scss en tu proyecto de Hugo:

mi-proyecto/
├── assets/
│   └── scss/
│       └── _custom.scss
└── hugo.toml

Debido a que Hudocs importa _custom.scss fuera de las capas de cascada, las reglas sin capa en tu archivo personalizado tienen precedencia natural sobre los estilos del tema sin requerir alta especificidad o !important.

Variables SCSS #

Hudocs define variables de color base utilizando la bandera !default de Sass. Puedes sobrescribir estas variables antes de que se compilen las reglas del tema:

// assets/scss/_custom.scss
$primary: #2563eb;
$secondary: #7c3aed;

Tokens de Diseño CSS #

Todas las propiedades visuales en Hudocs están vinculadas a propiedades personalizadas de CSS declaradas en :root. Puedes personalizarlas en tu _custom.scss apuntando a :root (para modo claro o valores universales) o a :root.dark (para modo oscuro).

Dimensiones y Diseño #

Estas variables controlan la cuadrícula de la página, los espaciados y las dimensiones de componentes:

Tipografía #

Colores de Marca #

Los tokens de marca definen los roles de acento primario y secundario junto con sus matices para contenedores:

Superficies y Fondos #

Las superficies definen los fondos de la página, contenedores de tarjetas, menús y elementos elevados:

Textos y Bordes #

Notificaciones y Estados #

Estos tokens dan estilo a alertas (shortcode hint), estados y validaciones:

Insignias de Tipos de Datos #

Utilizados por el shortcode type para clasificar tipos de datos de programación:

Bloques de Código y Sintaxis #

Controlan el fondo, tipografía y selección dentro de bloques de código:

Ejemplo de Personalización #

A continuación se muestra un ejemplo completo de assets/scss/_custom.scss que establece una tipografía personalizada, adapta la paleta principal y ajusta las superficies de fondo:

// 1. Sobrescribir variables SCSS
$primary: #0284c7;

// 2. Sobrescribir tokens CSS
:root {
  --font-primary: 'Poppins', sans-serif;
  --header-height: 64px;

  // Superficies personalizadas en modo claro
  --surface: #ffffff;
  --surface-container: #f8fafc;
}

:root.dark {
  // Superficies personalizadas en modo oscuro
  --surface: #0f172a;
  --surface-container: #1e293b;
  --primary: #38bdf8;
}