¿Qué es el archivo theme.json en WordPress y cómo usarlo

El archivo theme.json es una parte importante de los temas de bloques de WordPress, ya que controla muchos aspectos de la apariencia y funcionalidad de tu sitio. Si recientemente cambiaste de un tema clásico a uno de bloques, es posible que te preguntes de qué se trata este archivo y si deberías editarlo.

No estás solo. Nosotros y muchos usuarios de WPBeginner también nos hemos estado preguntando exactamente lo mismo. Así que decidimos investigar a fondo este tema para ofrecer una guía completa.

En este artículo, explicaremos qué es un archivo theme.json, por qué es importante y cómo puedes usarlo para personalizar tu sitio de WordPress. 

¿Qué es el archivo theme.json de WordPress?

El archivo theme.json es un archivo de tema especial introducido en WordPress 5.8. Juega un papel clave en la experiencia de edición completa del sitio (FSE), que te permite personalizar visualmente cada aspecto de tu tema de bloques de WordPress.

Esencialmente, el archivo theme.json actúa como un plano que controla el estilo y la funcionalidad de tu tema de bloques. Contiene código que le dice a WordPress cómo deben verse y comportarse diferentes elementos como colores, tipografía, diseños y plantillas.

¿Por qué los temas de bloques de WordPress necesitan un archivo theme.json?

Editar un tema de bloques en WordPress es diferente a editar un tema clásico.

Los temas clásicos usan el archivo functions.php para habilitar funciones como menús personalizados o imágenes destacadas con la función add_theme_support(). Luego, puedes estilizar esas funciones con reglas CSS en el archivo de hoja de estilos CSS (style.css).

En los temas de bloques, theme.json actúa como un centro de control para todo lo que define la apariencia de tu tema de bloques. Te permite definir cosas como fuentes, colores y opciones de diseño en un solo lugar, reemplazando la necesidad de add_theme_support() en functions.php.

Es por eso que el archivo functions.php en los temas de bloques suele ser más pequeño que el equivalente en los temas clásicos.

Tener un archivo theme.json dedicado ofrece grandes beneficios sobre el sistema anterior de temas clásicos.

Primero, theme.json funciona en conjunto con el editor de sitio completo de WordPress. Esto te permite personalizar los estilos y configuraciones de tu tema fácilmente directamente desde el editor, sin necesidad de tocar ningún código.

Además, theme.json busca crear una experiencia consistente tanto para desarrolladores como para usuarios. Algunos usuarios encuentran frustrante cuando necesitan cambiar de tema porque tienen que aprender diseños y opciones de estilo completamente nuevos.

Con theme.json, cambiar de tema se convierte en un proceso más fluido porque todo está organizado de manera similar.

Finalmente, al usar theme.json, los desarrolladores y usuarios de temas pueden preparar su trabajo para el futuro a medida que WordPress continúa expandiendo sus capacidades de edición de sitio completo.

Ahora que hemos cubierto qué es un archivo theme.json, profundicemos en el tema. Puedes usar los enlaces rápidos a continuación para navegar por esta guía:

• ¿Dónde encuentras el archivo theme.json de WordPress?
• ¿Cómo se ve el archivo theme.json?
• Qué debes hacer antes de editar el archivo theme.json
• Cómo editar el archivo theme.json de WordPress
• Consejo extra: Usa WPCode para agregar código personalizado a tu tema

¿Dónde encuentras el archivo theme.json de WordPress?

El archivo theme.json se encuentra dentro del directorio de tu tema en tu servidor web. La ruta de archivo típica sería public_html » wp-content » themes » tu-nombre-de-tema » theme.json.

Para acceder a él, primero necesitas conectarte a tu sitio a través de FTP o el administrador de archivos de tu cuenta de hosting.

Si usas Bluehost, puedes iniciar sesión y cambiar a la pestaña ‘Websites’. Luego, haz clic en el botón ‘Settings’ debajo de tu sitio web.

Ahora, asegúrate de permanecer en la pestaña ‘General’.

Luego, desplázate hacia abajo para hacer clic en el botón ‘Administrador de archivos’.

Cuando abras el administrador de archivos de esta manera, estarás automáticamente dentro de la carpeta raíz de tu sitio web.

Aquí, busca el directorio ‘wp-content’ y ábrelo. Allí, encontrarás la carpeta ‘themes’ que contiene todos tus temas de WordPress instalados.

Abre la carpeta del tema de bloques específico que estés utilizando. El archivo theme.json se encontrará directamente dentro de este directorio de temas junto con otros archivos del tema.

Una vez que lo hayas encontrado, puedes ver el archivo theme.json usando un editor de código.

¿Cómo se ve el archivo theme.json?

El archivo theme.json tiene una estructura específica que organiza todas las configuraciones globales para tu tema de bloques de WordPress.

Dependiendo de cuán complejo o simple se vea tu tema, el archivo puede ser muy corto o largo. Sin embargo, puedes dividir fácilmente este archivo en 7 secciones de nivel superior:

{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {},
"patterns": []
}

Aquí tienes un desglose simplificado:

Esquema

Esta parte es en realidad opcional en los temas de bloques, por lo que es posible que la veas o no en el tuyo.

La propiedad schema enlaza la URL con el esquema JSON de WordPress, que define las configuraciones globales, estilos y otras configuraciones para tu tema.

Versión

Esta sección especifica qué versión de la API del formato theme.json está utilizando el archivo y asegura que siga la estructura correcta.

Al momento de escribir este artículo, la API está en la versión 2.

Configuración

Esta propiedad define las opciones y controles disponibles para que los usuarios personalicen su tema. Estos incluyen ajustes preestablecidos para la paleta de colores del tema, tipografía, espaciado, degradados, sombras, bordes, etc.

Aquí tienes un ejemplo muy simple de cómo se ve la propiedad de configuración:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "base",
          "color": "#ffffff",
          "name": "White"
        },
        {
          "slug": "contrast",
          "color": "#222222",
          "name": "Dark"
        },
        {
          "slug": "accent",
          "color": "#f08080",
          "name": "Pink"
        },
        {
          "slug": "accent-2",
          "color": "#90ee90",
          "name": "Light Green"
        },
        {
          "slug": "accent-3",
          "color": "#e0ffff",
          "name": "Light Blue"
        }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "Open Sans, sans-serif",
          "slug": "open-sans",
          "name": "Open Sans"
        },
        {
          "fontFamily": "Arial, sans-serif",
          "slug": "arial",
          "name": "Arial"
        },
        {
          "fontFamily": "Times New Roman, serif",
          "slug": "times-new-roman",
          "name": "Times New Roman"
        }
      ],
      "fontSizes": [
        {
          "name": "Extra Small",
          "slug": "xx-small",
          "size": "0.75rem"
        },
        {
          "name": "Small",
          "slug": "small",
          "size": "0.875rem"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "1rem"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "1.125rem"
        },
        {
          "name": "Extra Large",
          "slug": "x-large",
          "size": "1.25rem"
        },
        {
          "name": "XX-Large",
          "slug": "xx-large",
          "size": "1.5rem"
        }
      ],
      "spacing": {
        "units": ["rem"],
        "values": {
          "small": "1rem",
          "medium": "1.5rem",
          "large": "2rem"
        }
      }
    }
  }
}

Si observas el código, el lenguaje utilizado es bastante fácil de entender. Puedes notar que la configuración define los colores, familias de fuentes, tamaños de fuente y el espaciado utilizados en el tema.

Si hay alguna referencia aquí o en tu tema que no entiendas, puedes consultar la Referencia oficial de configuración de WordPress.

Algunos elementos, como los colores y las familias de fuentes, tienen identificadores (slugs), como este:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "base",
          "color": "#ffffff",
          "name": "White"
        },

Estos serán útiles para la sección de estilos más adelante para crear ajustes preestablecidos, lo cual explicaremos en la siguiente parte.

Estilos

Mientras que la sección de configuración define las opciones de personalización predeterminadas del tema, la sección de estilos las aplica al tema.

Aquí, puedes aplicar la configuración de personalización a todo el sitio web o a nivel de bloque utilizando ajustes preestablecidos.

Veamos el siguiente ejemplo:

{
  "settings": {
    // Existing settings from the previous example
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    },
    "elements": {
      "link": {
        "color": {
          "text": "var(--wp--preset--color--accent-2)"
        }
      },
      "h1": {
        "fontSize": "var(--wp--preset--font-size--xx-large)",
        "lineHeight": "1.2",
        "marginBottom": "1rem"
      },
      "h2": {
        "fontSize": "var(--wp--preset--font-size--x-large)",
        "lineHeight": "1.2",
        "marginBottom": "1rem"
      },
      "h3": {
        "fontSize": "var(--wp--preset--font-size--large)",
        "lineHeight": "1.2",
        "marginBottom": "1rem"
      }
    }
  }
}

Como puedes ver, hay esta línea de código que aparece en todo este fragmento: var(--wp--preset--xxx). Estos son ajustes preestablecidos, que son atajos en la sección de estilos que se refieren a los valores definidos en la sección de configuración.

Por ejemplo, considera {"slug": "base", "color": "#ffffff", "name": "White"} en la sección de configuración. Aquí, "base" es el identificador (slug), y el ajuste preestablecido correspondiente para este color es var(--wp--preset--color--base).

Por lo tanto, el código "color": {"background": "var(--wp--preset--color--base)" en los estilos dice que el color de fondo de este tema es blanco.

Plantillas personalizadas

En el desarrollo de temas de bloques de WordPress, los desarrolladores pueden crear diseños predefinidos para páginas personalizadas, publicaciones o tipos de publicaciones personalizadas para que los usuarios las utilicen.

Por ejemplo, el tema Twenty Twenty-Four tiene varias plantillas personalizadas definidas en el archivo theme.json: Página sin título, Página con barra lateral, Página con imagen ancha y Individual con barra lateral.

Puedes usar cualquiera de estas para crear tu contenido.

],
"customTemplates": [
  {
    "name": "page-no-title",
    "postTypes": ["page"],
    "title": "Page No Title"
  },
  {
    "name": "page-with-sidebar",
    "postTypes": ["page"],
    "title": "Page With Sidebar"
  },
  {
    "name": "page-wide",
    "postTypes": ["page"],
    "title": "Page with wide Image"
  },
  {
    "name": "single-with-sidebar",
    "postTypes": ["post"],
    "title": "Single with Sidebar"
  }
]

Una cosa a tener en cuenta es que el archivo theme.json solo hace referencia a las plantillas por nombre y proporciona metadatos sobre ellas, como su título y los tipos de publicación para los que están destinadas.

Sin embargo, la apariencia y funcionalidad reales de las plantillas personalizadas se definen en archivos de plantilla separados dentro de la carpeta del tema.

Para verlas, puedes ir a public_html » wp-content » themes » tu-nombre-de-tema » templates.

Partes de plantilla

Las partes de plantilla son áreas reutilizables que puedes aplicar en tus plantillas personalizadas. Estos son elementos como encabezados, pies de página, barras laterales, etc.

Así es como se ven esas partes de plantilla registradas en theme.json:

"templateParts": [
  {
    "area": "header",
    "name": "header",
    "title": "Header"
  },
  {
    "area": "footer",
    "name": "footer",
    "title": "Footer"
  },
  {
    "area": "sidebar",  // Removed "uncategorized"
    "name": "sidebar",
    "title": "Sidebar"
  },
  {
    "area": "post-meta",  // Removed "uncategorized"
    "name": "post-meta",
    "title": "Post Meta"
  }
]

Al igual que las plantillas personalizadas, el archivo theme.json solo hace referencia a las plantillas.

Su apariencia real se define en sus propios archivos de parte de plantilla en la carpeta parts.

Patrones

Los patrones son colecciones predefinidas de bloques que te permiten crear diseños de contenido personalizados en tus páginas, publicaciones o en cualquier otro lugar de tu tema.

Cuando abres el editor de sitio completo, es posible que notes el menú Patrones. Aquí es donde puedes encontrar todos los patrones disponibles para tu tema de bloques de Gutenberg.

Con theme.json, los desarrolladores de temas pueden referenciar patrones del directorio público de Patrones de WordPress. Es una excelente manera de ofrecer más opciones de personalización sin tener que diseñar estos bloques reutilizables tú mismo.

Por ejemplo, el tema Twenty Twenty-Four hace referencia a dos patrones del directorio oficial: tres columnas de servicios y la sección de clientes:

"patterns": [
  "three-columns-of-services",
  "clients-section"
]

Sabemos esto porque estos patrones están en el menú Patrones en el editor de sitio completo.

Sin embargo, no están en la carpeta patterns dentro del directorio del tema.

Qué debes hacer antes de editar el archivo theme.json

Dado que theme.json es un archivo central del tema, editarlo directamente en tu sitio web de WordPress en vivo conlleva cierto riesgo. Errores accidentales podrían potencialmente dañar tu tema o sitio web.

Un enfoque más seguro es usar un tema hijo.

Un tema hijo hereda todas las variaciones de estilo y funcionalidades de tu tema padre (el tema de bloques que estás utilizando) pero te permite personalizar cosas sin modificar el tema padre en sí. De esta manera, si el tema padre recibe actualizaciones, tus personalizaciones no se sobrescribirán.

Puedes leer nuestra guía sobre cómo crear un tema hijo en WordPress para obtener más información. Este artículo muestra un método sencillo con el plugin Create Block Theme, que generará automáticamente un nuevo archivo theme.json solo para tu tema hijo.

Para garantizar una experiencia de edición fluida y evitar cualquier tiempo de inactividad del sitio web, también recomendamos crear una nueva copia de seguridad de tu sitio de WordPress. De esta manera, si algo sale mal, puedes restaurar fácilmente tu sitio a su estado anterior.

Recomendamos usar un plugin como Duplicator para una solución de copia de seguridad rápida y confiable.

También se recomienda trabajar en un entorno de desarrollo local de WordPress o un sitio de staging. Esto crea una réplica de tu sitio web en vivo donde puedes probar cambios de forma segura sin afectar a tus visitantes.

Aquí tienes algunos consejos más a tener en cuenta:

• Comienza con ediciones menores en tu archivo theme.json y pruébalas a fondo antes de hacer cambios más complejos.
• Si no estás seguro de alguna propiedad o configuración específica dentro del archivo theme.json, consulta la documentación oficial de WordPress.
• No dudes en buscar ayuda del equipo de soporte del desarrollador del tema o de los foros de soporte de WordPress.org si encuentras algún problema. Consulta nuestra guía sobre cómo pedir soporte de WordPress para más información.

Cómo editar el archivo theme.json de WordPress

Basándonos en nuestra investigación y pruebas, hemos descubierto dos formas de editar un archivo theme.json de WordPress: usando el editor de sitio completo o usando código. La primera opción es mucho más fácil y segura, y te permite ver tus modificaciones desde el front-end de tu sitio web.

Mientras tanto, la segunda opción se recomienda si te sientes cómodo con el desarrollo avanzado de WordPress.

Edita theme.json sin código (principiantes)

Para editar tu archivo theme.json sin tocar el código directamente, puedes usar el plugin Create Block Theme. Este plugin fue publicado por el equipo oficial de WordPress.org para permitir a los usuarios crear un tema de bloques personalizado, editarlo y/o guardar las variaciones de estilo de su tema de bloques.

Primero, procede a instalar el plugin de WordPress en tu área de administración. Luego, abre el editor de sitio completo yendo a Apariencia » Editor.

Ahora verás varios menús para editar tu tema.

Aquí, selecciona 'Estilos'.

A continuación, haz clic en el ícono del lápiz 'Editar estilos'.

Esto te llevará al editor de bloques para editar la configuración global y los estilos de tu sitio web.

Ahora, puedes cambiar el estilo de tu tema como de costumbre. Puedes leer la sección sobre cómo editar los estilos globales de tu tema en nuestra guía de edición de sitio completo de WordPress para más información.

Intentemos crear una paleta de colores personalizada como ejemplo.

El esquema de color o paleta es un conjunto de colores predeterminados para elementos como texto, fondos y botones. Asegura una apariencia cohesiva en todo tu sitio web.

Los elementos que usan la misma preconfiguración de color siempre coincidirán para que el diseño de tu sitio web se vea pulido y profesional.

Para editar la paleta, selecciona 'Colores' en la barra lateral de configuración de Estilos.

En la siguiente pantalla, verás algunas configuraciones para personalizar los colores de tu tema.

Aquí, haz clic en los colores en la sección 'Paleta'.

En este ejemplo, el tema Twenty Twenty-Four ya ha definido 5 colores en la paleta, pero puedes cambiar cualquiera de ellos para crear uno personalizado desde cero.

Para hacerlo, haz clic en uno de los colores debajo de ‘Tema’. Luego, selecciona cualquier color en la herramienta de selección de color.

Ahora, si previsualizas tu sitio web, verás que los bloques o elementos específicos que usaban el color anterior han sido reemplazados por el color que acabas de seleccionar en tu paleta.

Puedes repetir los mismos pasos para cada color. Luego, haz clic en ‘Guardar’.

Después de guardar tus cambios, haz clic en el botón Crear tema de bloque (el ícono de la llave inglesa).

Luego, selecciona ‘Guardar cambios en el tema’.

En la siguiente pantalla, necesitas desplazarte hacia abajo.

Después de eso, haz clic en ‘Guardar cambios’. Esto le pedirá a WordPress que almacene todos los cambios que has hecho en tu tema en el archivo theme.json.

Una vez que hagas eso, el editor de bloques se actualizará solo.

Ahora, haz clic de nuevo en el botón Crear tema de bloque y selecciona ‘Ver theme.json’.

Para ver el código de tu paleta de colores personalizada, busca palette anidado dentro de color y settings, así:

"settings": {
  // Some code...
  "color": {
    // Some code...
    "palette":  
  }
}

Debajo de él, deberías ver los nuevos códigos hexadecimales de tu paleta de colores personalizada.

Edita theme.json con código (usuarios avanzados)

Este método se recomienda si aspiras a ser un desarrollador de temas de WordPress o tienes algo de experiencia con código.

Primero, abre el archivo theme.json de tu tema de bloque en tu directorio de WordPress. Puedes usar el editor de código en el administrador de archivos de tu host web o descargar el archivo, editarlo en tu computadora y volver a subirlo a tu servidor.

Usaremos el tema Twenty Twenty-Four y el administrador de archivos de Bluehost con fines de demostración. Si eres usuario de Bluehost y estás utilizando el administrador de archivos, puedes simplemente hacer clic derecho en tu archivo theme.json y seleccionar ‘Editar’.

Si usas FTP, puedes leer nuestra guía sobre cómo usar FTP para subir archivos a WordPress.

Intentemos un ejemplo sencillo de edición de tu archivo theme.json: crear tamaños de fuente personalizados.

De nuevo, recuerda que la propiedad settings especifica los estilos predeterminados de tu tema, mientras que la propiedad styles los implementa. Por esta razón, editaremos la propiedad settings en el archivo theme.json.

Si usas un tema hijo, entonces puedes simplemente copiar y pegar el siguiente código en tu archivo theme.json y cambiar los tamaños de fuente en píxeles como mejor te parezca:

{
  "settings": {
    "typography": {
      "fluid": false,
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "16px"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "24px"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "40px"
        },
        {
          "name": "Extra Large",
          "slug": "x-lagrge",  // Typo fixed (large -> large)
          "size": "48px"
        }
      ]
    }
  }
}

Nota: Si estás editando el archivo de tu tema padre directamente, entonces necesitas encontrar el código que dice fontSizes.

Debería estar anidado dentro de typography y settings, así:

{
  "settings": {
    // Some code...
    "typography": {
      // Some code...
      "fontSizes": [
        // Font size definitions here
      ]
    }
  }
}

Después de eso, reemplaza esas líneas de código con el fragmento de código de arriba. Solo asegúrate de que no haya errores de sintaxis en él.

Una vez hecho, guarda el archivo y previsualiza tu sitio web para ver tus cambios. Para los usuarios de Bluehost, puedes simplemente hacer clic en ‘Guardar cambios’ en el editor de código del administrador de archivos.

Si deseas editar tu theme.json aún más, te animamos a familiarizarte con la estructura del archivo como se explica en la sección anterior.

También te sugerimos leer la Referencia oficial de configuración de WordPress, que incluye una lista completa de las propiedades de configuración disponibles e instrucciones para usarlas.

Consejo extra: Usa WPCode para agregar código personalizado a tu tema

En esta guía, has aprendido sobre theme.json y su potencial para la personalización de temas. Pero tal vez todavía te parezca un poco abrumador editarlo directamente.

Afortunadamente, existe otra opción fácil de usar para agregar código personalizado y realizar personalizaciones avanzadas: WPCode.

Con WPCode, puedes insertar fragmentos de código personalizados sin tener que tocar los archivos de tu tema. Esto reduce significativamente el riesgo de romper tu sitio web durante la personalización.

Si deseas obtener más información sobre este plugin de fragmentos de código, consulta nuestra reseña completa de WPCode.

Además, aquí tienes algunos tutoriales útiles para empezar a usar WPCode:

• Fragmentos de código útiles de WordPress para principiantes (selección de expertos)
• Cómo resaltar publicaciones nuevas para visitantes recurrentes en WordPress
• Cómo resaltar texto en WordPress
• Cómo agregar fácilmente sombra de caja en WordPress

Esperamos que este artículo te haya ayudado a aprender sobre el archivo theme.json en WordPress. También puedes consultar nuestra guía para principiantes sobre cómo editar un sitio web de WordPress y nuestra selección experta de los mejores constructores de páginas de arrastrar y soltar para WordPress.

Si te gustó este artículo, suscríbete a nuestro canal de YouTube para obtener tutoriales en video de WordPress. También puedes encontrarnos en Twitter y Facebook.