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 with this body:
{
"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"
}
]
}- 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
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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
More jobs like this: Hand off a long task
- Add the Maven Wrapper to a Maven Project (Maven)
- Make GitHub Actions Workflows Run in a Merge Queue (GitHub Actions)
- Add Mermaid Diagrams to a Docusaurus Site (Docusaurus)