# Migrate a Gatsby Blog from Markdown to MDX

Yes. An agent swaps gatsby-transformer-remark for gatsby-plugin-mdx, rewrites the queries, template and feed, builds the site and opens a pull request.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and maps every place Markdown enters the site. In gatsbyjs/gatsby-starter-blog that is `gatsby-config.js`, where `gatsby-transformer-remark` runs `gatsby-remark-images` with `maxWidth` 630, `gatsby-remark-responsive-iframe` and `gatsby-remark-prismjs`; `gatsby-node.js`, whose `createPages` queries `allMarkdownRemark` sorted by date and whose `onCreateNode` adds a `slug` field to nodes of type `MarkdownRemark`; `src/templates/blog-post.js`, which renders `post.html` through `dangerouslySetInnerHTML`; `src/pages/index.js`, which lists `allMarkdownRemark` with `excerpt`; and the `gatsby-plugin-feed` block, whose serializer puts `node.html` into `content:encoded`. The three posts live in `content/blog/*/index.md` with `title`, `date` and `description` frontmatter, and `hello-world` has a fenced `js` block and a JPEG, so code highlighting and image processing both have to survive.

It then reads the versions. `package.json` asks for `gatsby` ^5.14.6 and the lockfile resolves 5.16.1, React is 18.2.0, Prettier 2.8.8 is the only dev dependency, `.prettierrc` sets `semi: false` and `arrowParens: avoid`, and `npm test` exits 1 on purpose. There is no CI workflow, so `gatsby build` is the check. The agent installs `gatsby-plugin-mdx` at the major that matches Gatsby 5 together with `@mdx-js/react`, removes `gatsby-transformer-remark`, and moves the three remark plugins under the MDX plugin's `gatsbyRemarkPlugins` with the same options, setting `extensions` to both `.mdx` and `.md` so the existing files keep their names and URLs.

The code changes follow the data model. `allMarkdownRemark` becomes `allMdx` in `gatsby-node.js`, `index.js` and the feed query; `onCreateNode` matches `Mdx`; `createSchemaCustomization` declares `type Mdx implements Node` with the same `Frontmatter` and `Fields`, keeping `date: Date @dateformat`; and `createPage` passes `component` as the template path with `?__contentFilePath=` and the node's `internal.contentFilePath`, which is how Gatsby 5 hands MDX content to a template. `blog-post.js` drops `html` and renders `children` inside the article, and `pageQuery` asks for `excerpt(pruneLength: 160)` and frontmatter only. MDX nodes have no `html` field, so the feed serializer keeps `excerpt` for the description and the agent states in the pull request that `content:encoded` is dropped unless the reader wants a rendering step added.

To prove the migration, the agent adds a fourth post, `content/blog/using-mdx/index.mdx`, that imports a small component and uses it inline, runs `npm run build`, serves the output with `gatsby serve` and opens the four posts and `/rss.xml` in the sandbox's browser to check that the highlighted block, the responsive image and the new component render. It runs `npm run format` so the diff matches the Prettier settings, and opens a pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this Gatsby blog from gatsby-transformer-remark to gatsby-plugin-mdx. Read package.json and its lockfile, gatsby-config.js, gatsby-node.js, every file under src and content/blog first. Install gatsby-plugin-mdx and @mdx-js/react at the versions that match the installed Gatsby, keep gatsby-remark-images, gatsby-remark-responsive-iframe and gatsby-remark-prismjs under gatsbyRemarkPlugins with their current options, and accept both .md and .mdx so existing posts keep their file names and URLs. Change every allMarkdownRemark query, the onCreateNode slug logic, the schema customization, the page creation and the blog post template to the Mdx node type, update the RSS feed query, and add one .mdx post that uses a component. Run gatsby build and check the posts and feed in a browser, run the formatter, and open a pull request that lists what the feed loses.",
  "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 changes `package.json` and `package-lock.json`, the plugin block in `gatsby-config.js`, the three functions in `gatsby-node.js`, `src/templates/blog-post.js`, `src/pages/index.js`, adds `content/blog/using-mdx/index.mdx` and a component it imports, and leaves the three existing `.md` posts untouched. The description lists the queries that changed and says plainly that the feed's full-content element is gone.

The run's record keeps the `gatsby build` output with its page count, the `npm run format` result and the screenshots of each post and the feed from the sandbox browser, so a reviewer can compare the rendered code block and image with the current site without building locally.

Before merging, a reviewer checks that the URLs of the three posts are unchanged, that `excerpt` on the index page reads the same, that `gatsby-remark-prismjs` still wraps the `js` block, and whether the feed change is acceptable to subscribers who relied on full text.

## Run it on every new Gatsby site

A team that maintains several Gatsby sites starts one run per repository with `POST /o/{org}/sessions`, this prompt and the repository in `resources`. Each run reads its own `gatsby-config.js`, so a site that already uses `gatsby-plugin-mdx` for some content gets only the remaining queries moved, and each opens its own pull request.

A `request_id` in each body makes a retry safe, and the API key's webhook receives `run.completed` or `run.failed` with the `session_url` when each run finishes, so a script can post the pull request links and the build output to the team channel.

## Why run it on Rush?

The migration is only done when `gatsby build` succeeds and the rendered pages look the same, and a diff cannot show either. The sandbox runs the build, serves it and opens the pages in a real browser, keeping the output and the screenshots, which is what a reviewer needs to trust a change that touches every query in the site.

It also keeps a slow, uncertain task off a developer's machine. `npm install` for a Gatsby site and a full build take minutes, and a reviewer who wants to compare three plugin configurations can start three runs at once, each in its own sandbox, and read the results side by side.

## Frequently asked questions

### Do I have to rename my .md files to .mdx?

No. `gatsby-plugin-mdx` takes an `extensions` list, and the agent sets it to both, so the existing posts stay as `index.md` and keep their slugs. Only files that use components need the `.mdx` extension.

### What happens to the code highlighting and images?

They stay. `gatsby-remark-prismjs`, `gatsby-remark-images` and `gatsby-remark-responsive-iframe` run under the MDX plugin's `gatsbyRemarkPlugins` with the same `maxWidth` and `wrapperStyle` options, and `gatsby-browser.js` keeps importing the Prism theme.

### Why does the RSS feed change?

`gatsby-transformer-remark` exposes rendered `html` on each node and the feed puts it in `content:encoded`. `Mdx` nodes have no `html` field, because MDX is compiled to a component, so the agent keeps `excerpt` and reports the loss. Rendering full posts into the feed needs an extra build step the reader can ask for.

### Does it migrate frontmatter?

Nothing in the frontmatter changes. `title`, `date` and `description` are read the same way, and `createSchemaCustomization` keeps `date` as a `Date` with `@dateformat`, so `date(formatString: ...)` in the queries still works.

## More Gatsby jobs

- [Review Pull Requests on a Gatsby Site](https://getrush.ai/run/review-pull-requests/gatsby/)
- [Run an SEO Audit on a Gatsby Blog](https://getrush.ai/run/seo-audit/gatsby/)
- [Upgrade Gatsby and Its Plugins](https://getrush.ai/run/upgrade-gatsby/gatsby/)

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

- [Migrate MkDocs API Docs From mkautodoc to mkdocstrings](https://getrush.ai/run/migrate-to-mkdocstrings/mkdocs/)
- [Move Firebase Functions From process.env to Params and Secrets](https://getrush.ai/run/migrate-to-params/firebase-functions/)
- [Migrate a Python Library from Pydantic v1 to v2](https://getrush.ai/run/migrate-to-pydantic-v2/pydantic/)

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