Static site publishing usually feels reliable until the first editor says, “It looked fine in the CMS preview.” A markdown preview can show headings and paragraphs, but it will not catch a table that overflows on mobile, a missing hero image, a future date that hides the post, or a description that is too long for the article layout.
The preview workflow should answer one practical question: can the person approving the change see the same route that readers and crawlers will see?
Preview the real URL shape
A generic markdown pane is useful while writing. Approval should happen on the real route: /posts/example/, /privacy/, /tags/frontend/, or whatever the production URL will be.
For an Astro content collection, the preview build should run the same schema used for production:
const posts = defineCollection({
schema: z.object({
title: z.string().min(8),
description: z.string().min(40).max(180),
pubDatetime: z.date(),
modDatetime: z.date().optional().nullable(),
draft: z.boolean().optional(),
tags: z.array(z.string()).default([]),
}),
});This is not just developer neatness. It keeps publishing mistakes from becoming runtime surprises.
Treat drafts and scheduled posts as separate states
Drafts and scheduled posts fail when teams overload one field. A draft should be visible in preview and absent from production lists. A scheduled post should be inspectable before its date and hidden from production output until the intended time.
Write the rules down:
| State | Preview build | Production build |
|---|---|---|
draft: true | Render with preview banner | Exclude from posts, RSS, sitemap |
Future pubDatetime | Render for editors | Exclude until publish window |
| Missing required metadata | Fail build | Fail build |
The timezone rule matters. If the content team works in one timezone and the hosting platform builds in another, “tomorrow morning” can become a bug.
Check assets before visual review
Images create many preview failures. The markdown references /uploads/photo.jpg, but the file was not committed. The file exists but is 8 MB. Alt text is empty. The first image is so tall that no article text appears in the first viewport.
A lightweight asset check can catch the mechanical issues before an editor reviews the page:
for (const image of referencedImages) {
assertFileExists(`public${image.src}`);
assert(image.alt.trim().length > 0, `${image.src} is missing alt text`);
assert(image.bytes < 1_500_000, `${image.src} is too large for article use`);
}The visual review still matters, but it should focus on layout and readability, not missing files.
Make failures readable for non-framework users
Raw build output often points at the framework, not the content mistake. A wrapper script can summarize the failure in editorial language:
Content validation failed
File: src/content/posts/content-preview-workflow.md
Field: description
Problem: 236 characters; maximum is 180
Fix: Shorten the summary used in article cards and metadata.Editors do not need a stack trace. They need the file, the field, and the next action.
Keep preview close to the publishing path
The more preview differs from publishing, the less people trust it. If content is saved through a Git-based CMS, a save should create a commit and trigger a preview deployment. If content is edited through pull requests, attach the preview URL to the PR. If content is edited locally, the dev server should use the same content filters as the production build, with explicit preview overrides.
A practical preview checklist:
- Article route renders
- Article appears or hides in index according to draft/date rules
- RSS and sitemap behavior match production rules
- Images load from the same public path as production
- Mobile article width and tables are readable
- Metadata title and description are presentStatic sites are fast because they move mistakes to build time. Preview is where that discipline becomes visible before readers see the page.