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:

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

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.