# Add Mermaid Diagrams to a Hugo Docsy Site

Yes. An agent adds mermaid code fences to your Docsy pages, sets the plugin options once, builds the site the way CI does, checks the output, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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

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.

## 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.

## More Hugo jobs

- [Add Reading Time to a Hugo Blog](https://getrush.ai/run/add-reading-time/hugo/)
- [Add Related Posts to a Hugo Blog](https://getrush.ai/run/add-related-posts/hugo/)
- [Add Search to a Hugo Site](https://getrush.ai/run/add-search/hugo/)

## The same job on other stacks

- [Add Mermaid Diagrams to a Jekyll Blog on GitHub Pages](https://getrush.ai/run/add-mermaid-diagrams/jekyll/)
- [Add Mermaid Diagrams to an mdBook](https://getrush.ai/run/add-mermaid-diagrams/mdbook/)
- [Add Mermaid Diagrams to a MkDocs Site](https://getrush.ai/run/add-mermaid-diagrams/mkdocs/)

## 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/)
