¿En qué se parecen y diferencian los bloques de detalles y acordeón de WordPress y para qué es mejor usar cada uno?

Si alguna vez has querido añadir secciones desplegables en tu WordPress, seguramente te has encontrado con dos opciones que parecen hacer lo mismo: el bloque de detalles y el bloque de acordeón que llegó con WordPress 6.9. Y es normal que te surjan dudas, porque a primera vista pueden parecer prácticamente idénticos.

Pero la realidad es que cada uno tiene su propósito y sus particularidades. Saber cuándo usar uno u otro puede marcar la diferencia entre tener una web bien organizada o terminar peleándote con el editor intentando conseguir el resultado que buscas.

En este artículo vamos a destripar tú y yo ambos bloques, comparándolos punto por punto para tener claro exactamente qué hace cada uno, cómo personalizarlos y, sobre todo, cuándo conviene usar uno u otro. Vamos al lío.

¿Qué son y para qué sirve cada uno de estos bloques?

Como ya he dicho que son diferentes, empecemos por los detalles (guiño guiño)

El bloque de detalles

El bloque de detalles lleva con nosotros desde WordPress 6.3 (julio de 2023). Es la forma que tiene WordPress de implementar el elemento HTML nativo <details>, que básicamente es una sección que puedes plegar y desplegar haciendo clic.

Imagina que tienes un spoiler de una película, una nota al pie extensa que no quieres que moleste en medio del texto, o simplemente información adicional que solo algunos lectores querrán ver. Para eso está el bloque de detalles: una única sección desplegable, ya.

Si quieres saber más sobre este bloque, ya hablé de él en detalle en este artículo sobre el bloque de detalles.

El bloque de acordeón

El bloque de acordeón llegó con WordPress 6.9 (diciembre de 2025) y viene a resolver algo que llevaba años pidiéndose: una forma nativa de crear esas típicas listas de preguntas frecuentes donde haces clic en una pregunta y se despliega la respuesta.

A diferencia del bloque de detalles, el acordeón no es un bloque suelto, sino una estructura completa pensada para agrupar múltiples secciones relacionadas. Es como tener varios bloques de detalles, pero organizados bajo un mismo contenedor y con opciones específicas para trabajar con ellos como grupo.

La diferencia clave

Aquí está el quid de la cuestión que debes tener claro desde ya:

• Bloque de detalles → Una única sección desplegable independiente
• Bloque de acordeón → Múltiples secciones agrupadas bajo un mismo contenedor

Es como la diferencia entre tener una nota al pie en un libro (detalles) y tener un índice completo de preguntas frecuentes al final (acordeón).

¿Cómo están construidos internamente?

Bloque de detalles: HTML nativo

El bloque de detalles es elegante en su sencillez. Usa dos elementos HTML5 estándar:

• <details> → El contenedor principal
• <summary> → El texto que siempre se ve (tu título, llamado resumen)

El contenido que añadas dentro del bloque quedará oculto hasta que alguien haga clic en el resumen. No hay JavaScript complejo, no hay dependencias raras. Los navegadores saben perfectamente qué hacer con estos elementos porque forman parte del estándar HTML5.

<details class="wp-block-details">
  <summary>Haz clic aquí para ver más</summary>
  <p>Bloque oculto inicialmente</p>
</details>

Cuando haces clic, el navegador simplemente añade el atributo open al elemento <details> y el contenido se hace visible. Así de simple.

Bloque de acordeón: jerarquía de bloques

El acordeón es mucho más elaborado. En realidad no es un bloque, son cuatro bloques trabajando juntos en una estructura anidada:

1. Acordeón → El contenedor principal que agrupa todo
2. Elemento de acordeón → Cada una de las secciones individuales (cada pregunta-respuesta)
3. Encabezado del acordeón → El encabezado de cada sección (incluye el icono y el título)
4. Panel del acordeón → El contenido desplegable de cada sección
5. Bloques del panel del acordeón → El contenido desplegable dentro de cada panel

Cuando añades un bloque de acordeón, automáticamente se crea un elemento de acordeón con su encabezado y panel. Luego puedes ir añadiendo más elementos según necesites.

<div class="wp-block-accordion">
  <div class="wp-block-accordion-item">
    <h3 class="wp-block-accordion-heading">
      <button class="wp-block-accordion-heading__toggle">
        <span class="wp-block-accordion-heading__toggle-icon"></span>
        <span class="wp-block-accordion-heading__toggle-title">¿Primera pregunta?</span>
      </button>
    </h3>
    <div class="wp-block-accordion-panel">
      <p>Respuesta a la primera pregunta</p>
    </div>
  </div>
  <!-- Más elementos de acordeón... -->
</div>

Como ves, la estructura es bastante más compleja. Usa divs, botones y clases CSS en lugar de elementos semánticos nativos. Esto le da más flexibilidad para personalizar, pero también significa que depende más de CSS y JavaScript para funcionar correctamente.

¿Cuál es mejor estructuralmente?

¿Cómo se añade y usa cada bloque?

Añadir el bloque de detalles

Buscar el bloque de detalles es sencillo, simplemente escribe «detalles». O si eres de atajos de teclado, escribe /detalles en una línea nueva y pulsa INTRO.

Una vez añadido, verás dos campos:

1. Escribe un resumen → Aquí va tu título o texto que siempre estará visible
2. Escribe / para añadir un bloque oculto → Aquí añades cualquier contenido que quieras ocultar

Puedes añadir cualquier tipo de bloque dentro: párrafos, imágenes, listas, otros bloques… lo que necesites.

Añadir el bloque de acordeón

Para el acordeón, simplemente busca «acordeón» o «plegar» en el buscador de bloques, o teclea /acordeon y pulsa INTRO.

Al añadirlo, automáticamente se crea con:

• Un primer elemento de acordeón ya listo
• Su encabezado (donde escribes la pregunta o título)
• Su panel (donde añades la respuesta o contenido)

Para añadir más preguntas, tienes varias opciones:

• Usar el botón + que aparece al final del último elemento
• Duplicar un elemento existente
• Añadir manualmente un nuevo bloque de elemento de acordeón

Diferencias en el uso diario

• Con el bloque de detalles, si quieres crear una lista tipo FAQ, tendrías que añadir múltiples bloques de detalles uno detrás de otro. Funcionará, pero cada uno es independiente y no hay forma nativa de gestionarlos como grupo.
• Con el de acordeón, todos los elementos están relacionados y los gestionas desde un único bloque contenedor. Esto es mucho más cómodo cuando tienes 5, 10 o 20 preguntas frecuentes.

¿Que se puede personalizar SIN código?

Si ya tienes claro para qué vas a usar cada bloque nos ponemos con lo siguiente: darles un poco de colorinchi, que ya habrás visto por las capturas que por defecto no son la alegría de la huerta precisamente.

Bloque de detalles: ajustes básicos pero suficientes

Cuando seleccionas el bloque de detalles, en la barra lateral derecha (en la configuración del bloque) encuentras estas opciones:

En la pestaña de ajustes:

• Abierto por defecto → Un interruptor para que el bloque aparezca desplegado al cargar la página
• Opciones avanzadas → Anclaje HTML, atributo de nombre y clases CSS personalizadas
• Bloques permitidos → Decide qué bloques se pueden añadir ocultos bajo el desplegable

En la pestaña de estilos:

• Color → texto y fondo
• Tipografía → familia, tamaño, aspecto (negrita, cursiva), altura de línea, espaciado de letras, decoración, mayúsculas/minúsculas
• Dimensiones → relleno (espaciado interno) y margen (espaciado externo)
• Borde → color, ancho, radio (esquinas redondeadas)

Lo que NO puedes cambiar sin código:

• El icono por defecto (▶)
• La posición del icono
• Animaciones de apertura/cierre

Bloque de acordeón: minimalismo con potencial

El acordeón viene con una filosofía diferente: muy pocos estilos por defecto. Esto puede parecer una desventaja, pero en realidad es una ventaja enorme para los que queremos personalizar.

Las opciones básicas que encuentras son similares a las del bloque de detalles (colores, tipografía, espaciados), pero aplicadas a cada nivel de la estructura:

• A nivel de acordeón (el contenedor) → Afecta a todo el grupo
• A nivel de elemento de acordeón → Afecta a cada sección individual
• A nivel de encabezado de acordeón → Solo al encabezado
• A nivel de panel de acordeón → Solo al contenido desplegable

Pero aquí viene lo interesante, y es que el acordeón está diseñado para trabajar con variaciones de estilo JSON (introducidas en WordPress 6.6). Esto significa que los creadores de temas pueden registrar estilos completos que luego aparecen como opciones en el editor.

Resumen de personalizaciones sin código

¿Qué se puede personalizar CON código?

Aquí es donde entramos en terreno interesante. Los iconos por defecto de ambos bloques son… digamos que poco emocionantes. Pero con un poco de CSS puedes transformarlos completamente.

Cambiar el icono del bloque de detalles

El icono por defecto del bloque de detalles es ese triángulo que apunta a la derecha (▶). Para cambiarlo, necesitas modificar el pseudo-elemento ::marker.

Opción 1: Cambiar solo el símbolo

/* Cambiar icono de bloque detalles a símbolos + y - */
.wp-block-details summary::marker {
    content: "+ ";
}

.wp-block-details[open] summary::marker {
    content: "- ";
}

Opción 2: Mover el icono a la derecha

Si prefieres que el icono aparezca al final en lugar de al principio (algo muy habitual en acordeones), necesitas este código que, de paso, también aprovechamos y cambiamos los iconos a los del ejemplo anterior:

/* Ocultar el marcador por defecto del bloque detalles */
.wp-block-details summary::marker {
content: none;
}

/* Añadir icono a la derecha del bloque detalles */
.wp-block-details summary::after {
content: " +";
float: right;
text-align: right;
}
.wp-block-details[open] summary::after {
content: " -";
}

Opción 3: Usar como iconos Dashicons de WordPress

WordPress incluye Dashicons por defecto, así que no necesitas cargar fuentes externas y quedan mejor que los simples símbolos de texto, y sino aquí un ejemplo buscando el mismo criterio estético:

/* Usar Dashicons incluidos en WordPress */
.wp-block-details summary::marker {
    content: none;
}

.wp-block-details summary::before {
    font-family: dashicons;
    content: "\f132"; /* Icono plus */
    margin-right: 0.5em;
    font-size: 1.2em;
    vertical-align: middle;
}

.wp-block-details[open] summary::before {
    content: "\f460"; /* Icono minus */
}

Cambiar los colores para imitar una caja informativa de WordPress con el bloque de detalles 

Como igual te aburre el estilazo tan minimalista de estos bloques, un poco de color te anima el día. Se me ocurre darle el look de la típica caja informativa de WordPress:

/* Estilo info box para el bloque de detalles */
.wp-block-details {
border: 1px solid #00a0d2;
border-radius: 4px;
overflow: hidden;
}

/* El resumen/título */
.wp-block-details summary {
background-color: #0073aa;
color: #ffffff;
padding: 12px 16px;
cursor: pointer;
font-weight: 600;
}

.wp-block-details summary:hover {
background-color: #005a87;
}

/* Fondo azul claro para todo el bloque cuando está abierto */
.wp-block-details[open] {
background-color: #e5f5fa;
}

/* Mantener el fondo del summary como está */
.wp-block-details[open] summary {
background-color: #0073aa;
border-bottom: 1px solid #00a0d2;
}

/* Padding para el contenido */
.wp-block-details[open] {
padding-bottom: 16px;
}

.wp-block-details[open] > *:not(summary) {
margin: 0 16px;
margin-top: 16px;
}

/* Cambiar el icono por defecto */
.wp-block-details summary::marker {
content: "▶ ";
color: #ffffff;
}

.wp-block-details[open] summary::marker {
content: "▼ ";
}

No queda mal ¿no?

Cambiar el icono del bloque de acordeón

El acordeón tiene su icono dentro de un <span> específico, lo que nos da más control:

Opción 1: Cambiar a símbolos simples

/* Ocultar el icono SVG por defecto */
.wp-block-accordion-heading__toggle-icon {
    display: none;
}

/* Añadir símbolo con ::before en el título */
.wp-block-accordion-heading__toggle-title::before {
    content: "+ ";
    margin-right: 0.5em;
}

/* Cambiar cuando está abierto */
.wp-block-accordion-item[open] .wp-block-accordion-heading__toggle-title::before {
    content: "- ";
}

Opción 2: Rotar el icono existente

En lugar de cambiar el icono, puedes rotarlo cuando se abre:

/* Transición suave icono bloque acordeon */
.wp-block-accordion-heading__toggle-icon {
    transition: transform 0.3s ease;
}

/* Rotar 90 grados cuando está abierto */
.wp-block-accordion-item[open] .wp-block-accordion-heading__toggle-icon {
    transform: rotate(90deg);
}

Opción 3: Iconos con Dashicons de WordPress

/* Ocultar icono por defecto de bloque acordeon */
.wp-block-accordion-heading__toggle-icon {
    display: none;
}

/* Icono de bloque acordeon con Dashicons */
.wp-block-accordion-heading__toggle::before {
    font-family: dashicons;
    content: "\f347"; /* arrow-down-alt2 */
    margin-right: 0.75em;
    font-size: 1.2em;
    transition: transform 0.3s ease;
}

.wp-block-accordion-item[open] .wp-block-accordion-heading__toggle::before {
    transform: rotate(180deg);
}

Cambiar los colores para imitar una caja informativa de WordPress con el bloque de acordeón

El bloque de acordeón no iba a ser menos, también le damos un poquito de luz y color:

/* Bloque acordeon estilo info box WP - Contenedor del acordeón */
.wp-block-accordion {
border: 1px solid #00a0d2;
border-radius: 4px;
overflow: hidden;
}

/* Bloque acordeon estilo info box WP - Cada item individual */
.wp-block-accordion-item {
border-bottom: 1px solid #00a0d2;
}

.wp-block-accordion-item:last-child {
border-bottom: none;
}

/* Bloque acordeon estilo info box WP - El encabezado/pregunta */
.wp-block-accordion-heading {
margin: 0;
background-color: #0073aa;
}

.wp-block-accordion .wp-block-accordion-heading__toggle {
background-color: #0073aa !important;
color: #ffffff !important;
padding: 12px 16px;
width: 100%;
text-align: left;
border: none;
font-weight: 600;
cursor: pointer;
margin: 0;
}

.wp-block-accordion .wp-block-accordion-heading__toggle:hover {
background-color: #005a87 !important;
}

/* Bloque acordeon estilo info box WP - Panel de contenido con azul claro */
.wp-block-accordion-panel {
background-color: #e5f5fa;
padding: 16px;
margin: 0;
}

/* Bloque acordeon estilo info box WP - Ocultar el icono por defecto y añadir uno personalizado */
.wp-block-accordion-heading__toggle-icon {
display: none;
}

.wp-block-accordion-heading__toggle::before {
content: "▶ ";
margin-right: 8px;
color: #ffffff;
}

.wp-block-accordion-item[open] .wp-block-accordion-heading__toggle::before {
content: "▼ ";
}

/* Bloque acordeon estilo info box WP - Asegurar que el título dentro también sea blanco */
.wp-block-accordion-heading__toggle-title {
color: #ffffff !important;
}

Monísimo ¿verdad?

¿Dónde añado los códigos CSS?

Tienes varias opciones para añadir tu CSS personalizado:

1. Personalizador de WordPress → Apariencia > Personalizar > CSS adicional
2. En el editor de temas → Si usas un tema de bloques, en el archivo style.css
3. Plugin MU → Si quieres que sea parte permanente de tu sitio

¿HTML generado y semántica?

¿Cómo de limpio es el código que genera cada uno de estos bloques?, pues hay diferencias…

Bloque de detalles: menos es más

Una de las mayores ventajas del bloque de detalles es que usa elementos HTML semánticos nativos. Esto significa que el código es más limpio, los navegadores lo entienden perfectamente y los lectores de pantalla saben exactamente qué es.

El código generado es súper simple:

<details class="wp-block-details">
  <summary>¿Qué es WordPress?</summary>
  <p>WordPress es un sistema de gestión de contenidos...</p>
</details>

Los elementos <details> y <summary> están en el estándar HTML5 desde hace años y todos los navegadores modernos los soportan sin necesidad de JavaScript adicional.

Bloque de acordeón: funcional pero menos semántico

El acordeón genera una estructura basada en divs, botones y clases CSS:

<div class="wp-block-accordion">
  <div class="wp-block-accordion-item">
    <h3 class="wp-block-accordion-heading">
      <button class="wp-block-accordion-heading__toggle" 
              aria-expanded="false"
              aria-controls="panel-1">
        <span class="wp-block-accordion-heading__toggle-icon" 
              aria-hidden="true"></span>
        <span class="wp-block-accordion-heading__toggle-title">
          ¿Qué es WordPress?
        </span>
      </button>
    </h3>
    <div class="wp-block-accordion-panel" 
         id="panel-1" 
         role="region">
      <p>WordPress es un sistema de gestión de contenidos...</p>
    </div>
  </div>
</div>

Fíjate que usa <h3> por defecto para los encabezados. Esto ha generado algo de debate porque puede afectar la jerarquía semántica de tu página si no lo controlas bien.

Por otro lado, como te cometo abajo, incluye atributos ARIA (aria-expanded, aria-controls, etc.) para mejorar la accesibilidad, lo cual está muy bien.

No obstante, si prefieres controlar al 100% la jerarquía de tus contenidos y el <h3> no te encaja, con esta función puedes ponerlo según tu necesidad:

/**
* Cambiar el nivel encabezado por defecto de los bloques de acordeón
* Por defecto usan h3, y esto lo cambia a lo que tú quieras
* @Author: Fernando Tellado (ayudawp.com)
*/
add_filter( 'render_block_core/accordion', 'ayudawp_change_accordion_heading_level', 10, 2 );

function ayudawp_change_accordion_heading_level( $block_content, $block ) {
// Define aquí tu tag preferida (h2, h4, h5, h6, span, etc.)
$new_heading_level = 'h5';

// Nivel de encabezado por defecto de los bloques de acordeón
$default_heading_level = 'h3';

// Usa WP_HTML_Tag_Processor para modificar el HTML entregado
$processor = new WP_HTML_Tag_Processor( $block_content );

// Encuentra todos los elementos acordeón y los cambia
while ( $processor->next_tag( [ 'class_name' => 'wp-block-accordion-heading' ] ) ) {
$processor->set_bookmark( 'heading-start' );

// Obtenemos la tag definida arriba
if ( $processor->get_tag() === strtoupper( $default_heading_level ) ) {
// Almacena los atributos y el contenido
$html = $processor->get_updated_html();

// Reemplazamos la tag del encabezado
$html = str_replace( 
'<' . $default_heading_level . ' class="wp-block-accordion-heading">', 
'<' . $new_heading_level . ' class="wp-block-accordion-heading">', 
$html 
);
$html = str_replace( 
'</' . $default_heading_level . '>', 
'</' . $new_heading_level . '>', 
$html 
);

return $html;
}
}

return $block_content;
}

Y con eso ya lo pones a tu gusto. Simplemente cambia el valor de $new_heading_level a lo que necesites.

Si por algún motivo lo anterior no te funciona bien (cosas que pasan) puedes probar con este código, más robusto en realidad, que usa REGEX:

/**
* Cambiar el nivel encabezado por defecto de los bloques de acordeón (usando REGEX)
* Por defecto usan h3, y esto lo cambia a lo que tú quieras
* @Author: Fernando Tellado (ayudawp.com)
*/
add_filter( 'render_block_core/accordion', 'ayudawp_change_accordion_heading_level_regex', 10, 2 );

function ayudawp_change_accordion_heading_level_regex( $block_content, $block ) {
// Define como $new_level tu tag preferida
$new_level = 'h5';
$old_level = 'h3';

// Reemplazo de tagas de encabezado de apertura y cierre de la clase accordion-heading
$block_content = preg_replace(
'/<' . $old_level . '(\s+class="[^"]*wp-block-accordion-heading[^"]*")/',
'<' . $new_level . '$1',
$block_content
);

$block_content = preg_replace(
'/<\/' . $old_level . '>(?=\s*<\/div><!-- \.wp-block-accordion-item -->)/',
'</' . $new_level . '>',
$block_content
);

return $block_content;
}

De hecho mi consejo es que pruebes directamente con este código primero, es raro que falle.

¿Cuál es mejor semánticamente?

• Para una única sección desplegable, el bloque de detalles gana por goleada. Es HTML puro, semántico y estándar.
• Para múltiples secciones agrupadas tipo FAQ, el acordeón es más apropiado porque está diseñado específicamente para ese caso de uso, aunque sacrifique algo de semántica HTML pura a cambio de flexibilidad.

Accesibilidad: ¿funcionan bien con lectores de pantalla?

Como cada vez es más relevante la accesibilidad, es un factor siempre a tener en cuenta.

Bloque de detalles: accesibilidad nativa

Al usar elementos HTML nativos, el bloque de detalles hereda toda la accesibilidad que los navegadores implementan para <details> y <summary>:

• Los lectores de pantalla anuncian automáticamente que es una región expandible
• La navegación por teclado funciona de forma estándar (tabulador para mover el foco, INTRO o espacio para expandir/contraer)
• El estado (abierto/cerrado) se comunica automáticamente

No necesitas hacer nada especial. Funciona directamente.

Bloque de acordeón: accesibilidad implementada

El acordeón tiene que implementar manualmente la accesibilidad usando atributos ARIA:

• aria-expanded → Indica si el panel está abierto o cerrado
• aria-controls → Conecta el botón con el panel que controla
• role="region" → Define el panel como una región
• aria-hidden → Oculta el icono decorativo de los lectores de pantalla

Según los comentarios en el desarrollo, todavía hay algunos ajustes pendientes en la accesibilidad del acordeón, pero en general está bastante bien implementado.

Comparativa de accesibilidad

Rendimiento y peso en la página

Aunque seguro que ya te lo estás imaginando, resumimos el asunto de performance.

Bloque de detalles: no se puede dar más con menos

El bloque de detalles es extremadamente ligero porque:

• No carga JavaScript adicional (usa la funcionalidad nativa del navegador)
• CSS mínimo (solo algunas clases básicas)
• HTML simple y limpio

El impacto en el rendimiento es prácticamente cero. Es uno de los bloques más ligeros de WordPress.

Bloque de acordeón: también ligero pero no tanto

El acordeón necesita un poco más:

• JavaScript para manejar el estado de apertura/cierre
• CSS adicional para los estilos y animaciones
• Estructura HTML más compleja

Aun así, está muy optimizado. WordPress solo carga los recursos del acordeón cuando realmente lo usas en una página (carga bajo demanda, algo disponible hacia varias versiones).

Impacto real en el rendimiento

En la práctica, la diferencia de rendimiento entre usar uno u otro es muy pequeña para el usuario final. Ambos son soluciones ligeras comparadas con plugins de terceros que suelen cargar librerías pesadas como jQuery o frameworks completos.

Si tienes una web donde cada KB cuenta, el bloque de detalles tiene una ligera ventaja, pero para la mayoría de casos, esta diferencia es prácticamente irrelevante.

Schema y SEO: incomprensible decepción

Aquí viene una de las sorpresas (y decepciones) más gordas: ninguno de los dos bloques incluye marcado Schema por defecto.

Esto es especialmente frustrante con el acordeón, que parece diseñado específicamente para FAQs. Muchos esperábamos que WordPress 6.9 trajera Schema.org integrado, pero no ha sido así.

¿Por qué es importante el schema para FAQs?

El marcado de Schema (o datos estructurados) es código que ayuda a los buscadores a entender mejor tu contenido. Cuando añades Schema de tipo FAQPage a tus preguntas frecuentes, puedes conseguir que Google las muestre directamente en los resultados de búsqueda como «rich snippets».

Esto significa más visibilidad, mejor posicionamiento y, potencialmente, más clics hacia tu web.

¿Se puede añadir Schema al bloque de detalles?

Para el bloque de detalles tendrías que implementar código personalizado adaptado a la estructura de <details> y <summary>. El código sería similar al del acordeón, pero trabajando con estos elementos HTML nativos.

Francamente, si tu objetivo principal es crear FAQs con Schema, el acordeón es la mejor opción porque ya tiene soporte comunitario y documentación oficial para hacerlo. El bloque de detalles está más pensado para contenido individual que no necesariamente es una FAQ, así que mi consejo es que no pierdas el tiempo con una implementación para el bloque de detalles.

¿Se puede añadir Schema al bloque de acordeón?

El equipo de desarrollo de WordPress publicó un snippet de código oficial para añadir Schema al Acordeón. El código usa la clase WP_HTML_Tag_Processor para añadir los atributos de Schema automáticamente, así que sí, se puede.

Paso 1: Añade una clase CSS personalizada

En tu bloque de acordeón, ve a la configuración avanzada > Clases CSS adicionales y añade: is-faqs

Paso 2: Añade este código a tu tema o plugin

Puedes añadirlo en el archivo functions.php de tu tema hijo, o mejor aún, crear un mu-plugin para que sea independiente del tema:

/**
 * Añadir Schema FAQ a bloques acordeón con la clase 'is-faqs'
 */
add_filter( 'render_block_core/accordion', 'ayudawp_render_accordion_faqs' );

function ayudawp_render_accordion_faqs( $content ) {
    $processor = new WP_HTML_Tag_Processor( $content );
    
    // Cancelar antes si no hay ningún bloque acordeón con la clase .is-faqs
    if ( ! $processor->next_tag( [ 'class_name' => 'wp-block-accordion' ] ) || 
         ! $processor->has_class( 'is-faqs' ) ) {
        return $processor->get_updated_html();
    }
    
    // Añadir atributos de Schema FAQPage al contenedor
    $processor->set_attribute( 'itemscope', true );
    $processor->set_attribute( 'itemtype', 'https://schema.org/FAQPage' );
    
    // Loop por los elementos de acordeón para añadir el Schema Question
    while ( $processor->next_tag( [ 'class_name' => 'wp-block-accordion-item' ] ) ) {
        $processor->set_attribute( 'itemscope', true );
        $processor->set_attribute( 'itemprop', 'mainEntity' );
        $processor->set_attribute( 'itemtype', 'https://schema.org/Question' );
        
        // Añadir propiedad de nombre al encabezado
        if ( $processor->next_tag( [ 'class_name' => 'wp-block-accordion-heading__toggle-title' ] ) ) {
            $processor->set_attribute( 'itemprop', 'name' );
        }
        
        // Añadir Schema de Answer al panel
        if ( $processor->next_tag( [ 'class_name' => 'wp-block-accordion-panel' ] ) ) {
            $processor->set_attribute( 'itemscope', true );
            $processor->set_attribute( 'itemprop', 'acceptedAnswer' );
            $processor->set_attribute( 'itemtype', 'https://schema.org/Answer' );
            
            // Encontrar el primer párrafo o div dentro y marcarlo como texto de respuesta
            if ( $processor->next_tag( [ 'tag_name' => 'p' ] ) || 
                 $processor->next_tag( [ 'tag_name' => 'div' ] ) ) {
                $processor->set_attribute( 'itemprop', 'text' );
            }
        }
    }
    
    return $processor->get_updated_html();
}

Paso 3: Valida tu Schema

Usa la herramienta de validación de schema.org o el test de resultados enriquecidos de Google para comprobar que todo funciona correctamente.

Alternativa: usar un plugin

Si no te apetece tocar código, existe un plugin específico que añade esta funcionalidad automáticamente al acordeón: Accordion FAQ Schema Toggle.

Solo tienes que descargarlo, instalarlo y activarlo. Añade un selector en los ajustes de cada acordeón para activar/desactivar el Schema. Lo bueno de este plugin es que puedes decidirlo bloque a bloque, y lo malo … eso mismo, que tienes que hacerlo bloque a bloque.

¿Cuál es mejor para SEO?

Tabla comparativa – Repaso de todo lo visto

¿Cuándo usar cada bloque?

Usa el bloque de detalles para:

• Ocultar spoilers → Reseñas de películas, series o libros donde no quieres revelar el final
• Contenido adicional opcional → Información técnica que solo algunos lectores querrán ver
• Notas al pie extensas → Referencias o explicaciones largas que distraerían en medio del texto
• Sección «Leer más» → Cuando tienes un párrafo introductorio y quieres ocultar el resto inicialmente
• Información de eventos → Detalles como ubicación, horarios, requisitos que pueden ocultarse
• Descargos de responsabilidad legales → Avisos legales o términos que deben estar pero no son el foco
• Prioridad en la semántica HTML → Cuando quieres el código más limpio y estándar posible
• Máxima ligereza → Cada byte cuenta y no quieres ni una línea de JavaScript

Usa el bloque de acordeón para:

• Preguntas frecuentes (FAQs) → Para lo que está pensado expresamente el acordeón (a pesar de lo del Schema)
• Listas de características → Especificaciones técnicas de productos organizadas por categorías
• Guías paso a paso → Tutoriales donde cada paso se despliega individualmente
• Menús de servicios → Lista de servicios con descripción detallada de cada uno
• Información de productos → Descripción, especificaciones, envío, garantía en secciones separadas
• Políticas y términos → Política de privacidad, términos de uso, etc. organizados por secciones
• Contenido educativo → Temarios, lecciones o módulos que se despliegan
• Comparativas → Comparar opciones donde cada una tiene su sección desplegable
• Necesitas schema de FAQs → Para aparecer en los rich snippets de Google
• Múltiples secciones relacionadas → Cualquier contenido que agrupe varias partes bajo un mismo tema

Casos donde podrías usar cualquiera de los dos

Hay situaciones donde ambos funcionarían, pero uno podría ser más conveniente:

• Cuando quieres poner 2 o 3 preguntas en un artículo → Podrías usar el de detalles (son pocas), pero el acordeón queda más organizado
• Sección «Más información» → Detalles es más semántico, pero el acordeón te da más control visual
• Listado de instrucciones → Detalles funciona, pero si son muchas, el acordeón escala mejor

¿Cómo usar cada bloque?

Con el bloque de detalles

• Sé descriptivo en el resumen → El texto que siempre se ve debe explicar claramente qué hay dentro
• No anides detalles dentro de detalles → Técnicamente puedes, pero es confuso para los usuarios
• Úsalo con moderación → Si tienes más de 5 o 6 en una misma página casi seguro que deberías usar un acordeón
• Aprovecha la opción «Abierto por defecto» → Útil para destacar información importante inicialmente

Con el bloque de acordeón

• Mantén las preguntas concisas → Los títulos largos funcionan mal visualmente
• Agrupa por temas → Si tienes muchas FAQs, considera usar varios acordeones agrupados por categoría
• Añade la clase is-faqs si quieres Schema → Recuerda activarla en las clases CSS y añadir el código que vimos antes
• Cuida la jerarquía de encabezados → El H3 por defecto puede no encajar en tu estructura. Te recomiendo cambiarlo con los códigos de antes
• Prueba diferentes estilos → El minimalismo por defecto está pensado para que lo personalices

Con ambos bloques

• Piensa en móvil → Las secciones desplegables son especialmente útiles en pantallas pequeñas
• No ocultes contenido crítico → Google puede penalizar contenido importante que está oculto por defecto
• Prueba la accesibilidad → Navega con el teclado (TAB + INTRO) para verificar que funciona bien
• Personaliza con CSS → Los estilos por defecto son básicos; no tengas miedo de añadir tu toque
• Valida tu Schema → Si añades marcado de FAQs, compruébalo siempre con las herramientas de Google

Dos bloques, dos propósitos

Después de este repaso exhaustivo, queda claro que el bloque de detalles y el bloque de acordeón no son competidores, sino complementarios. Cada uno tiene su sitio y su propósito.

• El bloque de detalles es perfecto cuando necesitas ocultar contenido de forma puntual. Es simple, ligero, semántico y funciona perfectamente para casos individuales. Si solo necesitas uno o dos desplegables en un artículo, es tu elección.
• El bloque de acordeón llega para cubrir el hueco que faltaba en WordPress: una forma nativa de crear listas de preguntas frecuentes y contenido organizado en múltiples secciones. Es más complejo, pero también más potente y versátil cuando necesitas agrupar información relacionada. La pena es la incongruencia de incorporarlo pero que no use el Schema, pero bueno, eso. ya lo hemos arreglado aquí.

La llegada del acordeón en WordPress 6.9 no hace obsoleto al bloque de detalles, simplemente nos da más opciones para elegir la herramienta adecuada para cada trabajo.

Mi consejo final es que empieces usando cada uno para lo que están diseñados. Con el tiempo, y según tus necesidades específicas, irás descubriendo casos de uso creativos y personalizaciones que los harán todavía más útiles en tu web.

Ahora, también te digo que no son los bloques que más vas a usar en tu vida, por su enfoque tan concreto, pero igualmente es cierto que cuando necesitas algo de ese estilo no hay nada igual, y es el tipo de bloque que siempre debes tener en la caja de herramientas a la hora de diseñar páginas, y en según qué tipo de contenidos, incluso más.

¿Y tú, ya has probado el nuevo bloque de acordeón?, ¿o solo estás usando el bloque de detalles o ninguno? Me encantaría conocer tu experiencia en los comentarios.

¿Te gustó este artículo? ¡Ni te imaginas lo que te estás perdiendo en YouTube!