What the agent does
The agent reads how the site is built before touching content. In a site laid out like docsy/docsy-example, the site configuration is hugo.yaml, not config.yaml, which holds only the module.hugoVersion floor of 0.160.1; go.mod imports github.com/docsy/docsy/theme at v0.18.1 as a Hugo module, and package.json pins hugo-extended 0.166.0 under Node 24 with scripts for build, check:links, test:site and fix:format. hugo.yaml already sets markup.goldmark.renderer.unsafe: true, three languages under content/en, content/no and content/fa, and params.docsy is absent, so the theme's plugin defaults apply. .github/workflows/links.yaml builds the site, runs lychee against it, and fails if generated files drift. The content under content/en/docs/ is the Goldydocs sample: overview.md, concepts.md, a tasks section with the Ponycopters pages, tutorials and a reference section.
Docsy 0.18 ships Mermaid as a plugin that is on by default. The theme's own hugo.yaml sets params.docsy.plugins.mermaid to { enable: true, version: 11.17.2 }, and layouts/_markup/render-codeblock-mermaid.html turns any fenced block whose language is mermaid into a <pre class="mermaid"> and sets a hasmermaid flag in the page store. The script partial only emits the loader on pages where that flag is set, importing https://cdn.jsdelivr.net/npm/mermaid@<version>/dist/mermaid.esm.min.mjs in the browser. There is no switch to flip: a page with a mermaid fence renders a diagram, and a page without one loads nothing. The pre-0.18 params.mermaid key is refused with a build error, which the agent checks for in hugo.yaml so an older snippet copied from a blog post does not break the build.
The diagrams are written where the prose already describes a flow. The agent adds a flowchart to content/en/docs/overview.md showing how a Goldydocs site is built from Hugo, the Docsy module and npm, and a sequence diagram to content/en/docs/concepts.md, keeping each definition short enough to read in the source. Site-wide settings go in hugo.yaml as the options entry on the plugin, which must be a JSON object string because Hugo lowercases map keys and Mermaid's option names are case-sensitive: params.docsy.plugins.mermaid.options: '{"theme": "neutral"}'. Docsy sets startOnLoad itself and switches to Mermaid's dark theme on dark pages, so the agent does not set either. The Norwegian and Persian trees are left alone, because their pages are translations maintained separately.
The proof is the build. The theme's partial validates the pinned Mermaid version against the CDN at build time with resources.GetRemote, so npm run build needs network access and fails loudly on a bad pin; the agent runs it in the sandbox, confirms public/docs/overview/index.html contains a <pre class="mermaid"> and the plugin's JSON config block, and confirms a page without a diagram carries neither. It then runs npm run fix:format, since the repository's Prettier settings wrap prose and links.yaml fails on drift, and npm run test:site. .cspell.yml may flag diagram node labels; the agent adds only real words to the ignore list and rewrites labels otherwise.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Mermaid diagrams to this Hugo site built with Docsy. Read hugo.yaml, config.yaml, go.mod, package.json, .nvmrc, .github/workflows/links.yaml, .cspell.yml and the pages under content/en/docs first, and check go.mod for the Docsy version so you use that version's plugin configuration. Add a flowchart to content/en/docs/overview.md and a sequence diagram to content/en/docs/concepts.md as mermaid code fences, each describing a flow the page already explains in prose. Set params.docsy.plugins.mermaid.options in hugo.yaml to a JSON object string with the neutral theme and nothing else. Do not add a params.mermaid key. Run npm ci, npm run build, npm run fix:format and npm run test:site; confirm the built overview page contains a pre element with the mermaid class and the plugin config block and that a page without a diagram contains neither. Open a pull request that quotes the build output and lists each page changed.",
"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
The pull request changes hugo.yaml (one params.docsy.plugins.mermaid.options entry), content/en/docs/overview.md and content/en/docs/concepts.md, and, if a label needed it, .cspell.yml. Its description quotes the hugo build output, names the Docsy version read from go.mod, and shows the two fenced definitions next to a one-line description of what each renders, so a reviewer can read the diagram without running the site.
A reviewer checks that each diagram says what the surrounding paragraph says, that the options value is a JSON string rather than a YAML map, and that no page outside content/en was touched. They may prefer the default theme over neutral, which is a one-word change in hugo.yaml.
After merge, the pages render the diagrams in the browser at the pinned Mermaid version, follow the site's light and dark toggle, and the link checker and drift check in links.yaml keep passing because the generated files did not change.
Run it on every pull request that adds a documentation page
An automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize reads each new page under content/en/docs/ for a numbered list of steps or a paragraph that describes components calling each other. An automation's run is read-only, so it posts a review comment with a mermaid fence the author can paste, rather than pushing to the branch. The contributor keeps control of the prose.
An organisation with several Docsy sites starts one run per site from a handler on its own server, sending this body to POST /o/{org}/sessions with the repository in resources and a request_id that is a UUID v5 of the repository name, so a retried loop returns the run it already started. Each run reads its own go.mod, because a site still on a Docsy release before 0.18 configures Mermaid differently.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The configuration surface moved between Docsy releases, and the plugin validates its CDN pin at build time, so the only honest check is a full hugo build with network access on the Node and Hugo versions the repository pins. The agent does that in its own sandbox, installs from package-lock.json, and keeps the build output with the pull request.
Diagrams are prose work as much as markup work. An agent that reads the page it is illustrating writes a diagram that matches the text, and a reviewer who sees the definition beside the paragraph in the pull request can judge both at once instead of opening a preview deploy.
Frequently asked questions
Do I need to enable anything in hugo.yaml?
Not on Docsy 0.18. The theme enables the Mermaid plugin by default and renders any mermaid code fence; the loader is only emitted on pages that contain one. The agent adds an options entry only to set the theme, and refuses to add the old params.mermaid key, which fails the build on 0.18.
Why is the options value a string and not YAML?
Hugo lowercases the keys of configuration maps, and Mermaid's option names are case-sensitive, so Docsy takes the options as a JSON object string and decodes it itself. A value that is not a JSON object fails the build, which the agent's build step would catch.
Does the build need the internet?
Yes. The theme fetches the pinned Mermaid script from jsDelivr during the build to validate the version, and the browser loads it from the same URL at run time. The sandbox has network access, so npm run build in the run is the same build CI performs.
What about dark mode?
Docsy's plugin script sets Mermaid's dark theme when the page is in dark mode and reloads the page when the toggle changes, because Mermaid cannot be re-initialised. The agent leaves that alone; only the light theme comes from the options entry.