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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.