¿La plantilla de bloques no se aplica? Empieza por la base de datos

Tu archivo de plantilla casi con toda seguridad se está ignorando porque una copia en la base de datos está ganando. En cuanto abres una plantilla en el editor del sitio y pulsas Guardar, WordPress escribe un registro de entrada wp_template, y a partir de ahí sirve ese registro en lugar del archivo .html de la carpeta de tu tema, así que cada cambio que hagas después al archivo es invisible en la parte pública. Borrar ese registro es la solución, y es lo primero que hay que comprobar antes de tocar la jerarquía, el nombre del archivo o el caché.

Confirma que la copia en la base de datos existe

Ve a Apariencia → Editor → Plantillas. Toda plantilla que WordPress esté sirviendo desde la base de datos aparece marcada en la lista: según tu versión de WordPress la etiqueta dice “Personalizada” o la plantilla aparece bajo un filtro de personalizadas. Esa etiqueta es la respuesta completa. Si está ahí, tu archivo no se está usando.

Puedes comprobar lo mismo desde la línea de comandos, que es más rápido y funciona incluso cuando el editor del sitio se porta mal:

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

Cada fila es una anulación en la base de datos. El post_name coincide con el slug de la plantilla, así que una fila llamada single está tapando templates/single.html.

Un detalle que despista: estos registros se vinculan a un tema mediante un término de taxonomía, no mediante una ruta. Si renombras la carpeta de tu tema, las plantillas guardadas siguen en la base de datos pero dejan de coincidir con el tema activo, y el sitio pasa de golpe a usar los archivos. Eso parece “mis personalizaciones desaparecieron” en lugar de “mi archivo se ignora”: mismo mecanismo, síntoma opuesto.

Bórralo

En el editor del sitio, abre el menú de opciones de la plantilla (los tres puntos que hay junto a ella) y elige Borrar personalizaciones; algunas versiones lo etiquetan como Restablecer. Eso elimina el registro de la base de datos y el control vuelve al archivo en disco.

Si el menú ofrece Borrar en lugar de Borrar personalizaciones o Restablecer, esa plantilla existe solo en la base de datos y no tiene ningún archivo detrás. Eliminarla quita la plantilla por completo y WordPress cae hacia abajo por la jerarquía.

Desde WP-CLI, usando un ID de la lista anterior:

wp post delete 482 --force

Sé honesto contigo mismo sobre el coste: borrar las personalizaciones descarta permanentemente todo lo que construiste en el editor del sitio para esa plantilla, y no se puede deshacer. Si la versión del editor del sitio tiene trabajo de verdad dentro, copia antes el marcado de bloques: abre la plantilla en el editor, cambia a la vista de código y pega el resultado en tu archivo .html. Así el archivo pasa a ser la fuente de la verdad y no se pierde nada.

Cómo elige WordPress una plantilla

Los temas de bloques usan la misma lógica de jerarquía que los clásicos, solo que con archivos .html en templates/ en lugar de archivos .php en la raíz del tema. WordPress recorre de lo más específico a lo menos específico y usa el primer archivo que exista.

Se está viendo	Se comprueba en este orden
Una entrada individual	single-post-{slug}.html → single-post.html → single.html → singular.html → index.html
Una página	page-{slug}.html → page-{id}.html → page.html → singular.html → index.html
Un archivo de categoría	category-{slug}.html → category-{id}.html → category.html → archive.html → index.html
Un tipo de contenido personalizado	single-{post-type}.html → single.html → singular.html → index.html
La página 404	404.html → index.html

Dos cosas anulan esto por completo. Primero, el registro en la base de datos descrito arriba. Segundo, una plantilla asignada directamente a una entrada o página: abre el editor de entradas, busca el panel Plantilla en la barra lateral y comprueba si hay algo concreto seleccionado ahí. Una asignación explícita gana a la jerarquía siempre, y es invisible salvo que la busques.

Las plantillas basadas en slug son frágiles de una forma que conviene interiorizar. page-about.html coincide solo mientras el slug de la página sea about. Renombra la página a about-us y la plantilla deja de aplicarse sin aviso y sin error.

Plantilla frente a parte de plantilla

Una plantilla renderiza una vista entera y la selecciona la jerarquía. Una parte de plantilla es un fragmento (cabecera, pie, barra lateral) que las plantillas incorporan. Las partes viven en parts/, las plantillas en templates/, y se guardan por separado en la base de datos como registros wp_template_part.

La confusión habitual: editas la cabecera y el cambio aparece en páginas que no pretendías tocar. Ese comportamiento es correcto. Una misma parte la comparten todas las plantillas que la incluyen. Si quieres una cabecera distinta en una plantilla, necesitas un segundo archivo de parte y una plantilla que lo referencie; editar la compartida nunca te dará variación por plantilla.

También pasa lo contrario. Metes un diseño de página completo en parts/ y te preguntas por qué la jerarquía nunca lo recoge. Las partes no son candidatas en la jerarquía en absoluto; nada las va a enrutar directamente jamás.

Nombres y ubicación de los archivos

Comprueba esto antes de suponer nada más exótico:

• La carpeta es templates/, en plural, en la raíz del tema. No template/, ni block-templates/. block-templates/ era el nombre correcto en la época del plugin Gutenberg, antes de que los temas de bloques llegaran al núcleo, y muchos tutoriales lo siguen mostrando; en las versiones actuales de WordPress no funciona.
• Las partes de plantilla van en parts/, no en template-parts/ (que es la convención de los temas clásicos para los parciales PHP).
• La extensión es .html. Un archivo .php dentro de templates/ se ignora.
• Los nombres de archivo van en minúsculas y con guiones. single-Post.html o single_post.html no coinciden. En un sistema de archivos que no distingue mayúsculas, como el de macOS, esto funciona en local y se rompe en un servidor Linux: el clásico fallo de “en mi máquina funciona”.
• templates/index.html tiene que existir. Sin él, WordPress no clasifica el tema como tema de bloques y puede que el editor del sitio ni siquiera aparezca.
• Si trabajas en un tema hijo, sus plantillas tienen prioridad sobre las del padre. Un archivo olvidado en el tema hijo le ganará en silencio al archivo del padre que estás editando.

Las plantillas personalizadas que deban poder seleccionarse en el editor de entradas también hay que declararlas en theme.json bajo customTemplates, con el nombre base del archivo, un título legible y los tipos de contenido a los que se aplican. Sin esa entrada, el archivo existe pero nunca aparece en el panel Plantilla.

Caché: compruébalo al final

El caché es un problema real, pero es la causa menos probable, y empezar por ahí es como se pierde una tarde.

Vacía tu caché de página y, si usas un caché de objetos persistente como Redis o Memcached, vacíalo también: los resultados de la resolución de plantillas pueden quedarse ahí. Después recarga saltándote el caché del navegador.

Lo que no va a ayudar: vaciar OPcache. Las plantillas de bloques son archivos .html y PHP nunca las compila, así que OPcache no tiene nada que ver con ellas. Si alguna vez te pareció que vaciar OPcache arreglaba esto, algo más cambió al mismo tiempo.

¿Sigues atascado?

Si no hay registro en la base de datos, el nombre del archivo es correcto, no hay plantilla asignada explícitamente a la entrada y ya vaciaste los cachés, mira los plugins. Cualquier cosa que filtre la resolución de plantillas (un maquetador visual, un plugin de membresías, uno multilingüe, un LMS) puede sustituir la plantilla por la suya al final de la petición. Cambia a un tema de bloques por defecto y prueba con los plugins desactivados, y luego reactívalos de uno en uno.

Y si la plantilla sí se aplica pero se renderiza vacía, ese es otro problema: comprueba que el marcado de bloques del archivo es válido, ya que un comentario de bloque mal formado puede hacer que el editor elimine el contenido en silencio en lugar de lanzar un error.