Hacer cambios de estilo personalizados en tu sitio de WordPress normalmente implica editar varios archivos manualmente. Además, si cambias de tema, tendrás que volver a configurar todos estos ajustes desde cero. Puede ser un proceso que lleve bastante tiempo.
Por suerte, cuando WordPress lanzó la versión 5.8, introdujo un nuevo archivo theme.json. Este es un espacio específico para dar estilo al editor de bloques (y a bloques individuales) tanto en la parte pública como en el panel de administración. Como resultado, es mucho más fácil gestionar los estilos de tu sitio web.
En esta guía, analizaremos en detalle theme.json como archivo de configuración. A continuación, repasaremos algunos aspectos clave antes de mostrarte cómo editar theme.json en tu sitio.
¿Qué es theme.json en WordPress?
El archivo theme.json es un mecanismo que te permite configurar el Editor de bloques con mayor control. Es útil para hacer cambios de estilo en todo el sitio, ya que puedes asignar estilos predeterminados a todos tus bloques o solo a algunos.
En esencia, theme.json es una solución que mejora las capacidades de la API del Editor de bloques. Por ejemplo, con theme.json, podrás controlar el editor mediante programación. Además, podrás integrar un sistema de estilos de bloques. Esto facilita la gestión de las preferencias de usuarios, temas y del núcleo.
El archivo theme.json se introdujo al mismo tiempo que el Editor del sitio. Junto con él, theme.json es uno de los primeros pasos importantes para gestionar los estilos de futuras versiones de WordPress. Es una forma estupenda de obtener un mayor control sobre tu tema y tu sitio, para que puedas cambiar los menús, las cabeceras y los pies de página.
En resumen, el Editor del sitio te permite hacer montones de cambios de estilo globales, mientras que theme.json es el mecanismo que te permite configurar opciones personalizadas para tus bloques.
Por ejemplo, puedes redefinir los ajustes del Editor de bloques para mostrar u ocultar opciones de personalización a determinados usuarios. También puedes definir colores y tamaños de fuente predeterminados para tus bloques y configurar una nueva anchura o alineación para el editor.
¿Dónde se encuentra el archivo theme.json?
Encontrarás el archivo theme.json en la raíz del directorio de tu tema. Si utilizas el Editor del sitio y has activado un tema basado en bloques como Twenty Twenty-Three, sin duda tendrás disponible el archivo theme.json en tu tema.
Pero si el tema que has elegido no incluye theme.json como archivo de configuración, puedes cambiar de tema o crear tu propio archivo. Es importante tener en cuenta que algunos temas incluyen bloques muy específicos, ya sean de CSS o de estilos, que podrían ser incompatibles con los cambios que hagas en theme.json. Por ejemplo, el modo oscuro de Twenty Twenty-One no puede anularse mediante cambios de estilo añadidos en theme.json.
Qué hacer antes de editar tu archivo theme.json
Ahora que sabes un poco más sobre el archivo theme.json, veamos algunos factores importantes que debes tener en cuenta antes de hacer cambios.
1. Haz una copia de seguridad de tu sitio
Antes de hacer cualquier cambio importante, es fundamental hacer una copia de seguridad de tu sitio. Así, si algo sale mal, podrás recuperar tu web y volver a empezar.
Usar el plugin Jetpack VaultPress Backup es una de las formas más fáciles de hacer copias de seguridad de tu sitio.
Esta herramienta de Jetpack crea copias de seguridad en tiempo real y en la nube, y las almacena en la red de servidores seguros de WordPress.com. Además, el proceso de restauración es rápido y sencillo.
Puedes aprovechar las restauraciones con un solo clic desde la aplicación móvil, incluso si tu sitio está completamente caído.
2. Plantéate utilizar un sitio de staging
Un sitio de staging es una forma estupenda de probar los cambios que quieres hacer sin afectar a tu web activa. En esencia, un sitio de staging es una copia de tu web que no está disponible para el público general. De este modo, tendrás un entorno privado para probar nuevas funciones o actualizar tu sitio.
Así, no tendrás que preocuparte de que algo salga mal al editar el archivo theme.json. Además, si surge algún problema, seguirás teniendo acceso a tu sitio activo. También significa que, cuando finalmente publiques los cambios en tu sitio activo, podrás estar tranquilo sabiendo que no afectarán al funcionamiento de tus páginas.
Hay varias formas de configurar un sitio de staging. Puedes pedírselo a tu proveedor de hosting, configurar manualmente distintos subdominios para tu sitio o instalar un plugin. Sin embargo, puede ser más sencillo optar por una herramienta de desarrollo local de WordPress.
Cómo editar tu archivo theme.json
En este punto, ya puedes acceder a tu archivo theme.json y editarlo. En esta sección te mostraremos algunas formas útiles de editar theme.json como crear una paleta de colores y anular el tamaño de fuente predeterminado de tus bloques.
Para empezar, tendrás que acceder al directorio raíz de tu sitio web. Puedes hacerlo con un cliente SFTP como FileZilla o desde tu gestor de archivos. Después, ve al directorio public_html de tu sitio. Dentro de él, busca wp-content entre las carpetas.
A continuación, ve a themes y selecciona el tema activo de tu sitio. Aquí encontrarás theme.json si tu tema lo incluye.
1. Crea una paleta de colores predeterminada
Puede que quieras establecer una paleta de colores fija para el Editor. De este modo, podrás acceder rápidamente a tus colores y garantizar una identidad visual coherente en todas tus páginas.
Además, puede resultar útil si hay otros usuarios que crean entradas y páginas en tu sitio, ya que solo podrán acceder a los colores que incluyas en tu paleta. Tampoco podrán crear sus propios tonos ni degradados.
Para empezar, localiza theme.json siguiendo los pasos que hemos indicado antes. Aunque no es obligatorio, si solo quieres que los colores predeterminados de tu tema estén disponibles para el usuario, tendrás que hacer tres cosas:
- Desactiva los degradados personalizados
- Desactiva las opciones de color personalizadas
- Añade una paleta personalizada con los colores de tu marca
Después de conectarte a los archivos de tu tema mediante SFTP o el Administrador de archivos, tendrás que copiar el código siguiente y guardarlo en el directorio raíz de tu tema:
{
"version": 2,
"settings": {
"color": {
"custom": false,
"customGradient": false,
"gradients":[],
"link": false,
"palette":[
{
"slug": "vivadcyanblue",
"color": "#0693E3"
},
{
"slug": "vividgreencyan",
"color": "#00D084"
},
{
"slug": "white",
"color": "#ffffff"
}
]
}
}
}Ten en cuenta que tendrás que modificar el código anterior para adaptarlo a tus preferencias. En este caso, hemos desactivado las opciones de enlace personalizado, degradado personalizado y color personalizado.
Además, hemos establecido una paleta de colores fija con tres tonos diferentes. Por tanto, cuando los usuarios creen entradas y páginas en el sitio, solo podrán acceder a estos tonos.
Lo mejor de crear una paleta personalizada en theme.json es que WordPress también reescribirá todo el CSS necesario. De este modo, cualquier cambio de color que hagas en el Editor de bloques también se reflejará en la interfaz pública.
2. Configura tamaños de fuente personalizados
También puede ser útil configurar ciertos tamaños de fuente para el bloque Párrafo. Por supuesto, el bloque ofrece varios tamaños de fuente predeterminados, pero puedes usar theme.json para sustituirlos por tus preferencias.
De nuevo, tendrás que encontrar el directorio raíz de tu tema accediendo a la carpeta themes de wp-content. A continuación, localiza theme.json. Los tamaños de fuente se añaden a theme.json en la ruta settings → typography → fontSizes.
A continuación, tendrás que introducir tus valores. Usarás size para añadir un valor de tamaño de fuente CSS válido. Mientras tanto, slug es el identificador que WordPress usa en la propiedad personalizada CSS. También puedes añadir un name, pero esto es solo para tu uso personal, ya que es lo que verás en el editor.
En WordPress, el tamaño de fuente predeterminado «small» tiene el valor de 13 px, así que puedes basar tus valores en él. En definitiva, tu archivo theme.json tendrá un aspecto parecido a este cuando hayas añadido este código al archivo:
{
"version": 2,
"settings": {
"typography": {
"fluid": false,
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
},
{
"name": "Large",
"slug": "large",
"size": "36px"
},
{
"name": "Extra Large",
"slug": "x-large",
"size": "42px"
}
]
}
}
}Solo tienes que guardar los cambios para actualizar la configuración de bloques de WordPress.
3. Crea referencias a plantillas y partes de plantilla personalizadas
Otra forma de editar theme.json es crear una referencia a las plantillas personalizadas y las partes de plantilla. Como los temas pueden enumerar las plantillas personalizadas que se encuentran en la carpeta templates, puedes declarar los tipos de contenido que pueden usarlas y el título que muestras a tus usuarios.
Para empezar, abre theme.json. Tendrás que pensar en un nombre, un título y un tipo de entrada, aunque este último ajuste es opcional. Después, añade el siguiente código al archivo:
{
"version": 2,
"customTemplates": [
{
"name": "my-custom-template",
"title": "The template title",
"postTypes": [
"page",
"post",
"my-cpt"
]
}
]
}En este punto, ya has creado una plantilla para tus páginas, entradas y tipos de entrada personalizados. Puedes ir un paso más allá y crear partes de plantilla para tu tema.
De este modo, puedes configurar theme.json para declarar el término de área de una parte de plantilla, como un bloque de cabecera o pie de página. Al definirlo en theme.json, puedes asegurarte de que la configuración se aplica a todos los usos de esa entidad de parte de plantilla, en lugar de solo a un bloque.
Antes de empezar, tendrás que tener en cuenta el nombre, el título y el área de tu parte de plantilla. Es importante señalar que, si no especificas un área, se establecerá como «sin categoría» y no activará ninguna variación de bloque.
Para crear una parte de plantilla para tu tema, añade el siguiente código a theme.json:
{
"version": 2,
"templateParts": [
{
"name": "my-template-part",
"title": "Footer",
"area": "footer"
}
]
}Después, asegúrate de guardar los cambios antes de salir de theme.json.
Qué hacer si tu sitio deja de funcionar al editar el archivo theme.json
Si guardas el archivo theme.json y el editor del sitio aparece en blanco, o ves un mensaje de error que dice «JSON no válido», no te preocupes. Normalmente significa que hay un error de sintaxis.
Comprueba estos tres errores habituales:
- La coma final. Has añadido una coma después del último elemento de una lista. JSON no admite esto. Elimina la última coma.
- Las llaves. Has abierto una sección con {, pero has olvidado cerrarla con }.
- Las comillas. Has usado comillas simples ‘. JSON solo acepta comillas dobles “.
Si no encuentras el error, copia tu código y pégalo en una herramienta online gratuita como JSONLint. Te indicará el número de línea exacto en el que se encuentra el problema.
Preguntas frecuentes
Ahora ya sabes cómo editar theme.json, pero es posible que aún tengas algunas dudas al respecto. Por eso hemos respondido a algunas de las preguntas más frecuentes sobre el archivo theme.json a continuación.
¿Cuándo se introdujo por primera vez theme.json en WordPress?
El archivo theme.json se introdujo por primera vez con el lanzamiento de WordPress 5.8. Fue entonces cuando se lanzó la Edición completa del sitio (FSE) junto con la posibilidad de usar temas basados en bloques.
Esta versión supuso un enorme cambio para la plataforma, ya que los usuarios obtuvieron la posibilidad de hacer cambios en todo el sitio y disfrutaron de un mayor control sobre la configuración del estilo. Más tarde, con WordPress 5.9, theme.json evolucionó a una segunda versión.
¿Qué puedes hacer con el archivo theme.json?
En resumen, theme.json permite cambiar y aplicar nuevas opciones relacionadas con el estilo a todos tus bloques de WordPress. Por lo tanto, obtienes un control más preciso sobre los cambios de estilo. Además, puedes evitar tener que configurar estos cambios individualmente en cada bloque.
Por ejemplo, puedes editar theme.json para activar o desactivar funciones como la capitular, el relleno, el margen y la altura de línea personalizada. Además, puedes añadir varias paletas de colores, duotonos y degradados para aplicar más rápidamente los colores de tu marca a los elementos de tu página.
Además, puedes especificar tamaños de fuente exactos y aplicarlos en todo tu sitio. También puedes añadir anchos predeterminados para tu contenido y asignar partes de plantilla a áreas de partes de plantilla.
¿Cuáles son los requisitos previos para usar el archivo theme.json?
Editar theme.json es una forma sencilla de hacer cambios de estilo en todo el sitio. Pero, por desgracia, no es una opción disponible para todos los usuarios.
Para empezar, tendrás que usar el Editor de bloques. Si prefieres usar constructores de páginas, no podrás aprovechar esta funcionalidad. Además, tendrás que tener algunos conocimientos de CSS y sentirte cómodo editando los archivos de tu sitio.
Por último, tendrás que poder acceder a theme.json. Como hemos comentado antes, no todos los temas utilizan theme.json como archivo de configuración. Además, la configuración de algunos temas anulará cualquier cambio que hagas en theme.json.
Si tu tema tiene theme.json, podrás encontrarlo en el directorio raíz de tu sitio. Puedes localizarlo mediante SFTP o desde tu gestor de archivos. Después, busca la carpeta themes que está dentro de wp-content. Allí se encuentra theme.json como archivo de configuración. Si tu tema no tiene theme.json, puedes cambiar de tema o crear por tu cuenta el archivo theme.json que falta.
¿Cuál es la diferencia entre theme.json y style.css en WordPress?
La principal diferencia está en cómo funcionan. style.css es una hoja de estilos estándar que aplica reglas de diseño mediante código CSS. theme.json es un archivo de configuración que se comunica directamente con la interfaz del editor de WordPress.
Mientras style.css solo cambia el aspecto del sitio en la interfaz pública, theme.json controla tanto el aspecto de la interfaz pública como la configuración del editor en el back-end. Por ejemplo, utilizas theme.json para activar o desactivar funciones específicas para los usuarios, como los colores personalizados o los tamaños de fuente. Básicamente, gestiona el panel de configuración con el que interactúan los usuarios. Los temas de bloques modernos dependen en gran medida de theme.json para generar CSS automáticamente, lo que a menudo reduce la cantidad de código que tienes que escribir en style.css.
¿Puedo utilizar theme.json con un tema clásico de WordPress?
Sí. Puedes añadir un archivo theme.json a un tema clásico basado en PHP. Este enfoque suele denominarse híbrido. Te permite modernizar un tema antiguo sin tener que reconstruirlo por completo desde cero.
Cuando añades este archivo a un tema clásico, activa los nuevos estilos y ajustes del editor de bloques. Te ayuda a controlar la tipografía, la paleta de colores y las opciones de diseño de cualquier bloque utilizado en las áreas de contenido clásico. Es una forma inteligente de aprovechar las ventajas de la edición moderna de sitios de WordPress, como los estilos globales coherentes, mientras mantienes tus plantillas de PHP existentes para las cabeceras y los pies de página.
¿Cómo soluciono el error «JSON no válido» en WordPress?
Este error casi siempre se debe a un error de sintaxis en tu archivo. JSON es muy estricto con el formato. La causa más habitual es una coma final. Esto significa que has colocado una coma después del último elemento de una lista o un grupo. Debes eliminar esa última coma para que el archivo funcione.
Otro problema habitual está relacionado con las comillas. Debes utilizar comillas dobles " para todas las propiedades y los valores. Las comillas simples ' harán que el archivo deje de funcionar. Si tu sitio muestra una pantalla en blanco o un mensaje de error, copia el código y pégalo en una herramienta de validación de JSON en línea. La herramienta señalará el número de línea exacto en el que la puntuación es incorrecta para que puedas solucionarlo rápidamente.
¿Cuál es la diferencia entre «ajustes» y «estilos» en theme.json?
Estas dos secciones tienen funciones distintas. La sección settings controla la interfaz de usuario del editor de bloques. Determina qué herramientas están disponibles para el creador de contenido. Por ejemplo, utilizas settings para definir las opciones de la paleta de colores, activar las letras capitulares o desactivar los tamaños de fuente personalizados.
La sección styles aplica las reglas visuales reales al sitio. Aquí es donde defines el aspecto predeterminado. Si quieres que todos los encabezados sean azules y estén en negrita de forma predeterminada, lo defines en styles. Piensa en settings como la configuración de las herramientas, y en styles como la aplicación del diseño.
¿Cómo puedo desactivar los colores predeterminados de WordPress mediante theme.json?
Puedes desactivar los colores predeterminados para obligar a los usuarios a ceñirse a la paleta específica de tu marca. Esto evita que los clientes elijan colores aleatorios que no combinan con tu diseño. Para hacerlo, tienes que modificar la sección settings de tu archivo.
Dentro de settings.color, debes establecer defaultPalette en false. Una vez hecho esto, los colores estándar de WordPress (como el azul o el negro predeterminados) desaparecerán del selector de color. El usuario solo verá los colores personalizados que definas explícitamente en la matriz de colores de tu propia paleta. Esto garantiza una coherencia estricta de marca en todo el sitio web.
¿Los temas hijo heredan los ajustes del theme.json principal?
Sí. Los temas hijo heredan todo del archivo de configuración del tema principal. Sin embargo, el tema hijo puede sobrescribir partes específicas. WordPress combina ambos archivos.
Si el tema principal establece el fondo en blanco y el tema hijo lo establece en gris, prevalece el tema hijo. No tienes que copiar todo el archivo al tema hijo. Solo tienes que escribir las líneas específicas que quieras cambiar o añadir. Este modelo de herencia facilita la creación de variaciones de un tema sin duplicar código. Mantiene tu proyecto limpio y facilita su mantenimiento con el tiempo.
¿Utilizar theme.json mejora el rendimiento del sitio web?
Sí. Utilizar este archivo puede mejorar la velocidad del sitio y las puntuaciones de Core Web Vitals. Cuando defines estilos en theme.json, WordPress genera CSS únicamente para los bloques que realmente se utilizan en la página.
Es mucho más eficiente que cargar un archivo style.css enorme que contenga miles de líneas de código para elementos que quizá ni siquiera existan en la página actual. Este enfoque reduce el tamaño total del archivo que el navegador necesita descargar. También ayuda con Cumulative Layout Shift (CLS), porque los ajustes de diseño se cargan al principio del proceso de renderizado.
¿Cómo añado fuentes personalizadas localmente a mi tema de WordPress?
Puedes registrar archivos de fuentes locales directamente en theme.json. Así no necesitas plugins externos ni reglas manuales en CSS mediante @font-face. Defines un array de fontFamilies dentro de la sección settings.typography.
Para cada fuente, proporcionas el nombre, el slug y la ruta del archivo de tus fuentes locales (como archivos .woff2) almacenadas en la carpeta de tu tema. WordPress gestiona automáticamente la carga de estos recursos. Alojar las fuentes localmente es mejor para el cumplimiento de la privacidad (como GDPR) y el rendimiento, porque elimina la necesidad de conectarse a servidores de terceros como Google Fonts.
¿Puedo establecer estilos diferentes para bloques específicos en theme.json?
Sí. Puedes aplicar estilos específicos a bloques individuales para que sean diferentes de los valores predeterminados globales. Esto se hace dentro de la sección styles.blocks.
Por ejemplo, quizá quieras que el texto de los párrafos sea negro de forma predeterminada, pero que el texto del bloque «Cita» aparezca en cursiva y gris. Abrirías una entrada específica para core/quote y aplicarías allí esas reglas de tipografía y color. Esto permite controlar cada elemento con gran precisión. Garantiza que los componentes específicos tengan exactamente el aspecto que quieres sin escribir manualmente selectores CSS complejos.
¿Por qué no aparecen en el sitio mis cambios en theme.json?
Hay dos razones principales por las que los cambios podrían no aparecer de inmediato. La primera es la caché del navegador o del servidor. Borra la caché del navegador o consulta el panel de control de tu proveedor de hosting para vaciar la caché gestionada.
La segunda razón es la especificidad de CSS. Si tienes un archivo CSS independiente que use !important o selectores muy específicos, ese código podría anular los ajustes de theme.json. Además, si un usuario ha cambiado manualmente el color de un bloque en el editor de páginas, esa elección manual tiene prioridad sobre el valor predeterminado global. Comprueba la página concreta en el editor para ver si hay alguna anulación local activa.
¿Qué versión de WordPress es compatible con theme.json v3?
La versión 3 de Theme.json se introdujo oficialmente en WordPress 6.6. Si hoy estás creando un tema de bloques nuevo, deberías usar la versión 3 para asegurarte de que tu tema siga siendo compatible con futuras actualizaciones.
Esta versión introdujo un cambio importante en el funcionamiento de las anulaciones. En versiones anteriores, tus ajustes preestablecidos personalizados anulaban automáticamente los ajustes preestablecidos principales predeterminados. En la versión 3, este comportamiento es más explícito, lo que te proporciona un mayor control, pero requiere una configuración más estricta. Si tu sitio utiliza una versión antigua de WordPress (entre la 5.9 y la 6.5), debes seguir usando la versión 2. Sin embargo, como la mayoría de los sitios activos se actualizan automáticamente, la versión 3 es la opción más segura para el desarrollo moderno.
¿Por qué mis tamaños de fuente no anulan los valores predeterminados?
Este problema suele deberse a la naturaleza «en cascada» de CSS o a un comportamiento específico en las versiones más recientes de theme.json. Primero, comprueba si has establecido manualmente un tamaño de fuente en el bloque específico dentro del editor de WordPress. Un cambio manual realizado por un usuario en una página específica siempre prevalece sobre los valores predeterminados globales de tu theme.json.
En segundo lugar, si utilizas la versión 3, las reglas para sobrescribir los ajustes preestablecidos del núcleo han cambiado. Puede que debas asegurarte de que tus tamaños personalizados utilizan exactamente los mismos «slugs» (nombres) que los valores predeterminados si quieres reemplazarlos por completo. Por último, inspecciona tu sitio con la herramienta «Inspeccionar elemento» del navegador. Otro plugin o un archivo style.css residual podría estar cargando una regla de CSS más específica que obliga a que el tamaño de la fuente no cambie.
Usa el archivo theme.json de WordPress para un diseño web más sencillo
Realizar cambios personalizados en todo el sitio suele implicar editar numerosos archivos o completar muchas tareas manualmente. Pero, con theme.json, dispondrás de un espacio específico para controlar y gestionar todos los ajustes de estilo de tu sitio.
El archivo theme.json se encuentra en el directorio raíz de tu sitio a partir de WordPress 5.8. Puedes editarlo para realizar cambios importantes, como aplicar una paleta de colores personalizada a tu sitio y sobrescribir los tamaños de fuente predeterminados de WordPress.
Antes de editar el archivo theme.json de tu sitio, es importante hacer una copia de seguridad de tu sitio. Jetpack VaultPress Backup es un plugin fácil de usar que te permite restaurar tu sitio incluso cuando estás sin conexión. ¡Además, hace copias de seguridad de todos tus archivos, datos de WooCommerce y de tu base de datos!
Jetpack 