# Add Social Cards to a Hugo Site

Yes. An agent draws a per-page Open Graph image at build time with Hugo's image functions, points the meta tags at it, builds the site in its sandbox and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-social-cards/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 how the site gets its preview image today. In a theme laid out like janraasch/hugo-bearblog, `layouts/partials/seo_tags.html` writes a title, description and keywords meta, then calls Hugo's internal `_internal/opengraph.html`, `_internal/twitter_cards.html` and `_internal/schema.html` templates. Those read a page's `images` parameter and fall back to the site's, which `exampleSite/hugo.toml` sets to `["images/share.png"]`, one static file under `exampleSite/static/images/`. So every post, the home page and every tag list share one card. `theme.toml` sets `min_version = "v0.110.0"`; `.github/workflows/ci.yml` builds the example site with `peaceiris/actions-hugo` at `hugo-version: latest` and `hugo --minify --gc --destination ../public --source ./exampleSite --themesDir ../..`, then publishes `./public` to GitHub Pages. The theme ships no JavaScript and no stylesheet files, and `package.json` runs `js-beautify layouts/**/*.html -r` as its only test.

Hugo can draw text on an image at build time with `images.Text`, so no external service and no headless browser are needed. The agent adds a background PNG under `assets/images/` and a partial, `layouts/partials/social_card.html`, that loads it with `resources.Get`, draws the page's title with `images.Text` using a size, colour and offsets that fit the card, and returns the generated resource; Hugo wraps a long title within the image width and writes the file under the site's output with a content hash in its name. The home page and the taxonomy lists keep the static `share.png` from the site params, since a card that says only the site title adds nothing.

The internal templates cannot be told about a generated resource, so the agent copies the Open Graph and Twitter card templates from Hugo's source into `layouts/partials/` and edits the image lines: `og:image` with its width and height from the resource, `twitter:image`, and `twitter:card` set to `summary_large_image` on pages that have a card. Everything else those templates emit, the type, the published and modified times, the site name, is kept as it was, and `seo_tags.html` calls the copied partials in place of the internal ones. `custom_head.html` stays empty, because it exists for a site's own additions and the theme would be overriding itself through its own hook.

In its sandbox the agent downloads a Hugo release, runs the exact build command from `ci.yml`, and reads `public/blog/markdown-syntax/index.html` and the other pages for the meta tags, confirms the generated PNG exists at the path they name, and checks that `--gc` leaves it in place. It runs `npm test` so the new layouts match the beautifier's formatting, and adds `resources/_gen/` to the repository's `.gitignore` beside `public/` and `.hugo_build.lock`, since that is where Hugo caches generated images.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add generated social cards to this Hugo site. Read the site configuration, theme.toml, every file under layouts/, .github/workflows/ci.yml, .gitignore and package.json first, and note which meta tags come from Hugo's internal opengraph and twitter_cards templates. Add a background image under assets/ and a partial that uses images.Text to draw each page's title on it at build time, with the generated resource's width and height. Copy the internal Open Graph and Twitter card templates into layouts/partials/, point their image tags at the generated card on pages that have one, set twitter:card to summary_large_image there, and keep the static site image for the home page and list pages. In the sandbox, install Hugo, run the same build command the CI workflow runs, verify the meta tags and the generated image in the output, run the repository's formatting check, and ignore Hugo's generated-resources cache in .gitignore. Open a pull request whose description quotes the meta tags of one post before and after and the path of its generated card.",
  "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 that adds a background image under `assets/images/`, the `social_card.html` partial and the two copied card templates under `layouts/partials/`, and changes `seo_tags.html` and `.gitignore`. The description quotes one post's `og:image` and `twitter:*` tags before and after, the output path of its generated card, and the `hugo` build summary from the sandbox, so a reviewer sees the build still completes with `--minify --gc`.

The run's record keeps the build output and the generated cards as artifacts, so a reviewer looks at the actual image a share would show rather than the template that draws it, and can judge the font size and wrapping on the longest title in the content.

Before merging, a reviewer checks the card against a long title and a short one, confirms the home page and tag pages still carry the static image, and decides whether the background should carry the site name or a logo, which is one edit to the PNG under `assets/`.

## Run it on every Hugo site

A team with several Hugo sites sends this body once per repository from a script, with the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. `GET /o/{org}/github` lists what the Rush GitHub App reaches; the script keeps the ones with a Hugo configuration file.

Each run reads its own theme. A site whose theme already emits its own `og:image` gets the generated card wired into that template instead of a copy of Hugo's; one whose posts carry a `cover` image gets the card only for posts without one; one that uses a Hugo module for its theme gets the partials in the site's own `layouts/`, which override the module's. The pull requests arrive one per site with the generated images in each record.

## Why run it on Rush?

Social cards are the kind of change that looks finished in a template and fails on the first share: the image path is relative, the width and height are missing so the crawler ignores it, the card is drawn but `twitter:card` still says `summary`, or the generated file is cleaned up by `--gc`. In a Rush sandbox the agent runs the real build command from the workflow, opens the output HTML and the generated PNG, and fixes what it sees before it opens anything.

The build log and the cards stay with the run, so the reviewer sees the image and the tags rather than reading template code and imagining the result. The same job across every Hugo site a team publishes runs in parallel, each in its own sandbox with its own Hugo download and its own pull request.

## Frequently asked questions

### Why not a service that renders cards from a URL?

Because the site already has a build step that can draw images. `images.Text` runs inside `hugo`, needs no API key, no network call at request time and no headless browser, and the output is a file in `public/` that is deployed with everything else. The card changes only when the title does.

### Why copy Hugo's internal templates?

The internal Open Graph and Twitter templates take their image from a page or site parameter, which cannot name a resource generated during the build. Hugo has no way to override part of an internal template, so the agent copies the two that matter into `layouts/partials/` and changes only their image lines. The copies are the theme's own from then on and should be updated when Hugo changes the originals.

### Does the site need Hugo extended?

No. `images.Text` is in every Hugo build. The extended edition is only needed for Sass, which this theme does not use.

### Will the home page and tag pages get a card?

They keep the static image the site already names in its params. A generated card for a list page would show only the site title, which the static image already does. A site that wants one per tag can extend the partial, and the agent says where.

### Does generating images slow the build down?

Each card is drawn once and cached under `resources/_gen/`, so later builds redraw only pages whose title changed. The pull request quotes the build time from the sandbox run for the example site so a reviewer can compare it with the workflow's usual time.

## More Hugo jobs

- [Add JSON-LD Structured Data to a Hugo Documentation Site](https://getrush.ai/run/add-structured-data/hugo/)
- [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/)

## The same job on other stacks

- [Add Social Preview Cards to a MkDocs Material Site](https://getrush.ai/run/add-social-cards/mkdocs/)
- [Add Social Cards to Sphinx Docs](https://getrush.ai/run/add-social-cards/sphinx/)
- [Add Social Cards to a VitePress Blog](https://getrush.ai/run/add-social-cards/vitepress/)

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