All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading