Tutorial WordPress: Estilizar el bloque Table of Contents de Rank Math/Yoast con CSS

Introducción

En este tutorial detallado aprenderás a estilizar el bloque Table of Contents que ofrecen plugins como Rank Math y Yoast mediante CSS. Cubriremos cómo identificar el marcado HTML que generan ambos plugins, selectores comunes, estilos base y avanzados (cuadros, numeración, anclajes, estado activo, sticky, responsive y accesibilidad). Incluiré ejemplos listos para pegar en tu CSS o en el personalizador del tema. Si el bloque usa otra clase, te explico cómo localizarla y aplicar los mismos principios.

Antes de empezar: localizar la clase correcta

Cada plugin o tema puede exportar un HTML ligeramente distinto. Antes de añadir CSS, usa las herramientas de desarrollador del navegador (Inspect / Inspeccionar elemento) y busca el contenedor del TOC. Buscadores comunes de clases:

Rank Math: posibles selectores habituales: .rank-math-toc, .rank-math-table-of-contents, .rank-math-toc-list.
Yoast: posibles selectores habituales: .yoast-toc, .wp-block-yoast-toc, .wp-block-yoast-blocks-table-of-contents.
Si añadiste una clase CSS personalizada en el bloque (recomendado): usarás esa clase, por ejemplo .mi-toc.

Ejemplo rápido para confirmar: en la consola, al inspeccionar el bloque verás una estructura tipo ltdiv class=…toc…gt con una lista ul/li o una serie de anclas lta href=#idgt. Utiliza ese nombre de clase en tus selectores.

Estilos base recomendados

Primero, un conjunto de reglas base que funcionan bien para la mayoría de TOCs: contenedor con fondo, borde suave, espaciado, tipografía y enlaces fáciles de leer. Sustituye .mi-toc por la clase real del bloque (por ejemplo .rank-math-toc o .wp-block-yoast-toc).

/ Estilos base para el TOC /
.mi-toc {
  background: #ffffff
  border: 1px solid rgba(0,0,0,0.08)
  border-radius: 8px
  padding: 16px
  font-family: system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, Arial
  font-size: 15px
  color: #222
}

/ Título del TOC (si el bloque genera un h3 o un elemento con clase) /
.mi-toc .toc-title,
.mi-toc h3 {
  margin: 0 0 10px 0
  font-weight: 600
  font-size: 16px
}

/ Lista del TOC /
.mi-toc ul {
  list-style: none
  margin: 0
  padding: 0
}

/ Items y enlaces /
.mi-toc li {
  margin: 6px 0
}
.mi-toc a {
  color: #0a66c2
  text-decoration: none
  display: inline-block
  padding: 6px 8px
  border-radius: 4px
}
.mi-toc a:hover,
.mi-toc a:focus {
  background: rgba(10,102,194,0.06)
  outline: none
}

Numeración y estilo de lista

Si el TOC genera una lista sin numeración y quieres números automáticos, usa CSS counter para numerar elementos sin alterar el HTML:

/ Numeración automática /
.mi-toc ul {
  counter-reset: toc-counter
}
.mi-toc li {
  counter-increment: toc-counter
  position: relative
  padding-left: 34px
}
.mi-toc li::before {
  content: counter(toc-counter) .
  position: absolute
  left: 0
  top: 50%
  transform: translateY(-50%)
  color: #6b7280
  font-weight: 600
}

Estilos para jerarquía (sublistas)

Para diferenciar niveles (H2, H3, H4) y mantener claridad visual, aplica indentación y tamaño de fuente decreciente:

.mi-toc li { font-size: 15px }
.mi-toc ul ul li { font-size: 14px padding-left: 28px color: #374151 }
.mi-toc ul ul ul li { font-size: 13px padding-left: 42px color: #6b7280 }

Resaltar el elemento activo (current item)

Muchos TOC añaden una clase al enlace activo (por ejemplo .current, .active o usan :target para el hash). Aquí tienes estilos para ambos casos:

/ Si el plugin añade la clase .current /
.mi-toc a.current,
.mi-toc a.active {
  background: #0a66c2
  color: #fff
  box-shadow: 0 1px 0 rgba(0,0,0,0.05) inset
}

/ Si quieres usar :target y los anchors tienen ids en el content /
.mi-toc a[href=#]:not([href=#]) { transition: background .15s }
.mi-toc a[href=#]:focus,
.mi-toc a[href=#]:hover { background: rgba(10,102,194,0.08) }

/ Resaltar el item cuyo destino coincide con :target /
:target {
  / estilos al ancla destino (no cambia el TOC por sí solo) /
}

/ Alternativa: detectar elemento anclado con JS para añadir .current al TOC.
   Si no deseas JS, confía en la clase que el plugin ya añade. /

Offset para anclas y desplazamiento suave

Cuando haces clic en un enlace del TOC, el encabezado puede quedar oculto detrás de tu cabecera fija. Usa scroll-margin-top en los encabezados para compensar. Además, habilita scroll suave:

/ Scroll suave (global) /
html {
  scroll-behavior: smooth
}

/ Compensar cabeceras fijas (ajusta 90px al alto de tu header) /
.entry-content h2,
.entry-content h3,
.entry-content h4 {
  scroll-margin-top: 90px
}

TOC fijo (sticky) en pantallas grandes

Si quieres que el TOC quede visible mientras el usuario hace scroll, usa position: sticky. Colócalo en una columna lateral o en un contenedor con altura suficiente:

/ TOC sticky en pantallas amplias /
@media (min-width: 992px) {
  .mi-toc {
    position: sticky
    top: 24px / separación respecto al top del viewport /
    max-height: calc(100vh - 48px)
    overflow: auto
    padding-right: 8px
  }
}

TOC colapsable (solo CSS sencillo)

Si prefieres un TOC colapsable sin JavaScript, puedes usar el elemento details/summary si tu TOC no lo genera por defecto. Si el plugin no ofrece esa estructura, considera envolver el bloque con un bloque HTML personalizado. Ejemplo de CSS para details:

/ Estilos para details/summary /
.mi-toc details {
  border-radius: 8px
  overflow: hidden
}
.mi-toc summary {
  cursor: pointer
  list-style: none
  padding: 12px
  display: block
  background: #f8fafc
  font-weight: 600
}
.mi-toc details[open] summary {
  background: #eef2ff
}
/ Transición de contenido /
.mi-toc details > ul {
  padding: 12px
}

Responsive: ocultar o transformar en acordeón en móviles

En móviles el TOC puede ocupar demasiado espacio puedes ocultarlo por defecto o convertirlo en un acordeón:

/ Ocultar TOC en móviles (mostrar botón o summary sería mejor) /
@media (max-width: 767px) {
  .mi-toc {
    display: none / o max-height: 0 overflow: hidden /
  }
}

/ Alternativa: mostrar como bloque compacto /
@media (max-width: 767px) {
  .mi-toc {
    padding: 8px
    font-size: 14px
  }
  .mi-toc li { margin: 4px 0 }
}

Accesibilidad y usabilidad

Asegura contraste suficiente entre texto y fondo (ratio recomendado 4.5:1 para texto normal).
Proporciona foco visible: usa :focus-visible para que usuarios de teclado vean dónde están.
Aumenta el área de clic para enlaces con padding y display: inline-block.
Si usas sticky y overflow: auto, asegúrate de que sea navegable por teclado (focus dentro del scrollable).

/ Enfoque accesible /
.mi-toc a:focus-visible {
  outline: 3px solid rgba(10,102,194,0.18)
  outline-offset: 2px
}

Ejemplos prácticos para Rank Math y Yoast

A continuación encontrarás dos bloques de CSS listos para usar. Sustituye la clase si tu plugin utiliza otra.

Ejemplo: TOC para Rank Math (clase sugerida .rank-math-toc)

/ Rank Math TOC - estilo moderno /
.rank-math-toc {
  background: linear-gradient(180deg,#fff,#fbfdff)
  border: 1px solid rgba(16,24,40,0.06)
  border-radius: 10px
  padding: 18px
}
.rank-math-toc .rank-math-toc-list {
  list-style: none
  margin: 0
  padding: 0
}
.rank-math-toc a {
  color: #0b5fff
  display: inline-block
  padding: 6px 10px
  border-radius: 6px
  text-decoration: none
}
.rank-math-toc a.current {
  background: #0b5fff
  color: #fff
}
/ Sticky en escritorio /
@media (min-width: 992px) {
  .rank-math-toc { position: sticky top: 24px max-height: calc(100vh - 48px) overflow: auto }
}

Ejemplo: TOC para Yoast (clase sugerida .wp-block-yoast-toc)

/ Yoast TOC - estilo compacto /
.wp-block-yoast-toc {
  background: #fffefb
  border-left: 4px solid #f59e0b
  padding: 14px
  border-radius: 6px
}
.wp-block-yoast-toc ul { margin: 0 padding-left: 12px }
.wp-block-yoast-toc li { margin: 6px 0 }
.wp-block-yoast-toc a { color: #b45309 text-decoration: none }
.wp-block-yoast-toc a:hover { text-decoration: underline }

Consejos finales y buenas prácticas

Usa clases personalizadas en el editor de bloques cuando sea posible así no dependes de nombres internos del plugin que puedan cambiar.
Inspecciona el HTML real con las herramientas del navegador para confirmar selectores y estructura (ul/li, a[href^=#], etc.).
Prueba en móvil y ajusta la visibilidad o la disposición del TOC para no afectar la legibilidad.
Simplifica los estilos si usas un tema con estilos muy propios evita conflictos con reglas globales del tema.
Guarda los estilos en el CSS del tema hijo o en el personalizador (Apariencia → Personalizar → CSS adicional) para que las actualizaciones no los borren.

Conclusión

Con unos pocos selectores y técnicas CSS puedes lograr un Table of Contents visualmente atractivo, usable y accesible tanto para Rank Math como para Yoast. Comienza con los estilos base, añade jerarquía y numeración si lo deseas, y compleméntalo con sticky, scroll-offset y cuidados de accesibilidad. Reemplaza .mi-toc por la clase real de tu bloque o añade una clase personalizada en el editor para tener control total.

SushiHost