HubSpot accepts JSON-LD in three places, and the right one depends on what the markup describes. Use the Head HTML box on a single page or post for markup that belongs to that page alone. Use Site Header HTML for entities that describe the whole site, such as your organization. Use a coded template with HubL when every blog post should carry its own title, URL, image and dates.

Before you add anything, open one published page and one published post and view their source. Your theme may already print some JSON-LD, and a second description of the same item leaves you with duplicates to reconcile.

Key takeaways

  1. Three routesHubSpot documents Head HTML for one page or post, Site Header HTML for the domain, and coded templates for per-post markup.
  2. Match scope to entityPut the organization in Site Header HTML and page-specific entities such as BlogPosting on the page or in its template.
  3. HubL fills each postVariables such as content.title and content.absolute_url print each post's own values, and a missing value is left out.
  4. Check the published HTMLInspect the rendered source first, then use Schema.org, Google, Bing and Yandex tools for their own questions.
  5. Valid is not guaranteedPassing a check shows the markup parses. It promises no rich result, ranking, traffic or AI citation.

Choose where the JSON-LD goes in HubSpot

HubSpot documents head-code options at the level of a single page, a blog post and a whole domain (HubSpot code snippets documentation, last updated February 2026). Those levels line up with the three kinds of markup most sites need. Google's general structured data guidelines recommend JSON-LD, so all three routes below use it.

  1. One page or post. Open Content, then Website Pages, Landing Pages or Blog, choose the item, and go to Settings, then Advanced, then Head HTML.
  2. The whole site. Go to Settings, then Content, then Pages, and use Site Header HTML.
  3. Every post from one template. Put the script inside the <head> of a coded HTML and HubL template.

Match the route to the entity. Stable facts about the organization or the website belong in Site Header HTML. Anything that describes one page, such as an Article, BlogPosting, Product or Event, belongs on that page or in the template that builds it.

HubSpot says permissions differ by scope. Edit and Publish permission covers individual content, while Website Settings permission covers domain-wide code. The documentation also says head and footer options vary by subscription and content type, and that blog posts support Head HTML but not Footer HTML. Menu labels change over time, so compare what you see in your portal with the HubSpot page before you start.

Check what your theme already outputs

What a HubSpot theme prints depends on the theme itself, the blog settings and your subscription. Read your own published HTML instead of assuming. Open one published page and one published post, view the page source, and search for application/ld+json. Note each block's @type and any @id.

A woman in an olive blazer points a pen at a laptop while holding a printed sheet of boxes joined by arrows at a desk in a small agency
Figure 1. Compare what a published page already outputs with the markup you plan to add.

If a block already describes the same organization or article, edit that source where you can, or add only the properties that are missing and give them a matching @id. Adding a second complete Organization or BlogPosting through another route creates two competing descriptions of one item. Duplicate nodes are acceptable only when you connect them on purpose with identical @id values, which is the pattern covered in the JSON-LD graph guide.

The same check tells you which entities you can skip. If the theme already prints a correct breadcrumb trail, leave it alone. If it prints nothing, you have a clear gap to fill with one of the routes above.

Add JSON-LD to one page or post with Head HTML

Head HTML suits a page whose markup is written once and rarely changes, such as a single landing page or one post that needs its own breadcrumb trail. Open the item in the editor, go to Settings, then Advanced, and paste a complete script element into Head HTML. Paste the tags as well as the JSON, because the box expects HTML rather than a bare object.

The example below is a BreadcrumbList for a fictional post. Google's breadcrumb documentation (updated September 2026) requires itemListElement with at least two ListItem objects, and each item needs a position and a name. Use item for the URL of each step. Replace the names and URLs with the real trail shown on the page, and keep the order the same as the visible breadcrumb links.

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": "Example Post",
      "item": "https://example.com/blog/example-post/"
    }
  ]
}
</script>

Publish the item, then check the live URL rather than the editor preview. For a deeper look at the properties, the breadcrumb schema guide and the breadcrumb generator cover the details.

Add site-wide Organization markup

An organization is the same on every page, so it belongs in Site Header HTML. Google says the Organization feature has no required properties (documentation updated September 2026). Add the ones that apply to you, such as name, url, logo, sameAs, address, telephone, email and description, and leave out any you cannot state truthfully.

The fictional example below gives the organization a stable @id. Replace the name, the URLs and the sameAs profile with your own, and keep the @id unchanged wherever you refer to the organization later. Page-level markup can then point at it, so there's no need to repeat the full object on every page.

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>

HubSpot's documentation notes that domain-wide code can reach every page on the domain you select, so keep page-specific entities out of this box. If the theme already prints an organization on the home page, update that markup rather than stacking this block on top. The Organization schema guide explains each property, and the Organization generator builds the object for you. If you want to know whether it should repeat on every page, the guide on Organization markup across pages answers that directly.

Match each BlogPosting property to the post

Schema.org defines BlogPosting as a subtype of Article. Google's Article documentation (updated September 2026) supports Article, NewsArticle and BlogPosting, and lists no required properties for the feature. It recommends author, author.name, author.url, datePublished, dateModified, headline and image where they apply.

"Recommended" here is Google's label for its own Search feature. It does not mean Bing, Yandex, Apple or an AI system reads the same fields the same way, and it does not mean a display is guaranteed. The table shows how the common properties line up. The Article schema guide goes further into authors and dates.

BlogPosting properties and Google's Article labels

Hover over or tap a row to highlight it. On small screens the table scrolls sideways.

PropertySchema.orgGoogle Article feature
authorValidRecommended
headlineValidRecommended
imageValidRecommended
datePublished and dateModifiedValidRecommended
publisherValidOptional for this Google feature
description and mainEntityOfPageValidOptional for this Google feature

Build the HubL template for blog posts

HubL is HubSpot's template language, based on Jinjava. A coded template uses it to print values stored on the current page or post. Expressions use {{ ... }} and statements use {% ... %} (HubSpot developer documentation). That is what lets one template give every post its own markup without retyping anything.

HubSpot documents these content variables, and each one maps to a schema property:

  • content.title becomes headline
  • content.meta_description becomes description
  • content.featured_image becomes image
  • content.absolute_url becomes url and mainEntityOfPage.@id
  • content.publish_date becomes datePublished
  • content.updated becomes dateModified

Three rules keep the rendered output valid. The result must be valid JSON, so quotation marks and special characters in titles and descriptions have to be escaped. A property with no value should be left out, not printed as an empty string. And the markup must describe content that is visible on that post.

The template below applies those rules. Place it inside the <head> of your blog post template. Replace the author and publisher values with the people or organization your byline shows, and keep the publisher @id the same as the one in your Site Header HTML so the two connect. The description and image lines sit inside if tests, so a post without them prints neither property, and the properties after them always print, which keeps the commas valid.

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>

For comparison, here is what a finished, fixed BlogPosting looks like once the values are filled in. This is the shape the rendered page should show in its source.

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": "A Fictional Guide to Better Website Organization",
  "description": "A fictional example explaining how website owners can organize related pages.",
  "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": "Website Organization",
  "inLanguage": "en-US"
}

Validate the browser-rendered HTML, not the template source. The template contains HubL tags that a validator cannot read, and only the published page shows what a crawler receives. Look closely at the two date lines in the rendered output, because the date format your account prints needs to read as a full date and time. If you would rather draft the object first and then translate it into HubL, the Article schema generator builds the fixed version.

Check the published HTML

Each tool answers a different question, so run more than one. Work through them in this order.

  1. View the page source or rendered DOM and confirm the JSON-LD sits inside <script type="application/ld+json">.
  2. Run the URL through Google's Rich Results Test to see whether it meets a supported Google feature and to preview that feature.
  3. Open Search Console's URL Inspection tool to see how Google reads the published URL. Google recommends checking crawl access, noindex, robots.txt and login restrictions (Article documentation).
  4. Paste the URL into the Schema.org Validator to check how the vocabulary parses, apart from any Google feature.
  5. Use the Markup card in Bing Webmaster Tools' URL Inspection to see how Bing reads the JSON-LD, and read Bing's structured data documentation for the formats it accepts.
  6. Where Yandex traffic matters, use the Yandex structured data validator.

A valid result is not the same as an eligible one. Google says eligibility depends on the feature's own requirements, its general guidelines, page accessibility and content quality, and that valid markup does not guarantee a feature will appear. The rich results guide and the free Schema Validator help you separate those levels.

A blog post card with title, image, calendar and link icons feeding a template card that produces a markup card, with one empty slot skipped
Figure 2. A template fills each property from the post and leaves out any value the post does not have.

Run the setup in order

The steps are the same for each route, and only the place you paste the code changes. Domain-wide code can affect every HubSpot-hosted page on the selected domain, so page-specific entities generally use page or template scope. HubSpot's documentation also says blog posts have no Footer HTML option, so Head HTML or the template's head is where post-level markup goes.

Setup sequence for a HubSpot site

  1. Choose the routePick the page type, then Head HTML for one item, Site Header HTML for the domain, or a HubL template.
  2. Write the JSON-LDSelect the most specific Schema.org type and build complete markup from content visible on the page.
  3. Add and publishPaste the script element or save the template, then publish the page or post.
  4. Inspect the rendered HTMLView the live source and confirm the script appears with valid JSON and no duplicates.
  5. ValidateRun the Schema.org Validator and the Google, Bing or Yandex tools that match your audience.
  6. Monitor changesCheck again after template or content changes, because new output can duplicate or break the markup.

Bing documents JSON-LD, Microdata, RDFa, Microformats and Open Graph, so the JSON-LD you add in HubSpot serves Bing too. DuckDuckGo says its traditional links come largely from Bing. Yandex documents Schema.org and JSON-LD support and a semantic markup validator (Yandex JSON-LD documentation).

OpenAI recommends allowing OAI-SearchBot and its published IP ranges if you want pages to appear in ChatGPT search (OpenAI crawler overview), and Perplexity documents PerplexityBot and Perplexity-User access controls. Check robots.txt, firewall rules and crawl logs for the crawlers you want to reach the page, and see whether AI systems use schema markup.

Fix duplicate or broken output

Most HubSpot schema problems come from a short list of causes. Look for them in the rendered HTML first.

Duplicate entities appear when a theme and a custom block both describe the same article or organization. Remove one, or connect them with the same @id. Malformed JSON usually comes from an unescaped quotation mark in a title or description, which is why the template above prints those fields through escapejson. A missing value that prints as an empty string, or a stray comma after an omitted property, breaks parsing in the same way.

Markup that describes content visitors cannot see does not meet Google's guidelines, and the same holds for reviews or ratings you did not collect. If a URL does not appear in the Rich Results Test, check Google's access conditions: crawl access, noindex, robots.txt and login requirements. After editing a template or a post, republish it and look at the live source again, because the template file and the page people reach can differ until the change is published.

Run the check again after every template change, theme change or edit to the markup itself, so a new duplicate or a broken value shows up early.

Questions people ask

Does HubSpot add Article schema automatically?

It depends on your theme, blog settings and subscription, so read your own page source instead of guessing. View one published post and search for application/ld+json. If an Article or BlogPosting is already there, update that output rather than adding a second one.

Can I add schema markup to one HubSpot blog post only?

Yes. Open the post, go to Settings, then Advanced, and paste the script element into Head HTML. HubSpot documents this route for individual posts, and you need Edit and Publish permission to use it.

Should Organization markup appear on every page?

The organization itself can be described once in Site Header HTML. Page-level entities then refer to it with a stable @id, so there is no need to repeat the whole object. Google lists no required properties for its Organization feature.

Is FAQPage markup still a Google rich-result opportunity?

No. Google's documentation updates say the FAQ rich result stopped appearing in Google Search on May 7, 2026, and the FAQ documentation was removed in June 2026. FAQPage remains a valid Schema.org type, and any FAQ markup you add should match visible questions and answers on the page.

Does schema markup guarantee ChatGPT or Perplexity citations?

No. OpenAI says placement in ChatGPT search is not guaranteed. Accurate content, crawlable HTML and allowed crawlers are the parts you control.

Quick check

Choose an answer to see feedback. Nothing is scored or saved.

Question 1 of 3

A BlogPosting object passes the Schema.org Validator. What does that show?

Question 2 of 3

Where does markup for the organization itself belong in HubSpot?

Question 3 of 3

A post has no meta description. What should the template do with description?

Glossary

Select a term to see its definition.

Schema.org vocabulary. A shared set of types and properties for describing entities and content.