All jobs

Add Tag Pages to a Gatsby Blog from a Linear Issue

Yes. An agent adds a tags field to the Markdown schema, builds one page per tag and a tag index in gatsby-node.js, links them from each post, and opens a PR.

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 starts by reading how the blog is wired. In a site shaped like gatsbyjs/gatsby-starter-blog, package.json pins gatsby at ^5.14.6 with gatsby-transformer-remark, gatsby-source-filesystem, gatsby-plugin-feed and React 18, installs with npm from package-lock.json, has prettier as its only dev dependency, and its test script prints a reminder to write tests and exits 1, so there is no test suite and no workflow under .github/. gatsby-config.js points gatsby-source-filesystem at content/blog, where three posts (hello-world, my-second-post, new-beginnings) each carry title, date and sometimes description in their frontmatter, and nothing else.

gatsby-node.js is where the pages come from. createPages runs one allMarkdownRemark query sorted by date, creates a page per post with src/templates/blog-post.js and passes the previous and next post ids in context; onCreateNode adds a slug field with createFilePath; and createSchemaCustomization declares the Frontmatter type with exactly title, description and date, so a query for a tags field would fail the build until the type knows it. src/pages/index.js lists every post with its date and excerpt, and src/components/seo.js builds the head from siteMetadata.

The agent adds tags: [String] to the Frontmatter type first, so posts without tags keep building and the field reads as null rather than breaking the query. It writes src/templates/tag.js, a template whose page query filters allMarkdownRemark on frontmatter.tags containing the tag passed in context and renders the same post list the index uses, and src/pages/tags.js, which groups all posts by tag with a group(field: {frontmatter: {tags: SELECT}}) query and lists each tag with its post count. In createPages it adds a second query for the grouped tags and a createPage call per tag at /tags/<slug>/, with the slug made by a small helper in gatsby-node.js rather than a new dependency. blog-post.js and index.js get a row of tag links under each title, and the three sample posts get a tags list in their frontmatter so the pages have something to show.

Then it proves the build. npm ci and npm run build have to finish without a GraphQL error, and gatsby serve lets the agent fetch /tags/, one tag page and one post to confirm the links resolve and the RSS feed at /rss.xml still renders. npx prettier --check runs over the changed files because the repository formats with it. The agent commits the template, the page, the gatsby-node.js changes, the frontmatter edits and nothing under public/ or .cache/, which .gitignore already excludes.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "A Linear issue labelled agent asks for tag pages on the blog: each post may list tags in its frontmatter, every tag gets a page at /tags/<tag>/ listing its posts, /tags/ lists every tag with a count, and each post and the index show the post's tags as links. Read package.json, gatsby-config.js, gatsby-node.js, src/templates/blog-post.js, src/pages/index.js, src/components/seo.js and the frontmatter of every file under content/blog first. Add tags: [String] to the Frontmatter type in createSchemaCustomization so untagged posts still build. Add src/templates/tag.js and src/pages/tags.js, create one page per tag in createPages from a grouped allMarkdownRemark query with a slug helper in gatsby-node.js, link the tags from blog-post.js and index.js, and add tags to the existing posts. Run npm ci, npm run build and gatsby serve, fetch /tags/, one tag page, one post and /rss.xml, run prettier --check on the changed files, and open a pull request that links the issue and lists the new routes.",
  "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. It adds src/templates/tag.js and src/pages/tags.js, changes gatsby-node.js in three places (the tags field on the Frontmatter type, the grouped tags query and the per-tag createPage loop with its slug helper), adds tag links to src/templates/blog-post.js and src/pages/index.js, and adds a tags list to the frontmatter of the posts under content/blog. The description lists the routes the build produced, with /tags/ and each /tags/<slug>/ named, and quotes the issue.

Because the starter has no CI workflow and its test script exits by design, the proof is in the run's record rather than in a check. The trajectory at GET /o/{org}/sessions/{id}/messages keeps the gatsby build output with its page count, the curl of each new route against gatsby serve, the feed fetch and the prettier --check result, so a reviewer reads what the build did instead of trusting a description.

Before merging, a reviewer checks the tag names in the sample posts, decides whether /tags/ belongs in the site navigation (the starter has no nav component, so the agent links it from the tag rows only), and confirms the slug helper handles the tags their real posts will use. Nothing deploys until the pull request merges.

Run it on every Linear issue labelled agent

Connect Linear once from Settings → Connections, then add an automation to the Project that holds the blog with this prompt and a linear trigger on linear.issue.labeled, naming the label in config.labels. The trigger appends the labelled issue after the prompt and fills in no placeholder, so the agent reads the routes and the tag rules from the issue itself. Each labelled issue starts its own run in its own sandbox and ends in its own pull request; max_runs_per_hour caps how many the automation starts in an hour.

A handler on your own server can do the same without the automation: when Linear's webhook reports the label, it sends POST /o/{org}/sessions with the repository and https://linear.app/<workspace>/issue/<ID> in resources, which puts the issue text in the prompt through your Linear connection, and a request_id that is a UUID v5 of the issue id so a redelivered webhook returns the run it already started rather than a second one.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

A Gatsby schema change is only known to work after a full build, and the build is what takes the time: install, source the Markdown, run every page query, write public/. On a laptop that loop competes with a dev server holding .cache/, and a wrong createTypes string surfaces as a GraphQL error twenty seconds in. In a Rush sandbox the agent runs gatsby build and gatsby serve on a clean checkout, reads the errors, fixes the type or the query and builds again, and the laptop stays free.

The result carries its proof. The pull request holds the files, and the transcript holds the build output and the fetched routes beside the commands that produced them, so a reviewer sees that /tags/ rendered rather than reading that it should. A second issue, for category pages or a tag feed, is a second sandbox and a second pull request at the same time.

Frequently asked questions

Do my existing posts need tags for the build to pass?

No. The agent adds tags: [String] to the Frontmatter type in createSchemaCustomization, so a post without the field reads as null and the grouped query simply skips it. Only the posts the agent tags appear on a tag page. The starter already uses this pattern so that description can be missing without breaking blog-post.js.

Does it add a dependency for the tag slugs?

No. The starter's only dev dependency is prettier, and the agent keeps it that way with a short slug helper in gatsby-node.js that lowercases the tag and replaces runs of non-alphanumeric characters with a hyphen. If you already use lodash elsewhere, the prompt can ask for its kebabCase instead.

What happens to the RSS feed?

Nothing changes in gatsby-config.js. The gatsby-plugin-feed query selects title, date, excerpt and html and does not touch tags, so /rss.xml renders as before; the agent fetches it from gatsby serve to confirm. Adding each tag as a category element to the feed is a one-line follow-up if you want it.

Why are there no checks on the pull request?

Because the starter ships without a workflow and its test script exits 1 by design. The run's trajectory keeps the gatsby build output and the fetched routes, which is what a check would have shown. If the issue asks for it, the agent can add a workflow that runs npm ci and npm run build on every pull request in the same change.

More Gatsby jobs

The same job on other stacks

More jobs like this: Turn a Linear label into a PR

Keep reading