How to add schema markup to a HubSpot site

What schema markup does

Schema markup is structured data, written in the vocabulary from schema.org, that describes a page in a form machines can read without guessing. A person can see that a page is about your company’s SEO service, priced from a certain amount, offered in Finland and Spain. Structured data says the same thing explicitly.

Google uses it for rich results, such as breadcrumbs, review stars and product details in search, and to understand the page. AI assistants benefit from the same clarity when they decide what a page says and whether to quote it.

The markup most HubSpot sites need

Use JSON-LD, a small script block in the page’s head. It’s the format Google recommends, and it keeps the markup separate from the design.

Option 1: Site-wide head HTML

HubSpot’s website settings have a site header HTML field that’s added to every page. It’s the right place for markup that never changes between pages, which in practice is your Organization block.

Don’t put page-specific markup here. A Service block added site-wide would claim that every page, including your blog posts, is that service.

Option 2: Per page, in the page settings

Every HubSpot page has a head HTML field in its advanced settings. You can paste a JSON-LD block there for that page only. It works, and it’s fine for a handful of pages, but it has a weakness: when someone edits the page text, the markup doesn’t change with it. Six months later the page says one price and the markup another.

Option 3: Generated by the theme (recommended)

The most reliable approach is to let the templates and modules write the markup from the same fields that render the page. An FAQ module outputs its questions as visible text and as FAQPage markup at the same time. A blog post template builds BlogPosting markup from the post’s title, author and dates. A breadcrumb module outputs BreadcrumbList from the same links it shows.

The markup can’t drift from the content, because they come from the same place, and editors don’t need to know any JSON. This is how our AEO First theme works, and it’s how we build schema into custom themes. There’s more on that in building modules marketers can’t break.

What changed with FAQ and how-to results

In 2023, Google limited FAQ rich results to well-known, authoritative government and health sites, and stopped showing how-to rich results. That doesn’t make the markup useless: it still describes your content precisely, for Google and for AI assistants. Just don’t add it expecting the expandable questions under your search result.

How to test it

1. Run the live page through Google’s Rich Results Test. It shows which markup Google found and whether it qualifies for rich results.
2. Use the Schema Markup Validator at validator.schema.org for types Google doesn’t show as rich results.
3. Check Google Search Console’s enhancement reports after a few weeks for errors across the whole site.

And one rule above all: only mark up what the page actually shows. Markup describing reviews, prices or questions that aren’t on the page breaks Google’s guidelines.