# Add JSON-LD Structured Data to a Hugo Documentation Site

Yes. An agent adds a head hook that emits JSON-LD for your docs pages, posts and home page from front matter and Git dates, checks the built output and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-structured-data/hugo/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with what the theme already puts in `<head>`, because adding structured data twice is worse than once. In a site made from docsy/docsy-example, the theme is the `github.com/docsy/docsy/theme` Hugo module named in `go.mod`, the site's own `layouts/` holds only a heading render hook and a redirects template, and `hugo.yaml` sets `enableGitInfo: true`, three languages with Persian right-to-left, a `blog` permalink pattern with the date in the path, and `github_repo`, `copyright.authors` and `version` under `params`. The theme's head partial calls Hugo's embedded `opengraph.html`, `schema.html` and `twitter_cards.html`, and ends with a `hooks/head-end.html` partial the theme ships empty for a site to override. The agent confirms this by building the site and reading the head of `public/docs/getting-started/example-page/index.html`: `schema.html` writes `meta` tags with `itemprop` attributes, the microdata form, and there is no `application/ld+json` script.

Then it reads the content it will describe. `content/en/docs/getting-started/example-page.md` has `title`, `date`, `description`, `categories` and `tags`; the blog posts under `content/en/blog/news/` and `releases/` have `date`, `title` and `description`, and `first-post/index.md` is a page bundle whose `author` is a Markdown link and whose `resources` rule gives the featured JPEG a byline. With `enableGitInfo` on, every page's `.Lastmod` comes from the commit that last touched it, which is what Docsy's own `page-meta-lastmod.html` partial shows at the foot of a docs page.

The change is one file, `layouts/_partials/hooks/head-end.html`, which overrides the theme's empty hook. It builds a map per page kind and writes it with `jsonify`: a `WebSite` with the site title and permalink on the home page; a `BlogPosting` on a blog page with `headline`, `datePublished` from `.Date`, `dateModified` from `.Lastmod`, the author's name taken from the Markdown link with `markdownify` and `plainify`, the bundle's featured image as `image`, `inLanguage` from the page's language, and a `publisher` named from the site title; a `TechArticle` on a docs page with the same dates and the `description`; and a `BreadcrumbList` built from `.Ancestors` on every page below the home page. It emits nothing for the `print` output format, which the theme already marks `noindex`, and the Markdown and `LLMS` output formats never render the head at all, so they are untouched.

In its sandbox the agent runs `npm ci`, which `package.json` allows to install `hugo-extended` 0.166.0 through its `allowScripts` entry, and `npm run build`, then extracts every `ld+json` block from `public/` with a short Node script, parses each as JSON and checks the `@type` and the dates against the page's front matter and its Git commit. It adds `tests/structured-data.test.mjs` in the style of the site's existing `node --test` files, asserting a `BlogPosting` on the first post, a `TechArticle` on the example page and a `WebSite` on the home page, so `npm run test:site` keeps the hook honest, and runs `npm run fix:format` as `ci:test` does so Prettier leaves nothing to change.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add JSON-LD structured data to this Hugo site. Read hugo.yaml, go.mod, package.json, every file under layouts and tests, the docs and blog front matter under content/en, and .github/workflows/links.yaml first, then build the site and read the head of a rendered docs page to see what the theme already emits. Write layouts/_partials/hooks/head-end.html so that the home page gets a WebSite object, blog pages a BlogPosting with datePublished from the page date, dateModified from Lastmod, the author's plain name, the featured image and the language, docs pages a TechArticle, and every page below home a BreadcrumbList from its ancestors; emit nothing for the print output format. Build with npm run build, extract every ld+json block from public, parse each and compare its dates with the front matter and git history, add a node test under tests in the existing style that checks the three page kinds, and run the formatter the way ci:test does. Open a pull request whose description quotes the extracted objects for one docs page and one post.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request with one new partial under `layouts/_partials/hooks/`, one new test under `tests/`, and no change to `hugo.yaml`, the theme module or any content file. The description quotes the JSON-LD extracted from the example docs page and from the first blog post, so the reviewer reads the actual objects with their dates, author and image, and shows the `node --test` run passing.

The run's record keeps the Hugo build output, the extraction script's results for every rendered page, and the formatter run, so a reviewer can see each object parsed and each date matched its source before checking out the branch.

Before merging, a reviewer checks the publisher name and the author form, decides whether the Norwegian and Persian pages should carry their own `inLanguage` as written or be left out until their content is real, and notes that `links.yaml` checks out without full history, so `dateModified` in that build is the checkout commit's date; the production build on the site's host clones with history, and the pull request says so.

## Run it on every documentation site in the org

A team with several Hugo sites starts one run per repository from a script: `GET /o/{org}/github` lists every repository the installation reaches, the script keeps the ones with a `hugo.yaml` or `hugo.toml`, and sends this body with that repository in `resources` only where the built site has no `ld+json` block. Each call carries a `request_id` that is a UUID v5 of the repository's full name, so running the script twice returns the runs already started.

Each run reads its own site. One on a theme that already emits JSON-LD gets a report and no partial; one with `enableGitInfo` off gets `dateModified` from front matter instead of Git; one with a single language drops the `inLanguage` logic. The pull requests arrive one per site, each with its extracted objects in the record.

## Why run it on Rush?

Structured data added without building the site goes wrong silently: a second `BlogPosting` beside the one the theme already emits, a `dateModified` that is the deploy time because the build had no Git history, an author field holding Markdown link syntax, or a script tag rendered into the print view. In a Rush sandbox the agent builds the real site with the pinned Hugo, extracts every block it emitted and checks each against the front matter and the commit log before it opens anything.

The extracted objects stay with the run and the pull request quotes them, so the reviewer reads what a crawler will read. The same job across every site a team runs happens in parallel, each with its own machine, its own build and its own pull request.

## Frequently asked questions

### Doesn't Docsy already add structured data?

It calls Hugo's embedded `schema.html`, which writes `meta` tags with `itemprop` attributes, the microdata form. Google's documentation asks for JSON-LD, and the two can coexist on a page. The agent reads the built head first and adds the JSON-LD through the `head-end` hook the theme leaves empty for exactly this.

### Where does dateModified come from?

From `.Lastmod`, which with `enableGitInfo: true` is the date of the last commit that touched the page, the same source Docsy's own last-modified footer uses. A build from a shallow checkout gets the checkout commit's date, so the pull request notes which builds have full history.

### Does it handle the Norwegian and Persian pages?

Yes. The hook runs once per language and uses each page's own permalink and language code, so the Persian page carries `fa` and its own URL. The reviewer decides whether placeholder translations should be described at all.

### Will it break the Markdown or llms.txt output formats?

No. Those formats render their own templates without the head partial, and the hook also checks the output format so the `print` view, which the theme marks `noindex`, gets no script.

### How do I check what Google reads?

The pull request quotes the JSON-LD for two pages, and the new `node --test` file checks the three page kinds on every `npm run test:site`. Once deployed, the Rich Results Test on a page URL shows the same objects.

## More Hugo jobs

- [Add a Table of Contents to a Hugo Blog](https://getrush.ai/run/add-table-of-contents/hugo/)
- [Add a Typo Check to a Hugo Site](https://getrush.ai/run/add-typo-check/hugo/)
- [Add a Version Menu to a Hugo Docsy Site](https://getrush.ai/run/add-versioned-docs/hugo/)

## The same job on other stacks

- [Add JSON-LD Structured Data to a Jekyll Site](https://getrush.ai/run/add-structured-data/jekyll/)
- [Add Structured Data (JSON-LD) to a Nuxt App](https://getrush.ai/run/add-structured-data/nuxt/)
- [Add Structured Data to a Pelican Blog](https://getrush.ai/run/add-structured-data/pelican/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
