# Add Open Graph Tags to Sphinx Docs

Yes. An agent adds sphinxext-opengraph to your Sphinx docs so every page carries og:title, og:description, og:url and an image, builds to check, and opens a PR.

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

## What the agent does

The agent reads what the docs already put in `<head>` and how they are built, because the right values depend on the theme, the builder and the host. In a project laid out like psf/requests, `docs/conf.py` enables `sphinx.ext.autodoc`, `intersphinx`, `todo` and `viewcode`, uses the `alabaster` theme with `github_user`, `github_repo` and `github_banner` set, takes `version` and `release` from `requests.__version__`, serves `docs/_static/custom.css` and a `requests-sidebar.png` that `docs/_templates/sidebar.html` places as the logo, and sets no `html_logo`, no `html_baseurl` and nothing that writes an `og:` meta. `.readthedocs.yaml` builds with the `dirhtml` builder on Ubuntu 22.04 and Python 3.12, installs the package and `docs/requirements.txt`, which pins `Sphinx==7.2.6` beside the test tools, and also produces PDF and EPUB. The root `Makefile` has a `docs` target that runs `cd docs && make html`, and `.pre-commit-config.yaml` excludes `docs/` from its hooks.

Then it reads the extension. `sphinxext-opengraph` is one line in `extensions`, `sphinxext.opengraph`, and a handful of settings: `ogp_site_url` for the public address, which it reads from `READTHEDOCS_CANONICAL_URL` on Read the Docs so a local build and the hosted one agree; `ogp_image` for the picture a share card shows, resolved against the site URL when relative; `ogp_site_name` defaulting to `project`; `ogp_description_length` at 200 characters taken from the page; `ogp_enable_meta_description` on by default, which also adds a plain `<meta name="description">` the docs lack today; `ogp_type` at `website`; and `ogp_social_cards`, which generates a PNG per page through matplotlib when the `social_cards` extra is installed, using `html_logo` as the picture unless `image` names another.

The agent writes the config for this site: `sphinxext.opengraph` in `extensions`, `ogp_site_url` set to the Read the Docs address with a note that the environment variable overrides it there, `ogp_image` pointing at `_static/requests-sidebar.png`, since that is the only logo the project has and `html_logo` is unset, `ogp_site_name` left to `project`, and `ogp_custom_meta_tags` carrying a `twitter:card` of `summary` so the card reads the same tags. It pins `sphinxext-opengraph` in `docs/requirements.txt` next to Sphinx 7.2.6 at a version that supports it, and leaves social cards off with a comment on how to turn them on, because they add matplotlib and a font to the Read the Docs build and the pull request should not change its duration without a decision.

To check the result the agent builds the docs twice in its sandbox with the same commands the hosts use: `sphinx-build -b dirhtml docs docs/_build/dirhtml`, since `dirhtml` turns `user/quickstart.rst` into `user/quickstart/index.html` and `og:url` must end in the directory form, and `make html` from the root target. It greps the built pages for `og:title`, `og:url` and `og:description`, reads the description the extension took from the quickstart page to see that it is the first paragraph and not a directive, and confirms the PDF and EPUB builders are untouched by an HTML-only extension.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Open Graph meta tags to this project's Sphinx documentation. Read docs/conf.py, docs/requirements.txt, .readthedocs.yaml, docs/_templates/sidebar.html, docs/index.rst, docs/user/quickstart.rst, the root Makefile and docs/Makefile first. Add sphinxext.opengraph to extensions in docs/conf.py with ogp_site_url set to the Read the Docs address, ogp_image pointing at the sidebar logo in docs/_static, and a twitter:card meta through ogp_custom_meta_tags; leave social cards off with a comment on how to enable them. Pin sphinxext-opengraph in docs/requirements.txt at a version compatible with the pinned Sphinx. Build with sphinx-build -b dirhtml and with make html in your sandbox, grep the output for og:title, og:url and og:description on the index, quickstart and api pages, check the og:url values use the dirhtml directory form, and open a pull request with the head of one built page and the grep counts. Do not change the theme, the sidebar template or any .rst file.",
  "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 `docs/conf.py` and `docs/requirements.txt` and nothing else. Its description pastes the `<head>` of the built quickstart page with the new `og:` and `twitter:card` metas, the `og:url` of three pages in the `dirhtml` form, the description text the extension chose for each, and the count of built pages carrying an `og:title`.

Read the Docs builds the pull request as it builds every other, installing the new pin from `docs/requirements.txt`, and the `dirhtml` output it serves gets the same tags the sandbox build showed. The PDF and EPUB formats in `.readthedocs.yaml` are unaffected.

Before merging, a reviewer checks the description chosen for the index page reads well on a card, decides whether to turn on social cards for a per-page image, and whether `ogp_site_url` should be the versioned address or the `latest` one.

## Run it on every Sphinx project with bare share cards

A team that maintains several Sphinx projects sends this body once per repository from its own server: one `POST /o/{org}/sessions` each, with that 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 the repositories the Rush GitHub App installation can reach, so the script can pick the ones with a `conf.py` and no `sphinxext.opengraph`. Each run reads its own config: a project with `html_logo` set gets that as the image, one on the `html` builder gets `.html` page URLs, and one whose theme already writes `og:` tags gets no change and a note saying so.

A docs site that is rebuilt from a `release` event can start the same run from a handler on the reader's server after the tag is pushed, so the tags are checked on the version that was just published.

## Why run it on Rush?

The tags are a few lines of config, and the values are only right when they match the builder, the host and the logo the project already has: an `og:url` with `.html` on a `dirhtml` site, an image path that resolves locally and 404s on Read the Docs, a description that starts with a badge. The agent reads the build configuration first, builds the docs in its own sandbox the way the hosts do, and reads the tags out of the HTML it produced.

The build output and the grep stay with the run and are pasted into the pull request, so the reviewer sees the card values rather than the config that should produce them. The same request runs for every documentation project a team maintains at once.

## Frequently asked questions

### Why not turn on social cards?

Social cards generate a PNG per page with matplotlib and a bundled font, which adds packages and time to the Read the Docs build. The pull request leaves them off with a commented `ogp_social_cards` block so a maintainer can turn them on in a follow-up; the sidebar logo is used as a static `og:image` in the meantime.

### Where does the description come from?

From the page itself: the extension takes up to `ogp_description_length` characters of its text, 200 by default. The agent reads what that produced for the index and quickstart pages and pastes it into the description so a reviewer can see whether the first paragraph is the right summary.

### Why set `ogp_site_url` when Read the Docs sets it?

Read the Docs exposes `READTHEDOCS_CANONICAL_URL` and the extension reads it, so the hosted build needs nothing. A local build has no such variable, and without a site URL the `og:url` and the image path are incomplete, so the config sets the address as the fallback.

### Does this change the PDF or EPUB output?

No. The extension adds meta elements to HTML pages only; the `formats` list in `.readthedocs.yaml` still builds PDF and EPUB from the same sources, and the agent's sandbox build confirms those builders run unchanged.

## More Sphinx jobs

- [Add PDF Export to Sphinx Docs](https://getrush.ai/run/add-pdf-export/sphinx/)
- [Add Redirects for Moved Pages to Sphinx Docs](https://getrush.ai/run/add-redirects/sphinx/)
- [Add a Sitemap to a Sphinx Docs Site](https://getrush.ai/run/add-sitemap/sphinx/)

## The same job on other stacks

- [Add Open Graph Tags to a VitePress Blog](https://getrush.ai/run/add-open-graph-tags/vitepress/)
- [Add Open Graph Tags to a Zola Site](https://getrush.ai/run/add-open-graph-tags/zola/)
- [Add Open Graph and Twitter Card Tags to an Eleventy Blog](https://getrush.ai/run/add-open-graph-tags/eleventy/)

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