Updated 2026-11-15
Hugo JSON-LD: add structured data with a partial
Hugo doesn't write JSON-LD. Its embedded schema.html template writes schema.org microdata (<meta itemprop> tags), and Google recommends JSON-LD for structured data (Google Search Central: structured data). On a Hugo site, JSON-LD is one partial in your <head> that builds the data from front matter and site config. This guide gives a working partial for posts, breadcrumbs and the home page, and shows how to check the build. Which types fit which pages is covered in JSON-LD for Astro and Docusaurus; the data is the same in Hugo.
1. Escaping: build a dict, then jsonify
Don't type JSON by hand around template variables: a title with a quote breaks the block, and Google ignores a block it can't parse. Build the data as a dict and serialize it once:
<script type="application/ld+json">{{ $data | jsonify | safeJS }}</script>
jsonify escapes <, > and & as <, > and &, so a title containing </script> can't end the tag early, and the output stays valid JSON. safeJS stops Hugo's template engine from wrapping the result in quotes as a JavaScript string.
2. A partial for every page
Save this as layouts/_partials/json-ld.html (on Hugo before 0.146, layouts/partials/json-ld.html) and call it from your base template's head with {{ partial "json-ld.html" . }}:
{{- $graph := slice }}
{{- /* Home page: who publishes the site */}}
{{- if .IsHome }}
{{- $graph = $graph | append (dict
"@type" "WebSite"
"name" site.Title
"url" site.Home.Permalink
) }}
{{- end }}
{{- /* Posts: an article with dates, description and image */}}
{{- if and .IsPage (eq .Section "posts") }}
{{- $post := dict
"@type" "BlogPosting"
"headline" .Title
"datePublished" (.PublishDate.Format "2006-01-02T15:04:05Z07:00")
"dateModified" (.Lastmod.Format "2006-01-02T15:04:05Z07:00")
"mainEntityOfPage" .Permalink
}}
{{- with .Description }}{{ $post = merge $post (dict "description" .) }}{{ end }}
{{- with .Params.author }}{{ $post = merge $post (dict "author" (dict "@type" "Person" "name" .)) }}{{ end }}
{{- with .Params.images }}{{ $post = merge $post (dict "image" (index . 0 | absURL)) }}{{ end }}
{{- $graph = $graph | append $post }}
{{- end }}
{{- /* Every page below the home page: a breadcrumb trail */}}
{{- if not .IsHome }}
{{- $items := slice }}
{{- range $i, $p := .Ancestors.Reverse | append . }}
{{- $item := dict "@type" "ListItem" "position" (add $i 1) "name" $p.LinkTitle }}
{{- if not ($p.Eq $) }}{{ $item = merge $item (dict "item" $p.Permalink) }}{{ end }}
{{- $items = $items | append $item }}
{{- end }}
{{- $graph = $graph | append (dict "@type" "BreadcrumbList" "itemListElement" $items) }}
{{- end }}
{{- with $graph }}
<script type="application/ld+json">{{ dict "@context" "https://schema.org" "@graph" . | jsonify | safeJS }}</script>
{{- end }}
Notes on what it does:
- One block with
@graphholds every type for the page, so there's a single place to check and no duplicates from two partials. - Dates are full ISO 8601 with a time zone.
.Lastmodfalls back to the publish date unless you setlastmodorenableGitInfo. - Breadcrumbs come from
.Ancestors(Hugo 0.109 and later), outermost first; the home page is the first item. The last item, the page itself, leaves outitem, which Google accepts. Change"posts"to your blog's section name. - Optional fields (description, author, image) are only added when the front matter has them, so a post never claims an empty author.
- URLs are absolute because
.PermalinkandabsURLbuild them frombaseURL. IfbaseURLis stillhttp://example.org/or/, every URL in the block is wrong; the Hugo SEO guide covers that setting.
3. The embedded schema template
If your theme calls {{ partial "schema.html" . }} (or _internal/schema.html in older themes), it keeps writing microdata next to your JSON-LD. Search engines read both, so that's harmless, but you don't need both. Check whether your theme already emits JSON-LD before adding the partial: search the theme's layouts folder for ld+json. Two BlogPosting blocks for the same page with different headlines only add noise.
4. Check the build
List built pages with no JSON-LD at all:
hugo --gc --minify && grep -rL --include='*.html' 'application/ld+json' public
Then check a few pages of each template. The free structured data checker takes a URL or pasted markup and checks each block against the properties Google requires and recommends. Google's Rich Results Test shows which rich results a page qualifies for. The free site checker samples pages across a live site and shows which have no structured data, no description or no share image.
Common mistakes
- Hand-written JSON around
{{ .Title }}. A quote or a trailing comma makes the whole block invalid. Usedictandjsonify. - Missing
safeJS. Without it the output is one quoted string, not an object, and the block means nothing. - Dates like
.Date.Format "January 2, 2006". Use ISO 8601 with a time zone. - Front matter
imagesas relative paths withoutabsURL. - Markup for content that isn't on the page. Authors, ratings and prices must also be visible.
Automating it with Headlark
A partial covers the templates you write it for. On a site with hundreds of different pages, Headlark's build step runs after hugo and writes what each page is missing from its content: one to three JSON-LD blocks with only properties whose values appear on the page, plus missing descriptions, Open Graph tags and alt text. A type you already emit is kept as it is and never added twice, so it works alongside the partial above.
Try it
Try it free for 14 days on one site and up to 500 pages, no card needed. Add your site, copy its secret key, and your next build ships with SEO.