All jobs

Add Draft Posts to a VitePress Blog

Yes. An agent adds a draft flag to your VitePress blog so a draft renders in dev but stays out of the build, the index, the feed and prev/next links.

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 reads every place a post is listed, because a draft has to be left out of each. In a blog laid out like vuejs/blog, package.json runs vitepress 1.3 with vue, feed, gray-matter and Tailwind under pnpm 9, and the scripts are vitepress --open, vitepress build and vitepress preview. .vitepress/config.ts sets cleanUrls: true and buildEnd: genFeed, and .vitepress/genFeed.ts loads posts/*.md with createContentLoader and render: true, sorts by frontmatter.date and writes feed.rss into config.outDir. .vitepress/theme/posts.data.ts is a second createContentLoader('posts/*.md') with excerpt: true whose transform maps each file to title, url, excerpt and a formatted date; Home.vue lists that data, and Article.vue finds the current post in it by url to compute nextPost and prevPost. Layout.vue chooses Home, NotFound or Article by frontmatter.index and page.isNotFound. The sixteen posts under posts/ carry title, date, author, gravatar and twitter in their frontmatter and nothing that marks a state, so a half-written file committed to posts/ is published on the next build.

The flag is draft: true in a post's frontmatter, and the agent applies it in three layers. The first is the page itself: srcExclude in config.ts is a list of glob patterns VitePress drops when it lists markdown pages, so the config computes it at load time by reading posts/*.md with gray-matter, already a dependency, and collecting the files whose data has draft: true, but only when process.env.NODE_ENV is production, which vitepress build sets and vitepress --open does not. In dev every draft still renders at its URL so the author can read it. The second layer is the two content loaders, because createContentLoader globs the pattern itself and does not honour srcExclude: posts.data.ts filters raw on frontmatter.draft inside transform under the same environment check, and genFeed.ts filters its posts array before the loop that calls feed.addItem. Both loaders share one isDraft helper in .vitepress/drafts.ts so the rule is written once.

The third layer is what a draft looks like while it is visible. Article.vue shows a Draft badge beside the date when frontmatter.draft is set, so a dev preview is never mistaken for a published page, and Home.vue lists drafts in dev with the same badge so the author sees where the post will sit in the order. Because Article.vue computes nextPost and prevPost from the filtered data, a published post never links to a draft in the build and a draft in dev still gets neighbours. The agent also adds draft to the Post interface in posts.data.ts and documents the flag in the README's authoring section with the one line to remove when the post ships.

Checking is a build with a draft in it. The agent adds posts/draft-example.md with draft: true on a temporary branch of its work, runs pnpm build and checks that .vitepress/dist has no draft-example page, that dist/feed.rss has no item for it, and that the prev/next footer of the neighbouring posts skips it; then runs pnpm dev with the Vite server and fetches /draft-example to show it renders with the badge. The example file is removed before the pull request, and the description quotes the ls of dist, a grep of the feed and the dev fetch.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add draft posts to this VitePress blog. Read package.json, .vitepress/config.ts, .vitepress/genFeed.ts, .vitepress/theme/posts.data.ts, Home.vue, Article.vue and Layout.vue, and the frontmatter of a few files under posts/ first. A post with draft: true in its frontmatter must render in dev with a visible Draft badge on the article and in the index, and be left out of a production build everywhere: compute srcExclude in config.ts from the posts' frontmatter with gray-matter when NODE_ENV is production, filter the posts data loader's transform and the feed generator on the same flag through one shared helper, so the index, the RSS feed and the previous and next links never include a draft, and add draft to the Post type. Document the flag in the README. Verify with a temporary draft post: run the build and show the page is absent from dist and the feed, then run the dev server and show the page renders with the badge. Remove the temporary post and open a pull request quoting those checks.",
  "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

The pull request adds .vitepress/drafts.ts and changes .vitepress/config.ts, .vitepress/genFeed.ts, .vitepress/theme/posts.data.ts, Home.vue, Article.vue and README.md. Its description quotes the dist listing and the feed grep from a build that contained a draft, the dev server's response for the draft URL with the badge in the HTML, and a note that the temporary post was removed before the branch was pushed.

A reviewer checks that the three layers agree on one flag and one helper, that the environment check is the one vitepress build sets, and that the badge styling fits the theme's Tailwind classes. They decide whether drafts should also be hidden from the dev index or only badged, which is one condition in Home.vue.

Published posts, the feed's format, cleanUrls and the Vercel headers in vercel.json are unchanged; a build with no draft produces the same site as before.

Run it on every new post opened as a pull request

A blog whose posts arrive as pull requests can check the flag on each one. An automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize, filtered to the branch pattern the team uses for posts, runs read-only with a prompt that reads any new file under posts/, checks the frontmatter has title, date, author and a draft value, builds the site and comments with whether the post would appear in dist and the feed. The trigger adds the event after the prompt; it fills in no placeholder.

A handler on your own server that watches for a draft: true line removed in a merged pull request can send this body's checking part to POST /o/{org}/sessions with the repository in resources, with a request_id that is a UUID v5 of the merge commit SHA so a redelivered event returns the run already started.

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

Why run it on Rush?

VitePress has no draft state of its own, and the places a post appears are spread over a config option, two data loaders, a feed generator and the theme's components. Leaving one out means a draft shows in the feed while the page 404s, or links from a published post lead to nothing. The agent reads each listing site in the repository, routes them through one helper, and proves the result with a build that contained a draft and a dev run that rendered it, with the output kept in the run's record.

The environment check is the small detail that makes the feature usable: an author sees the draft at its real URL under vitepress --open, and the build that deploys never does.

Frequently asked questions

Why is srcExclude not enough?

srcExclude removes the page from the files VitePress lists, so the draft has no URL in the build. The two createContentLoader calls glob posts/*.md themselves and do not read srcExclude, so without the filter in their transform and in genFeed.ts the draft would still appear in the index data and in feed.rss, linking to a page that does not exist.

Can I see a draft in dev?

Yes. The exclusions apply only when NODE_ENV is production, which vitepress build sets. Under vitepress --open the draft renders at its URL and in the index, both with a Draft badge, so a preview is never mistaken for a published page.

Does a draft break previous and next links?

No. Article.vue derives nextPost and prevPost from the filtered posts data, so in a build the neighbours of a draft link past it, and in dev the draft itself has neighbours. The check in the pull request shows the footer of the two posts around the temporary draft.

How do I publish a draft?

Delete the draft: true line, or set it to false, and build. The README's authoring section says so, and because date is already in the frontmatter the post takes its place in the order without any other change.

What about a scheduled publish date?

That is a different rule, a post whose date is in the future, and the same helper is the place for it. The pull request leaves it out and notes that a date check at build time would also need a rebuild on the day, which the Vercel deployment does not do on its own.

More VitePress jobs

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading