Introducción
En este tutorial aprenderás a crear y estilizar manualmente un bloque de Lista de contenidos (Table of Contents, TOC) para WordPress usando HTML y CSS. El objetivo es: generar una lista de enlaces que apunten a los encabezados de la entrada/página, estilizarla, hacerla accesible y responsive, y ofrecer una solución ligera que no dependa de plugins externos.
Requisitos y consideraciones previas
- Editor de bloques (Gutenberg) o cualquier editor que permita editar HTML de bloques.
- Permiso para añadir CSS personalizado (Apariencia gt Personalizar gt CSS adicional, o en el tema hijo).
- Opcional: posibilidad de añadir un pequeño JavaScript encolado si quieres resaltar el enlace activo mientras se hace scroll.
- Atención a la accesibilidad: los enlaces deben ser navegables con teclado y tener estados visibles de foco.
Estructura HTML típica de la Lista de contenidos
La forma más sencilla es una lista desordenada con enlaces a los IDs de los encabezados presentes en el documento. En el editor de bloques puedes generar manualmente esta lista añadiendo anclas (IDs) a cada encabezado o usar el campo HTML anchor de cada bloque.
Ejemplo de estructura HTML para una TOC básica:
Ejemplo de encabezados en la entrada con IDs (puedes añadir el ID desde la barra lateral del bloque o editar HTML):
Introducción
Instalación
Configuración
Opciones avanzadas
Conclusiones
CSS base para estilizar la TOC
El siguiente CSS cubre: contenedor, espaciado, lista anidada, estilo de enlaces, estados hover y focus, saltos suaves, y un comportamiento básico responsive (colapsar en pantallas pequeñas). Pega este CSS en el CSS adicional de tu tema o en el archivo style.css del tema hijo.
/ Estilos base para la TOC /
.toc {
border: 1px solid rgba(0,0,0,0.08)
background: #fff
padding: 1rem
border-radius: 6px
font-family: system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, Arial
font-size: 0.95rem
line-height: 1.4
}
/ Título dentro (si añades) /
.toc .toc-title {
font-weight: 700
margin-bottom: 0.6rem
}
/ Lista principal /
.toc-list {
list-style: none
margin: 0
padding: 0
}
/ Ítems /
.toc-item {
margin: 0.25rem 0
}
/ Niveles anidados (por ejemplo h3 dentro h2) /
.toc-item.toc-level-2 { padding-left: 1.0rem font-size: 0.92em color: #444 }
.toc-item.toc-level-3 { padding-left: 1.8rem font-size: 0.88em color: #666 }
/ Enlaces /
.toc a {
color: #1a73e8
text-decoration: none
display: inline-block
padding: 0.18rem 0.25rem
border-radius: 4px
}
/ Hover y focus visibles (accesibilidad) /
.toc a:hover,
.toc a:focus {
background: rgba(26,115,232,0.08)
outline: none
}
/ Estilo para enlace activo (cuando se utiliza JS para añadir clase is-active) /
.toc a.is-active,
.toc a[aria-current=true] {
background: #1a73e8
color: #fff
box-shadow: 0 1px 0 rgba(0,0,0,0.04) inset
}
/ Suavizado del scroll cuando se usa hash /
html {
scroll-behavior: smooth
}
/ Sticky (mantener la TOC visible en pantallas grandes) /
@media (min-width: 992px) {
.toc {
position: sticky
top: 1.4rem
}
}
/ Responsive: esconder TOC y mostrar un botón simple en móviles (requiere un poco de JS para toggle) /
@media (max-width: 768px) {
.toc {
display: none / cambia con JS si implementas toggle /
}
}
/ Estilos para foco con teclado - muy importante para accesibilidad /
.toc a:focus {
box-shadow: 0 0 0 3px rgba(26,115,232,0.18)
}
Cómo añadir anclas (IDs) a los encabezados en Gutenberg
- Selecciona el bloque de encabezado en el editor.
- En la barra lateral derecha, busca Avanzado y el campo HTML anchor.
- Introduce un identificador corto y sin espacios (por ejemplo: introduccion, instalacion).
- En la TOC crea enlaces que apunten a esos identificadores: href=#instalacion.
Mejorando la usabilidad: mostrar el enlace activo mientras se hace scroll (JavaScript ligero)
Para que el enlace correspondiente al encabezado visible se marque con la clase is-active, puedes añadir este script. Crea un archivo JS y encolalo desde functions.php o utiliza un plugin que permita scripts personalizados.
Código JavaScript sugerido:
document.addEventListener(DOMContentLoaded, function () {
const tocLinks = Array.from(document.querySelectorAll(.toc a))
const headingIds = tocLinks.map(link => link.getAttribute(href)).filter(Boolean)
const headings = headingIds.map(id => document.querySelector(id)).filter(Boolean)
function onScroll() {
const offset = 120 // ajuste para top bar / admin bar
let activeIndex = -1
for (let i = 0 i < headings.length i ) {
const rect = headings[i].getBoundingClientRect()
if (rect.top - offset <= 0) {
activeIndex = i
} else {
break
}
}
tocLinks.forEach((link, idx) => {
if (idx === activeIndex) {
link.classList.add(is-active)
link.setAttribute(aria-current, true)
} else {
link.classList.remove(is-active)
link.removeAttribute(aria-current)
}
})
}
window.addEventListener(scroll, onScroll, { passive: true })
onScroll()
})
Ejemplo de cómo encolar ese script (functions.php del tema hijo):
function tema_hijo_enqueue_toc_script() {
wp_enqueue_script(
tema-toc,
get_stylesheet_directory_uri() . /js/tema-toc.js,
array(),
1.0,
true
)
}
add_action(wp_enqueue_scripts, tema_hijo_enqueue_toc_script)
TOC colapsable sin JS (opción limitada)
Si prefieres evitar JavaScript, puedes usar la pseudo-clase :target para alternar la visibilidad, o usar el enfoque con un checkbox oculto (requiere modificar HTML y puede no ser ideal para todos los temas). Aquí tienes un ejemplo simple con :target para mostrar/ocultar el bloque TOC mediante un ancla:
Mostrar índice / .toc { display: none } .toc:target { display: block } /
Nota: el comportamiento con :target tiene limitaciones (volver atrás en el historial del navegador, comportamiento inesperado con enlaces internos), por eso la combinación CSS pequeño JS suele ser la mejor opción.
Accesibilidad y SEO
- Usa un elemento nav con aria-label para indicar que es navegación de la página: ltnav aria-label=Tabla de contenidosgt.
- Asegura que los enlaces sean focusables y tengan contraste suficiente.
- Evita largas listas clónicas: si la entrada es muy corta, no muestres la TOC.
- Los enlaces internos mejoran la experiencia de usuario y pueden ayudar en accesibilidad en cuanto a SEO, no hay impacto negativo en sí, pero evita contenido duplicado.
Patrones avanzados y mejoras
- Numeración automática: puedes mostrar números delante de cada ítem con CSS counters.
- Ítems colapsables por secciones: requiere JS para un comportamiento robusto (activar/ocultar sublistas).
- Animaciones suaves: agrega transiciones para hover y para mostrar/ocultar el TOC.
- Generación dinámica: si prefieres automatizar la creación de la TOC, existen plugins o scripts que generan la lista leyendo los encabezados del contenido en tiempo de ejecución.
Ejemplo rápido de numeración CSS:
.toc-list {
counter-reset: toc-counter
}
.toc-item > a::before {
counter-increment: toc-counter
content: counter(toc-counter) .
color: #6b7280
margin-right: 0.35rem
font-weight: 600
}
Checklist final antes de publicar
- Asegúrate de que cada encabezado tiene un ID único y amigable.
- Verifica que los enlaces de la TOC apuntan correctamente (prueba clic y navegación por teclado).
- Comprueba el contraste y la visibilidad del foco.
- Revisa el comportamiento en móviles (ocultar o mostrar mediante toggle con JS).
- Si usas JS para destacar el enlace activo, confirma que no genera errores en la consola.
Recursos y alternativas
- Si deseas una solución lista para usar, existen plugins como Table of Contents Plus o SimpleTOC, pero la solución manual da más control estético y de rendimiento.
- Documentación sobre accesibilidad: Web Content Accessibility Guidelines (WCAG).
Conclusión
Crear una Lista de contenidos manual en WordPress te permite controlar completamente el diseño, la estructura y la accesibilidad. Con HTML sencillo, CSS moderno y un pequeño script opcional lograrás una TOC ligera, responsive y usable. Implementa anclas en tus encabezados, aplica los estilos base y, si lo deseas, añade un JS que resalte el enlace activo para mejorar la navegación durante el scroll.
Leave a Reply