Astro 5 content site with MDX, RSS, and OG images

A fast, content-led Astro 5 site. MDX with code highlighting, auto-generated OG images per post, RSS, sitemap, dark mode. Built for writing-heavy sites that need a 100 Lighthouse score.

use whenPersonal site, technical blog, or company writing surface. You want shipping speed without giving up performance.

May 14, 20262,540 bytesastromdxrsscontentblog

download .md↓

[Site Name]

A content-led site. Posts in MDX, images optimized at build, no client JS unless a component explicitly opts in.

Source of truth

GitHub repo is the source. Vercel auto-deploys on push to main. No CMS for v0; you write Markdown in your editor.

Tech stack

Astro 5 (Content Collections + Islands). Tailwind v4 for styling. MDX for posts, with @astrojs/mdx + expressive-code for syntax highlighting. @astrojs/image (sharp) for AVIF + WebP outputs. @astrojs/sitemap + @astrojs/rss. Deployed to Vercel as static output.

Deploy

git push origin main. Vercel runs npm run build and serves the static output. Preview deploys per PR.

File map

src/content/posts/ your MDX posts, named YYYY-MM-DD-slug.mdx
src/content/config.ts Zod schema for post frontmatter
src/pages/index.astro home
src/pages/posts/[slug].astro post template
src/pages/rss.xml.ts RSS feed
src/pages/og/[slug].png.ts per-post OG image (Satori)
src/components/ PostCard, Prose, ThemeToggle
src/layouts/Base.astro shared HTML shell
astro.config.mjs integrations, site URL

.env keys

PUBLIC_SITE_URL https://yourdomain.com (used by sitemap + RSS)

Hard rules

Every post needs title, slug, publishedAt, summary, tags. Zod will fail the build if missing.
No client JS by default. If a component needs it, opt in with client:visible or client:idle.
Images use <Image> not raw <img>. Width + height required.
One H1 per page (the title). Headings descend without skipping levels.
Run npm run lighthouse before each deploy. Target: 100/100/100/100 on /.
Post slugs are kebab-case, date-prefixed in the filename, no date in the slug itself.

Recent significant changes

2026-05-14: Scaffolded. Locked: Astro 5 with Vercel adapter (static), MDX over plain Markdown (component embedding worth the extra ms), Satori for OG (no headless Chrome).

Next session: start here

Edit astro.config.mjs site URL.
Write your first post under src/content/posts/.
Generate a favicon set with realfavicongenerator.net, drop in public/.
Set up custom OG template at src/pages/og/[slug].png.ts.
Push, deploy, attach domain.
Run apex-seo before DNS goes live.

← older

Phoenix LiveView app (Elixir realtime, no JS framework)

newer →

Next.js 16 SaaS starter (Stripe + magic-link auth)

Get the next CLAUDE.md in your inbox.

One new template every week, plus occasional case studies.