Tabla de Contenidos: Formato y Reglas

En la librería de elementos , un resumen rápido y una tabla de contenidos indican a los lectores qué cubre una página, en qué les ayudará a decidir y cómo saltar a la sección que necesitan.

Resumen rápido. Usa este elemento de apertura emparejado en páginas largas o estructuralmente complejas. Redacta un resumen de 40 a 90 palabras que establezca el alcance y el resultado esperado, luego proporciona una lista de contenidos hecha con encabezados H2 estables y solo encabezados H3 útiles. En este sitio, el control de contenidos en vivo que aparece abajo permanece oculto hasta que el lector se ha desplazado más de 300 píxeles; entonces aparece como un menú desplegable fijo de escritorio debajo del encabezado del sitio.

Por qué este elemento es importante

Los lectores no comienzan todas las páginas largas en el mismo punto. Una persona necesita una definición, otra quiere pasos de implementación, y una tercera está verificando una única restricción antes de aprobar un trabajo. Un resumen breve responde «¿Estoy en el lugar correcto?» antes de que el lector invierta atención. La lista de contenidos responde «¿Dónde está la parte que necesito?» sin forzar una lectura lineal.

Las dos partes se especifican juntas porque resuelven problemas de orientación adyacentes pero diferentes. El resumen explica la promesa, los límites y el resultado útil de la página en oraciones. La lista de contenidos expone la ruta a través de esa promesa como destinos. Una lista de contenidos sin resumen puede mostrar que una página tiene secciones llamadas «Configuración» y «Accesibilidad», pero no puede explicar si la página es una introducción conceptual o una especificación de producción. Un resumen sin navegación puede establecer el alcance, pero aún así hacer que un lector busque a través de 3000 palabras.

Este elemento también mejora la extractabilidad automatizada, es decir, la capacidad del software de aislar un pasaje y retener su propósito fuera de la página completa. El resumen es un segundo resumen conciso y autocontenido después del título y la descripción. La tabla de contenidos fuente de Hugo es un esquema enlazado y legible por máquina de la cobertura y jerarquía de la página; el renderizador fijo actual convierte esos enlaces en opciones que conservan sus valores de fragmento URL, la parte #seccion de una URL. Los sistemas de búsqueda, herramientas de recuperación, extensiones de navegador y agentes de IA pueden usar el esquema del documento para identificar regiones probables de respuesta antes de procesar cada párrafo. Esto no garantiza una función de búsqueda o una cita de IA; reduce la ambigüedad sobre dónde comienzan los temas y cómo se relacionan.

El emparejamiento no debe crear repetición. Un resumen indica el alcance y el resultado. Un bloque de respuesta directa responde la pregunta principal. Las conclusiones clave indican conclusiones que vale la pena recordar. Cuando los tres dicen lo mismo en cajas diferentes, la apertura se convierte en un obstáculo en lugar de una ayuda.

Cuándo usarlo

La lista de contenidos se justifica cuando saltar es un comportamiento probable del lector. El recuento de palabras es un indicador útil, pero la estructura es el factor decisivo.

Usa solo el resumen cuando el título podría interpretarse de forma amplia, cuando la página excluye deliberadamente temas adyacentes, o cuando el lector necesita conocer el resultado esperado antes de continuar. Una página de política de 900 palabras puede necesitar un resumen de dos oraciones aunque no necesite navegación.

Usa solo la lista de contenidos cuando el título y la apertura ya hagan inconfundible el alcance. Este caso límite es común en páginas de referencia: la apertura puede contener una definición directa que cumple la función de orientación, mientras que un conjunto extenso de campos independientes aún necesita navegación.

No uses ninguna de las dos partes como decoración. Un TOC de seis elementos en un artículo de 700 palabras añade una decisión extra antes de la respuesta. Un resumen que dice «Esta guía explora todo lo que necesitas saber» no define alcance, resultado ni exclusiones. No uses el par para ocultar una estructura de encabezados débil: si los encabezados se superponen, usan gramática inconsistente, o dividen una idea en muchas secciones diminutas, arregla el documento antes de exponer su esquema.

Dónde colocarlo

La posición es parte del significado del elemento. El resumen debe aparecer después del hero o la respuesta directa de apertura y antes del primer H2. Puede ser un párrafo corto o una lista compacta, pero debe encontrarse antes de que el lector se comprometa con el cuerpo. La invocación del TOC va inmediatamente después del resumen para que la fuente editada mantenga juntos la orientación y la navegación, aunque el control fijo de este sitio se vuelva visible solo después de desplazarse 300 píxeles.

El par no puede interrumpir una definición, separar una afirmación de su evidencia, ni aparecer por primera vez en la mitad del documento. No lo coloques entre un encabezado y su párrafo de apertura: la relación entre el encabezado y la explicación debe permanecer directa. No coloques otro componente tipo resumen inmediatamente a su lado. Cuando se requiere una respuesta directa o un bloque de conclusiones clave, asigna trabajos distintos y usa este orden: respuesta directa, resumen breve de alcance, invocación del TOC, primera sección del cuerpo. Omite uno de los resúmenes si la redacción aún se superpone.

Usa el shortcode una vez por página. Sus IDs renderizados (tocDropdown, tocSelect, selectTrigger y controles relacionados) son fijos, por lo que una segunda instancia crea IDs de documento duplicados y scripts impredecibles.

Anatomía

El elemento tiene seis regiones significativas. Las primeras cinco son contenido o comportamiento; el indicador de progreso es estado. La leyenda se mantiene en la página para que siga siendo legible cuando la captura de pantalla se redimensiona o reemplaza.

1. Cuerpo del resumen: 40 a 90 palabras que indican el alcance, el resultado previsto y cualquier límite importante.
2. Título del contenedor fijo: el título de la página por defecto, o el atributo title cuando una etiqueta más corta es más clara.
3. Etiqueta de sección actual: comienza como «Seleccionar sección…» y cambia a medida que el IntersectionObserver del navegador, una API que detecta elementos que entran en una región definida del viewport, marca las secciones como activas.
4. Activador del menú desplegable: abre la lista generada de destinos de sección al hacer clic en la implementación actual.
5. Opciones de encabezados: enlaces derivados de la tabla de contenidos de página de Hugo, actualmente H2 y H3 debido a markup.toml.
6. Barra de progreso: muestra la proporción del documento desplazable total recorrido; no identifica la finalización de secciones.

Ejemplos de diseño

La galería cubre estados de comportamiento en lugar de temas decorativos. El contenido subyacente permanece igual para que los revisores puedan comparar tiempos, jerarquía, recorte e interacción.

No se crean variantes visuales alternativas a través de Markdown. title cambia la etiqueta y class añade clases de contenedor, pero ninguno crea un elemento semánticamente diferente. Los nuevos tratamientos de color, tarjeta, barra lateral o lista en línea requieren una decisión de componente en lugar de una clase arbitraria añadida en el contenido.

Parámetros

El resumen y el TOC comparten un único contrato editorial, pero solo el TOC fijo es renderizado por el shortcode actual. Los valores de configuración se incluyen porque cambian la salida aunque los autores no puedan establecerlos por invocación.

La dependencia es fácil de pasar por alto: una página sin encabezados H2 no renderiza silenciosamente ningún TOC fijo porque Hugo no produce un esquema utilizable y el parcial emite markup solo cuando tiene encabezados. Con la configuración actual, los H2 y sus descendientes H3 son elegibles; los H4 y encabezados más profundos quedan excluidos. El parcial normalmente analiza .TableOfContents de Hugo. Su fallback HTML escanea solo los elementos H2 renderizados, por lo que los autores no deben confiar en el comportamiento de fallback para preservar la navegación H3.

Sintaxis y ejemplos de código

La notación portátil mantiene el resumen como el cuerpo del elemento y los ajustes de navegación como atributos. Los enlaces de encabezados siguen siendo generados a partir del documento circundante en lugar de ser duplicados por el autor.

:::quick-overview-and-toc{title="En esta página" class=""}
Esta guía explica cuándo usar el elemento, cómo se comporta el control fijo de Hugo
y cómo preservar destinos de sección accesibles y estables después de la publicación.
:::

El mapeo actual de Hugo escribe el resumen como Markdown normal e invoca el shortcode incluido una vez. No hay cuerpo JSON.

Esta guía explica cuándo usar el elemento, cómo se comporta el control fijo de Hugo
y cómo preservar destinos de sección accesibles y estables después de la publicación.

{{< table-of-contents title="En esta página" class="" >}}

El mapeo del bloque de WordPress almacena el mismo cuerpo y atributos. Un sitio que no haya registrado el bloque puede usar la forma de shortcode equivalente; no debe escribir manualmente los enlaces de encabezados.

<!-- wp:amicited/quick-overview-and-toc {"title":"En esta página","className":""} -->
<p>Esta guía explica cuándo usar el elemento, cómo se comporta el control fijo
y cómo preservar destinos de sección accesibles y estables después de la publicación.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="En esta página" class=""]
Esta guía explica el alcance, el comportamiento y la política de anclas del elemento.
[/amicited_quick_overview_toc]

En los tres sistemas, la fuente de verdad es la jerarquía real de encabezados del documento. Una lista mantenida manualmente se desviará a medida que los encabezados cambien y puede apuntar a IDs que ya no están presentes.

Ejemplos

Ejemplo correcto

Resumen rápido. Esta guía muestra a los equipos de contenido cómo planificar, redactar, revisar y mantener una página de comparación. Cubre estándares de evidencia, criterios de comparación, afirmaciones sobre productos, tablas accesibles y verificaciones posteriores a la publicación. No cubre colocación paga ni términos de comisiones de afiliados.

En esta página: Definir la decisión · Seleccionar criterios de comparación · Recopilar evidencia · Redactar la página · Revisar afirmaciones · Medir y mantener

Esto funciona porque el resumen nombra la audiencia, el resultado, la cobertura y el límite en 48 palabras. Los seis destinos son tareas distintas que un lector podría retomar de forma independiente. Sus etiquetas usan frases verbales paralelas, por lo que tanto las personas como las máquinas pueden inferir un proceso. Ninguna de las entradas repite el título de la página ni expone una subsección trivial.

Ejemplo incorrecto

Resumen: Bienvenido a nuestra guía completa. En el mundo cambiante de hoy, hay mucho que saber, así que sigue leyendo para aprenderlo todo.

Contenidos: Introducción · Más información · Cosas importantes · Otras cosas · Conclusión

Esto falla por dos razones. El resumen gasta 22 palabras sin definir alcance, lector, resultado o exclusión. Las entradas etiquetan contenedores retóricos en lugar de temas, por lo que no ayudan al lector a predecir dónde vive una respuesta. Añadir más encabezados no lo solucionaría; el documento necesita primero límites de sección significativos.

Un segundo caso límite es una respuesta de 600 palabras con «Resumen», «Antecedentes», «Detalles», «Consejos» y «Conclusión» en su TOC. Incluso si cada ancla funciona, la lista añade más interfaz que valor de navegación. Mantén la apertura directa y elimina el TOC.

Marcado de esquema y accesibilidad

Aquí, marcado de esquema significa código estandarizado legible por máquina que identifica entidades y propiedades. Este elemento no tiene un tipo o propiedad dedicada en el vocabulario de Schema.org, y el shortcode de Hugo no emite JSON-LD, la notación basada en scripts comúnmente usada para publicar ese vocabulario. No marques el TOC como ItemList simplemente porque es una lista; eso sugeriría una lista de elementos temáticos en lugar de navegación. El resumen puede informar la description de una página solo cuando la redacción es adecuada de forma independiente, pero no se copia automáticamente en los datos estructurados.

El comportamiento HTML y ARIA importa más aquí. ARIA, el estándar de Aplicaciones de Internet Enriquecidas Accesibles, proporciona roles, nombres y estados cuando el HTML nativo no lo hace. Un punto de referencia (landmark) es una región de página nombrada a la que los usuarios de tecnología de asistencia pueden saltar. El foco es el objetivo actual de interacción del teclado.

Estos son hechos de implementación, no permiso para ignorar la accesibilidad. Los revisores de contenido pueden verificar la claridad de los encabezados, los IDs únicos y el orden lógico hoy. Los propietarios de componentes deben resolver el comportamiento del activador, punto de referencia, foco, URL y movimiento reducido antes de describir la variante fija como accesible por teclado.

Reglas de redacción

Redacta el resumen después de que la estructura de la página sea estable. Esto evita que una promesa temprana se desvíe de la cobertura final. Mantenlo entre 40 y 90 palabras. Prefiere dos o tres oraciones; usa de tres a cinco viñetas solo cuando la página contenga varios resultados genuinamente paralelos. Indica en qué ayuda la página al lector a entender, decidir o hacer. Nombra una exclusión cuando el título podría prometer razonablemente más de lo que la página entrega.

Usa H2 para las preguntas principales, etapas o áreas de decisión de la página. Incluye H3 en la navegación solo cuando sea un destino independiente útil bajo un H2 sustancial. En este sitio, la configuración incluye automáticamente cada H2 y H3, por lo que la política práctica es más estricta: no crees un encabezado a menos que merezca aparecer en la navegación. Apunta a 5–18 entradas totales. Si la lista generada excede 18, combina secciones superpuestas, elimina encabezados H3 innecesarios o divide la página. Nunca saltes directamente de H2 a H4 para ocultar un encabezado del TOC; los niveles de encabezado expresan jerarquía, no preferencia de estilo o navegación.

Usa texto de encabezado conciso y descriptivo. Un lector debe entender cada destino sin leer su párrafo padre. Prefiere formas paralelas dentro de una secuencia: «Elegir criterios», «Recopilar evidencia» y «Revisar afirmaciones» son más fáciles de escanear que una mezcla de sustantivos, preguntas y etiquetas vagas. No pongas citas, afirmaciones promocionales, emojis, insignias de estado u oraciones completas en un encabezado únicamente para influir en el TOC.

El resumen nunca debe contener una segunda lista de contenidos en miniatura, afirmaciones de rendimiento no respaldadas o instrucciones que no aparezcan en ninguna parte del cuerpo. El TOC nunca debe contener anclas escritas manualmente, destinos fuera de la página actual o enlaces a secciones vacías.

Política de estabilidad de anclas

Un ID de encabezado es la parte del fragmento de una URL, como #politica-de-estabilidad-de-anclas. Las URL de fragmento publicadas son interfaces públicas. Los marcadores, enlaces de campañas, documentación de soporte, resultados de búsqueda y respuestas generadas por IA pueden apuntar directamente a ellas. Cambiar el texto del encabezado puede alterar el ID generado por Hugo y romper cada ancla entrante incluso cuando la URL de la página permanece igual.

Después de la publicación, congela los IDs de todos los encabezados H2 y H3. Prefiere editar el párrafo debajo de un encabezado en lugar de renombrar el encabezado. Cuando sea necesario renombrar, preserva el ID anterior usando un mecanismo de ancla explícito compatible con el sistema de publicación, luego verifica tanto el fragmento entrante antiguo como la nueva selección del TOC. Nunca reutilices un ID antiguo para un tema diferente, nunca dupliques un ID en la página y nunca traduzcas un ID en una URL localizada existente sin un plan de migración. Registra los cambios intencionales de anclas en la nota de la versión o en el registro de cambios de contenido para que los propietarios de enlaces entrantes conocidos puedan actualizarlos.

Tipos de publicación que lo usan

El frontmatter postTypes lista los formatos para los cuales este elemento es parte del patrón de producción. Sigue siendo condicional: una instancia corta de un formato normalmente largo puede estar por debajo del umbral del TOC.

Las páginas de producto, categoría y caso de uso no se incluyen por defecto porque sus recorridos principales a menudo son manejados por la navegación a nivel de página y las llamadas a la acción. Añade este elemento solo mediante una decisión documentada de plantilla, no porque la página sea larga.

Lista de verificación de control de calidad

• Confirma que la página cumple el umbral: al menos 1800 palabras, siete secciones H2, o una necesidad documentada de navegación no lineal.
• Confirma que el resumen tiene de 40 a 90 palabras e indica el alcance, el resultado previsto y cualquier exclusión necesaria.
• Confirma que el resumen no repite la respuesta directa ni las conclusiones clave.
• Confirma que el shortcode aparece una vez, inmediatamente después del resumen y antes del primer H2.
• Confirma que cada H2 es un destino principal significativo y cada H3 es suficientemente útil para aparecer en la navegación.
• Confirma que la lista generada contiene de 5 a 18 entradas, usa un orden lógico y no contiene elementos H4 bajo la configuración actual.
• Confirma que config/_default/markup.toml aún usa startLevel = 2, endLevel = 3 y ordered = false, o actualiza esta especificación con el cambio de componente.
• Confirma que una página sin H2 elegibles no afirma contener un TOC; el shortcode no renderizará nada silenciosamente.
• Confirma que cada fragmento generado es único y llega al encabezado previsto.
• Prueba las URL de ancla entrantes publicadas antes de cambiar cualquier redacción de H2 o H3; preserva los IDs antiguos cuando los encabezados deban cambiar.
• En escritorio, verifica que el contenedor fijo esté oculto a 300 píxeles o menos y aparezca después de que la posición de desplazamiento supere los 300 píxeles.
• Verifica que el contenedor fijo esté debajo del encabezado real, que la barra de progreso avance y que la etiqueta activa siga los cambios de sección.
• Verifica que los viewports estrechos no muestren el control actual, y registra esto como comportamiento actual esperado en lugar de una captura de pantalla rota.
• Registra las limitaciones de accesibilidad actuales: sin punto de referencia de navegación, sin activador visible enfocable por teclado, sin transferencia de foco, sin actualización de fragmento y sin rama de movimiento reducido.
• Confirma que ninguna ruta de captura de pantalla se renderiza hasta que el activo correspondiente exista en disco.

Preguntas frecuentes (FAQ)

Las preguntas a continuación cubren las decisiones editoriales que con mayor frecuencia causan que este elemento se añada demasiado pronto, se haga demasiado profundo, o se rompa después de la publicación.