# Add LaTeX Math Rendering to an Astro Blog

Yes. An agent adds remark-math and rehype-katex to an Astro blog's Markdown pipeline, ships the KaTeX stylesheet locally, builds the site and opens a pull request.

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

## What the agent does

The agent reads the Markdown pipeline before it changes it. In a repository shaped like satnaing/astro-paper, `astro.config.ts` builds the processor with `unified` from `@astrojs/markdown-remark`, with `remarkToc` and `remarkCollapse` as remark plugins and `rehypeCallouts` as the one rehype plugin, plus a `shikiConfig` with `min-light` and `night-owl` themes and four transformers, one of them the repository's own `transformerFileName`. The site runs Astro 7 with `@astrojs/mdx`, Tailwind 4 through `@tailwindcss/vite`, `pagefind` for search and `satori` for OG images, on Node 22.12 or newer per `engines`, with pnpm 11.3 in CI. `src/content.config.ts` loads posts from `src/content/posts` with a Zod schema, `src/layouts/Layout.astro` owns the `<head>` and imports `src/styles/global.css`, and `src/styles/typography.css` overrides Tailwind Typography under an `.app-prose` class. The `build` script runs `astro check`, `astro build`, then `pagefind --site dist`, and `.github/workflows/ci.yml` runs `pnpm run lint`, `pnpm run format:check` and that build on every pull request with a three-minute timeout.

The repository also contains its own instructions, `src/content/posts/how-to-add-latex-equations-in-blog-posts.md`, a published post that tells readers to install `rehype-katex`, `remark-math` and `katex`, add them to the remark and rehype lists, link the KaTeX stylesheet from a CDN in the layout, and give `.katex-display` the foreground colour in `typography.css`. The agent follows that post where it is still right and departs from it where the codebase has moved: the post's config snippet predates the `unified()` processor and the `@config` import, and a CDN stylesheet would be the site's only third-party request.

So the change is this. The agent runs `pnpm add remark-math rehype-katex katex`, adds `remarkMath` to the front of `remarkPlugins` inside the existing `unified()` call so it runs before `remarkToc`, and adds `rehypeKatex` after `rehypeCallouts`. Instead of the CDN link it imports `katex/dist/katex.min.css` from `src/styles/global.css`, so Vite bundles the stylesheet and its fonts with the site and the content security of the page does not change. In `src/styles/typography.css` it adds the `.katex-display` colour rule and an `overflow-x: auto` on display math so a long equation scrolls on a phone instead of breaking the layout. It updates the instructions post to match the code it just wrote, so the next reader does not follow the stale snippet, and adds one example post under `src/content/posts/` with an inline equation, a display equation and an `aligned` block, dated and tagged like the others.

Then it proves the build. It runs `pnpm install --frozen-lockfile`, `pnpm run lint`, `pnpm run format:check` with the repository's Prettier plugins for Astro and Tailwind, and `pnpm run build`, which runs `astro check` and the Pagefind indexing step. It opens the built example post from `dist/` and checks that the equation is a `.katex` element with MathML inside, not raw dollar signs, and that the OG image route still renders for the new post. Only then does it push a branch and open a pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add LaTeX math rendering to this Astro blog. Read astro.config.ts, the layout and the styles, and the repository's own post about adding LaTeX equations. Add remark-math and rehype-katex to the existing unified processor, bundle the KaTeX stylesheet locally through global.css instead of a CDN link, add the display-math styling in typography.css, update the instructions post to match the code, add one example post with inline and display equations, run lint, format:check and the full build, check the built HTML contains KaTeX output, and open a pull request.",
  "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 on its own branch. The diff touches `package.json` and `pnpm-lock.yaml` for the three packages, `astro.config.ts` for the two plugin entries, `src/styles/global.css` for the stylesheet import, `src/styles/typography.css` for the display-math rules, the existing instructions post, and one new post under `src/content/posts/`. The description explains why the stylesheet is bundled rather than linked from a CDN and lists the equations the example post renders.

The checks are the proof. The repository's `CI` workflow runs lint, the format check and the build on the pull request, and the session's trajectory at `GET /o/{org}/sessions/{id}/messages` keeps every `pnpm` command with its output, including the `astro check` result and the grep over `dist/` that found `.katex` markup in the example post. A reviewer sees the equation rendered without checking the branch out.

Before merging, a reviewer checks that `remarkMath` runs before `remarkToc`, since a heading inside a math block should not become a table-of-contents entry, that the KaTeX fonts are served from the site's own assets, and that the example post's `pubDatetime` and `tags` follow the schema in `src/content.config.ts`. They open the post in both colour schemes to confirm the `.katex-display` colour follows the theme.

## Run it on every Markdown feature requested

A blog team that adds Markdown features one at a time sends `POST /o/{org}/sessions` with this shape of prompt each time, naming the feature and the repository in `resources`. Each run reads the processor in `astro.config.ts` as it is at that moment and adds one plugin pair beside the ones already there, so a later run for diagrams or footnotes lands on top of this one without conflict.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when the turn ends, with `session_url` to read the pull request from. A `request_id` that is a UUID v5 of the feature name makes a retried request return the run it already started rather than opening a second pull request.

## Why run it on Rush?

Adding math to an Astro blog is a small change with a slow check: the Markdown pipeline only shows its result after a full `astro build`, and in this repository that includes `astro check` and Pagefind indexing. On Rush the run happens in its own cloud sandbox with the pnpm version and Node the CI uses, builds the site there and reads the built HTML, while your working tree stays as it was.

The result is checkable rather than claimed. The pull request carries the diff, the repository's workflow runs on it, and the trajectory keeps the build output and the check that found KaTeX markup in `dist/`, so the review is about the stylesheet choice and the example post, not about whether the equations render.

## Frequently asked questions

### Why not link the KaTeX stylesheet from a CDN as the guide post says?

The repository's post is older than the current pipeline and a CDN link would be the only third-party request on the site. Importing `katex/dist/katex.min.css` from `global.css` lets Vite bundle the stylesheet and fonts with the build, and the agent updates the post to describe what the code now does.

### Does it work in both .md and .mdx posts?

Yes. The plugins are added to the `markdown` processor in `astro.config.ts`, which `@astrojs/mdx` inherits, so a `$...$` or `$$...$$` block renders in either file type. The example post the agent adds is Markdown; the existing MDX posts are untouched.

### Will dollar signs in existing posts break?

A lone `$` in prose stays text; `remark-math` needs a matching closing delimiter on the same line for inline math. The agent greps the existing posts for paired dollar signs and names any post that would change in the pull request description, so a price list does not turn into an equation unnoticed.

### Does the build get slower?

KaTeX renders at build time to HTML and MathML, so there is no client-side script and no runtime cost for readers. The build does a little more work per post with math in it; the trajectory keeps the `astro build` output so you can read the timing for your own repository rather than an estimate.

### Can I use a different renderer such as MathJax?

Yes. Name it in the prompt and the agent adds `rehype-mathjax` instead and bundles no stylesheet, since MathJax output carries its own styling. The rest of the change, the remark plugin, the example post and the build check, stays the same.

## More Astro jobs

- [Add Post Series to an Astro Blog from a Linear Issue](https://getrush.ai/run/add-post-series/astro/)
- [Add PWA Support to an Astro Site](https://getrush.ai/run/add-pwa-support/astro/)
- [Add Reading Time to Posts in an Astro Site from a Linear Issue](https://getrush.ai/run/add-reading-time/astro/)

## More jobs like this: Hand off a long task

- [Add the Maven Wrapper to a Maven Project](https://getrush.ai/run/add-maven-wrapper/maven/)
- [Make GitHub Actions Workflows Run in a Merge Queue](https://getrush.ai/run/add-merge-queue-support/github-actions/)
- [Add Mermaid Diagrams to a Docusaurus Site](https://getrush.ai/run/add-mermaid-diagrams/docusaurus/)

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