HubSpot acepta JSON-LD en tres lugares, y el correcto depende de lo que describe el marcado. Use «Head HTML» (HTML del encabezado) en una página o entrada cuando el marcado pertenezca solo a esa página. Use «Site Header HTML» (HTML del encabezado del sitio) para entidades de todo el sitio, como su organización. Use una plantilla HubL cuando cada entrada del blog deba llevar su propio título, URL, imagen y fechas.

Antes de agregar nada, abra una página publicada y una entrada publicada, y vea su código fuente. Su tema puede imprimir ya algo de JSON-LD, y una segunda descripción del mismo elemento deja duplicados que después tendrá que conciliar.

Puntos clave

  1. Tres rutasHubSpot documenta «Head HTML» para una página o entrada, «Site Header HTML» para el dominio y plantillas codificadas para el marcado de cada entrada.
  2. Haga coincidir alcance y entidadPonga la organización en «Site Header HTML» y las entidades propias de una página, como BlogPosting, en la página o en su plantilla.
  3. HubL completa cada entradaVariables como content.title y content.absolute_url imprimen los valores de cada entrada, y un valor faltante se omite.
  4. Revise el HTML publicadoInspeccione primero el código renderizado y luego use las herramientas de Schema.org, Google, Bing y Yandex para sus propias preguntas.
  5. Válido no garantizaPasar una revisión demuestra que el marcado se analiza. No promete un resultado enriquecido, mejor posicionamiento, tráfico ni una cita en IA.

Elija dónde va el JSON-LD en HubSpot

HubSpot documenta las opciones de código para el encabezado a nivel de una sola página, de una entrada de blog y de un dominio completo (documentación de fragmentos de código de HubSpot, actualizada por última vez en febrero de 2026). Esos niveles coinciden con los tres tipos de marcado que necesita la mayoría de los sitios. Las directrices generales de datos estructurados de Google recomiendan JSON-LD, así que las tres rutas siguientes lo usan.

  1. Una página o entrada. Abra «Content» (Contenido), luego «Website Pages» (Páginas del sitio web), «Landing Pages» (Páginas de destino) o «Blog», elija el elemento, y vaya a «Settings» (Configuración), después a «Advanced» (Avanzado) y luego a «Head HTML».
  2. Todo el sitio. Vaya a «Settings», luego a «Content», después a «Pages» (Páginas) y use «Site Header HTML».
  3. Cada entrada desde una misma plantilla. Coloque el script dentro del <head> de una plantilla HTML y HubL codificada.

Haga coincidir la ruta con la entidad. Los datos estables sobre la organización o el sitio web van en «Site Header HTML». Todo lo que describe una sola página, como un Article, BlogPosting, Product o Event, va en esa página o en la plantilla que la genera.

HubSpot indica que los permisos cambian según el alcance. El permiso «Edit and Publish» (Editar y publicar) cubre el contenido individual, mientras que el permiso «Website Settings» (Configuración del sitio web) cubre el código de todo el dominio. La documentación también indica que las opciones de encabezado y pie varían según la suscripción y el tipo de contenido, y que las entradas del blog admiten «Head HTML» pero no «Footer HTML» (HTML del pie). Los nombres de los menús cambian con el tiempo, así que compare lo que ve en su portal con la página de HubSpot antes de empezar.

Revise lo que ya muestra su tema

Lo que imprime un tema de HubSpot depende del propio tema, de la configuración del blog y de su suscripción. Lea su HTML publicado en lugar de suponerlo. Abra una página publicada y una entrada publicada, vea el código fuente y busque application/ld+json. Anote el @type de cada bloque y cualquier @id.

Una mujer con una chaqueta verde oliva señala con un bolígrafo un portátil mientras sostiene una hoja impresa con cajas unidas por flechas, en el escritorio de una agencia pequeña
Figura 1. Compare lo que ya muestra una página publicada con el marcado que planea agregar.

Si un bloque ya describe la misma organización o el mismo artículo, edítelo en su origen cuando sea posible, o agregue solo las propiedades que faltan y asígnelas un @id que coincida. Agregar un Organization o un BlogPosting completos por otra ruta crea dos descripciones en competencia de un mismo elemento. Los nodos duplicados solo son aceptables si los conecta a propósito con valores @id idénticos, que es el patrón que explica la guía sobre el grafo en JSON-LD.

La misma revisión le indica qué entidades puede omitir. Si el tema ya imprime una ruta de navegación correcta, no la toque. Si no imprime nada, tiene un hueco claro que cubrir con una de las rutas anteriores.

Agregue JSON-LD a una página o entrada con Head HTML

«Head HTML» conviene a una página cuyo marcado se escribe una vez y casi no cambia, como una página de destino única o una entrada que necesita su propia ruta de navegación. Abra el elemento en el editor, vaya a «Settings», luego a «Advanced», y pegue un elemento script completo en «Head HTML». Pegue las etiquetas junto con el JSON, porque el cuadro espera HTML y no un objeto suelto.

El ejemplo siguiente es un BreadcrumbList para una entrada ficticia. La documentación de Google sobre la ruta de navegación (actualizada en septiembre de 2026) exige itemListElement con al menos dos objetos ListItem, y cada elemento necesita un position y un name. Use item para la URL de cada paso. Reemplace los nombres y las URL por la ruta real que se muestra en la página, y mantenga el mismo orden que los enlaces visibles de la ruta de navegación.

html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "@id": "https://example.com/blog/example-post/#breadcrumb",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Blog",
      "item": "https://example.com/blog/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Entrada de ejemplo",
      "item": "https://example.com/blog/example-post/"
    }
  ]
}
</script>

Publique el elemento y revise después la URL en vivo, no la vista previa del editor. Para ver las propiedades con más detalle, la guía de schema de ruta de navegación y el generador de schema de ruta de navegación explican los detalles.

Agregue el marcado Organization para todo el sitio

Una organización es igual en todas las páginas, por lo que va en «Site Header HTML». Google indica que la función Organization no tiene propiedades obligatorias (documentación actualizada en septiembre de 2026). Agregue las que correspondan a su caso, como name, url, logo, sameAs, address, telephone, email y description, y omita cualquiera que no pueda afirmar con veracidad.

El ejemplo ficticio siguiente asigna a la organización un @id estable. Reemplace el nombre, las URL y el perfil de sameAs por los suyos, y mantenga el @id sin cambios en cada lugar donde haga referencia a la organización. El marcado de cada página puede entonces apuntar a él, así que no hace falta repetir el objeto completo en todas las páginas.

html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "Example Publishing",
  "url": "https://example.com/",
  "logo": {
    "@type": "ImageObject",
    "url": "https://example.com/images/example-logo.png"
  },
  "sameAs": [
    "https://www.example.org/example-publishing"
  ]
}
</script>

La documentación de HubSpot indica que el código de todo el dominio puede llegar a cada página del dominio que seleccione, por lo que debe dejar fuera de este cuadro las entidades propias de cada página. Si el tema ya imprime una organización en la página de inicio, actualice ese marcado en lugar de superponer este bloque. La guía de schema de Organization explica cada propiedad, y el generador de schema de Organization crea el objeto por usted. Si quiere saber si debe repetirse en todas las páginas, la guía sobre el marcado de Organization en varias páginas responde esa pregunta de forma directa.

Relacione cada propiedad de BlogPosting con la entrada

Schema.org define BlogPosting como un subtipo de Article. La documentación de Google sobre Article (actualizada en septiembre de 2026) admite Article, NewsArticle y BlogPosting, y no enumera propiedades obligatorias para esa función. Recomienda author, author.name, author.url, datePublished, dateModified, headline e image cuando correspondan.

«Recommended» (Recomendado) es la etiqueta de Google para su propia función de Búsqueda. No significa que Bing, Yandex, Apple o un sistema de IA lean los mismos campos de la misma manera, ni que una visualización esté garantizada. La tabla muestra cómo se alinean las propiedades comunes. La guía de schema de Article profundiza en autores y fechas.

Propiedades de BlogPosting y etiquetas de Article de Google

Pase el cursor o toque una fila para resaltarla. En pantallas pequeñas la tabla se desplaza de lado.

PropiedadSchema.orgFunción Article de Google
authorVálidoRecomendado
headlineVálidoRecomendado
imageVálidoRecomendado
datePublished y dateModifiedVálidoRecomendado
publisherVálidoOpcional para esta función de Google
description y mainEntityOfPageVálidoOpcional para esta función de Google

Cree la plantilla HubL para las entradas del blog

HubL es el lenguaje de plantillas de HubSpot, basado en Jinjava. Una plantilla codificada lo usa para imprimir valores guardados en la página o entrada actual. Las expresiones usan {{ ... }} y las instrucciones usan {% ... %} (documentación para desarrolladores de HubSpot). Así, una sola plantilla da a cada entrada su propio marcado sin tener que reescribir nada.

HubSpot documenta estas variables de contenido, y cada una corresponde a una propiedad de schema:

  • content.title se convierte en headline
  • content.meta_description se convierte en description
  • content.featured_image se convierte en image
  • content.absolute_url se convierte en url y en mainEntityOfPage.@id
  • content.publish_date se convierte en datePublished
  • content.updated se convierte en dateModified

Tres reglas mantienen válido el resultado renderizado. El resultado debe ser JSON válido, así que las comillas y los caracteres especiales de los títulos y las descripciones deben escaparse. Una propiedad sin valor debe omitirse, no imprimirse como cadena vacía. Y el marcado debe describir contenido visible en esa entrada.

La plantilla siguiente aplica esas reglas. Colóquela dentro del <head> de la plantilla de sus entradas del blog. Reemplace los valores de autor y editor por las personas u organización que aparecen en su firma, y mantenga el @id del editor igual al de su «Site Header HTML» para que ambos se conecten. Las líneas de description e image están dentro de condicionales if, así que una entrada sin ellas no imprime ninguna de las dos propiedades, y las propiedades posteriores siempre se imprimen, lo que mantiene válidas las comas.

html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "@id": "{{ content.absolute_url }}#blogposting",
  "url": "{{ content.absolute_url }}",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "{{ content.absolute_url }}"
  },
  "headline": "{{ content.title|escapejson }}",
  {% if content.meta_description %}
  "description": "{{ content.meta_description|escapejson }}",
  {% endif %}
  {% if content.featured_image %}
  "image": ["{{ content.featured_image }}"],
  {% endif %}
  "author": {
    "@type": "Organization",
    "@id": "https://example.com/#organization",
    "name": "Example Publishing"
  },
  "publisher": {
    "@type": "Organization",
    "@id": "https://example.com/#organization",
    "name": "Example Publishing"
  },
  "datePublished": "{{ content.publish_date|format_datetime("yyyy-MM-dd'T'HH:mm:ssXXX") }}",
  "dateModified": "{{ content.updated|format_datetime("yyyy-MM-dd'T'HH:mm:ssXXX") }}",
  "inLanguage": "en-US"
}
</script>

Para comparar, así se ve un BlogPosting terminado y fijo una vez completados los valores. Esta es la forma que la página renderizada debe mostrar en su código fuente.

json
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "@id": "https://example.com/blog/example-post/#blogposting",
  "url": "https://example.com/blog/example-post/",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://example.com/blog/example-post/"
  },
  "headline": "Una guía ficticia para organizar mejor un sitio web",
  "description": "Un ejemplo ficticio que explica cómo los propietarios de sitios web pueden organizar páginas relacionadas.",
  "image": [
    "https://example.com/images/example-post-1200x675.jpg"
  ],
  "author": {
    "@type": "Organization",
    "@id": "https://example.com/#organization",
    "name": "Example Publishing",
    "url": "https://example.com/about/"
  },
  "publisher": {
    "@type": "Organization",
    "@id": "https://example.com/#organization",
    "name": "Example Publishing",
    "url": "https://example.com/",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/images/example-logo.png"
    }
  },
  "datePublished": "2026-01-15T09:00:00-06:00",
  "dateModified": "2026-02-03T14:30:00-06:00",
  "articleSection": "Organización del sitio web",
  "inLanguage": "en-US"
}

Valide el HTML renderizado en el navegador, no el código fuente de la plantilla. La plantilla contiene etiquetas HubL que un validador no puede leer, y solo la página publicada muestra lo que recibe un rastreador. Revise con atención las dos líneas de fecha del resultado renderizado, porque el formato de fecha que imprime su cuenta debe leerse como fecha y hora completas. Si prefiere redactar primero el objeto y luego traducirlo a HubL, el generador de schema de Article crea la versión fija.

Revise el HTML publicado

Cada herramienta responde a una pregunta distinta, así que use más de una. Siga estos pasos en este orden.

  1. Vea el código fuente de la página o el DOM renderizado y confirme que el JSON-LD está dentro de <script type="application/ld+json">.
  2. Pase la URL por la Prueba de resultados enriquecidos (Rich Results Test) de Google para ver si cumple una función de Google compatible y para previsualizar esa función.
  3. Abra la herramienta «URL Inspection» (Inspección de URL) de Search Console para ver cómo lee Google la URL publicada. Google recomienda revisar el acceso de rastreo, noindex, robots.txt y las restricciones de inicio de sesión (documentación de Article).
  4. Pegue la URL en el Schema.org Validator para comprobar cómo se analiza el vocabulario, independientemente de cualquier función de Google.
  5. Use la tarjeta «Markup» (marcado) de la Inspección de URL en Bing Webmaster Tools para ver cómo Bing lee el JSON-LD, y lea la documentación de datos estructurados de Bing para conocer los formatos que acepta.
  6. Cuando el tráfico de Yandex importe, use el validador de datos estructurados de Yandex.

Un resultado válido no es lo mismo que un resultado elegible. Google indica que la elegibilidad depende de los requisitos de cada función, de sus directrices generales, de la accesibilidad de la página y de la calidad del contenido, y que el marcado válido no garantiza que una función aparezca. La guía de resultados enriquecidos y el validador de schema gratuito le ayudan a separar esos niveles.

Una tarjeta de entrada de blog con iconos de título, imagen, calendario y enlace alimenta una tarjeta de plantilla que produce una tarjeta de marcado, con un espacio vacío omitido
Figura 2. Una plantilla completa cada propiedad a partir de la entrada y omite cualquier valor que la entrada no tenga.

Siga la configuración en orden

Los pasos son los mismos en cada ruta, y solo cambia el lugar donde pega el código. El código de todo el dominio puede afectar a cada página alojada en HubSpot del dominio seleccionado, así que las entidades propias de una página suelen usar el alcance de página o de plantilla. La documentación de HubSpot también indica que las entradas del blog no tienen opción de «Footer HTML» (HTML del pie), por lo que el marcado a nivel de entrada va en «Head HTML» o en el encabezado de la plantilla.

Secuencia de configuración para un sitio de HubSpot

  1. Elija la rutaElija el tipo de página y luego «Head HTML» para un elemento, «Site Header HTML» para el dominio o una plantilla HubL.
  2. Escriba el JSON-LDSeleccione el tipo de Schema.org más específico y redacte un marcado completo con contenido visible en la página.
  3. Agregue y publiquePegue el elemento script o guarde la plantilla, y luego publique la página o la entrada.
  4. Inspeccione el HTML renderizadoVea el código fuente en vivo y confirme que el script aparece con JSON válido y sin duplicados.
  5. ValideEjecute el Schema.org Validator y las herramientas de Google, Bing o Yandex que correspondan a su público.
  6. Supervise los cambiosRevise de nuevo después de cambios en la plantilla o en el contenido, porque la nueva salida puede duplicar o romper el marcado.

Haga que el marcado sea legible para Bing y la búsqueda con IA

Bing documenta JSON-LD, Microdata, RDFa, Microformats y Open Graph, así que el JSON-LD que agregue en HubSpot también sirve a Bing. DuckDuckGo indica que sus enlaces tradicionales provienen en gran medida de Bing. Yandex documenta la compatibilidad con Schema.org y JSON-LD, y un validador de marcado semántico (documentación de JSON-LD de Yandex).

OpenAI recomienda permitir OAI-SearchBot y sus rangos de IP publicados si quiere que las páginas aparezcan en la búsqueda de ChatGPT (descripción general de rastreadores de OpenAI), y Perplexity documenta los controles de acceso de PerplexityBot y Perplexity-User. Revise robots.txt, las reglas del firewall y los registros de rastreo de los rastreadores que quiera que lleguen a la página, y consulte la guía sobre si los sistemas de IA usan el marcado schema.

Corrija la salida duplicada o rota

La mayoría de los problemas de schema en HubSpot provienen de una lista corta de causas. Búsquelas primero en el HTML renderizado.

Las entidades duplicadas aparecen cuando un tema y un bloque personalizado describen el mismo artículo u organización. Elimine uno o conéctelos con el mismo @id. El JSON mal formado suele deberse a una comilla sin escapar en un título o una descripción, por eso la plantilla de arriba imprime esos campos a través de escapejson. Un valor faltante que se imprime como cadena vacía, o una coma suelta después de una propiedad omitida, rompe el análisis de la misma manera.

El marcado que describe contenido que los visitantes no pueden ver no cumple las directrices de Google, y lo mismo ocurre con reseñas o calificaciones que usted no recopiló. Si una URL no aparece en la Prueba de resultados enriquecidos, revise las condiciones de acceso de Google: acceso de rastreo, noindex, robots.txt y requisitos de inicio de sesión. Después de editar una plantilla o una entrada, vuelva a publicarla y revise el código fuente en vivo, porque el archivo de la plantilla y la página que ven las personas pueden diferir hasta que se publique el cambio.

Vuelva a ejecutar la revisión después de cada cambio en la plantilla, en el tema o en el propio marcado, para detectar pronto un duplicado nuevo o un valor roto.

Preguntas frecuentes

¿HubSpot agrega schema Article automáticamente?

Depende de su tema, de la configuración del blog y de su suscripción, así que lea el código fuente de su propia página en lugar de suponer. Vea una entrada publicada y busque application/ld+json. Si ya hay un Article o un BlogPosting, actualice esa salida en lugar de agregar una segunda.

¿Puedo agregar marcado schema a una sola entrada del blog de HubSpot?

Sí. Abra la entrada, vaya a «Settings» (Configuración), luego a «Advanced» (Avanzado), y pegue el elemento script en «Head HTML». HubSpot documenta esta ruta para entradas individuales, y necesita el permiso «Edit and Publish» (Editar y publicar) para usarla.

¿El marcado Organization debe aparecer en todas las páginas?

La organización puede describirse una sola vez en «Site Header HTML». Las entidades a nivel de página la mencionan entonces con un @id estable, así que no hace falta repetir el objeto completo. Google no enumera propiedades obligatorias para su función Organization.

¿El marcado FAQPage sigue siendo una oportunidad de resultado enriquecido en Google?

No. Las actualizaciones de la documentación de Google indican que el resultado enriquecido de preguntas frecuentes dejó de aparecer en la Búsqueda de Google el 7 de mayo de 2026, y que la documentación sobre preguntas frecuentes se eliminó en junio de 2026. FAQPage sigue siendo un tipo válido de Schema.org, y cualquier marcado de preguntas frecuentes que agregue debe coincidir con las preguntas y respuestas visibles en la página.

¿El marcado schema garantiza citas en ChatGPT o Perplexity?

No. OpenAI indica que la aparición en la búsqueda de ChatGPT no está garantizada. El contenido preciso, el HTML rastreable y los rastreadores permitidos son las partes que usted controla.

Comprobación rápida

Elija una respuesta para ver comentarios. Nada se califica ni se guarda.

Pregunta 1 de 3

Un objeto BlogPosting supera el Schema.org Validator. ¿Qué demuestra eso?

Pregunta 2 de 3

¿Dónde debe ir el marcado de la propia organización en HubSpot?

Pregunta 3 de 3

Una entrada no tiene meta descripción. ¿Qué debe hacer la plantilla con description?

Glosario

Seleccione un término para ver su definición.

Vocabulario de Schema.org. Un conjunto compartido de tipos y propiedades para describir entidades y contenido.