Building an Astro Blog Theme from Scratch with WindSurf AI

Have you ever wanted to build a sleek, modern blog from scratch with minimal effort? In this article, I’ll walk you through how I used WindSurf, an AI-powered IDE, to create a fully functional blog theme using Astro and Tailwind CSS 4. Whether you’re a beginner or a seasoned developer, you can follow along and replicate this process—starting from the initial setup to a polished, responsive website. Let’s dive in!

What Is WindSurf?

WindSurf is an innovative IDE that leverages AI to help you build applications by simply chatting with it. Unlike traditional coding tools, WindSurf allows you to describe what you want, and it generates the code for you. It’s free to use with some limitations, but I opted for the Pro Plan (more on that later). With features like file inspection and advanced language models (like Claude Sonnet 3.7), it’s a game-changer for rapid development.

I recently used WindSurf to revamp my Astro-based blog, incorporating Tailwind CSS 4, and the results were stunning—a responsive, fast, and feature-rich site built in just a few days. Here’s how I did it, step by step.

Check WindSurf

Initial Setup: Laying the Foundation

Before WindSurf could work its magic, I needed a basic Astro project. Here’s how I kicked things off:

Step 1: Installing Astro

I started by creating a new Astro project using the official CLI:

npm create astro@latest

• Prompts:
  • Directory: . (current folder)
  • Template: A basic, minimal starter
  • Dependencies: Yes
  • Git: Yes

This gave me a clean Astro setup with a dev server (npm run dev) and Git initialized—ready for customization.

Step 2: Adding Tailwind CSS 4

Next, I integrated Tailwind CSS 4 for styling:

npx astro add tailwind

• Installed: @tailwindcss/vite@^4.0.6 and tailwindcss@^4.0.6
• Created: ./src/styles/global.css for Tailwind styles
• Updated: astro.config.mjs to include Tailwind via Vite plugins

I imported the stylesheet in my layout file (src/layouts/Layout.astro) to ensure styles applied globally.

Step 3: Enhancing with Typography

For better Markdown formatting, I added the Tailwind Typography plugin:

npm install -D @tailwindcss/typography

This made prose content (like blog posts) look polished without extra effort.

Step 4: Adding MDX Support

To enable richer content with MDX, I ran:

npx astro add mdx

This updated astro.config.mjs to include the @astrojs/mdx integration, allowing me to mix Markdown and JSX.

Step 5: Incorporating Astro Icons

For lightweight icons, I added the astro-icon package:

npx astro add astro-icon
npm install @iconify-json/mdi

This integrated icons from the Material Design Icons set (mdi), enhancing the UI with minimal overhead.

With these foundations in place, I was ready to let WindSurf take over.

Check WindSurf

Building the Blog with WindSurf

Chatting My Way to a Blog Theme

Once my Astro project was set up, I opened WindSurf and started chatting. My goal: a blog theme with a header, footer, pagination, categories, tags, dark/light mode, and more—all using Tailwind 4 and Astro 5.4. Here’s how it unfolded:

• First Prompt: “Build a blog with Astro and Tailwind CSS 4. Use theme variables and Tailwind.” WindSurf analyzed my project and began scaffolding.
• Global CSS: I asked it to define custom colors and fonts in src/styles/global.css. It created a flexible theme setup, though I didn’t enforce strict rules initially.
• Features: I requested a dark/light mode toggle, pagination, and a responsive menu. WindSurf updated files like layouts and components on the fly.

Key Features of the Blog

WindSurf delivered a feature-packed theme:

• Header: A clean, responsive header with a mobile menu.
• Pages: Authors, categories, tags, and series (tutorials) with pagination.
• Posts: Breadcrumbs, table of contents, related posts (tag-based), and social sharing.
• Search: A client-side search using Fuse.js—no React, just Astro.
• Widgets: Accordions, tabs, buttons, and notification boxes for richer content.
• SEO: Optimized components for better discoverability.

The site scored near-perfect on Google PageSpeed (100 on mobile!), thanks to Astro’s image optimization and Tailwind’s efficient CSS.

WindSurf in Action: Behind the Scenes

How I Used It

• Write Mode: I used WindSurf’s “write” mode, which auto-updates files without manual approval—perfect for speed.
• Multi-Tasking: I’d ask for 3-4 features at once (e.g., “Add header, footer, and pagination”). This minimized credit usage while maximizing output.
• Error Handling: If something broke, WindSurf flagged it without consuming credits—a nice touch.

Challenges and Fixes

Tailwind 4 was new, and WindSurf didn’t know it perfectly. For example:

• Dark Mode: Initially buggy, but I guided it to fix the toggle.
• Custom Widgets: I requested accordions and tabs; it delivered, though I tweaked sizing later.

Credits and Pricing

I used the Pro Plan ($15/month):

• 500 Prompt Credits: For AI interactions.
• 1,500 Flow Credits: For file edits and actions. After ~8 hours of work, I used just 77 prompt credits and half my flow credits—super efficient!

The Result: A Public Astro Theme

In 3 days, I built Bit Doze-Astro Theme, a public repository (link in the description) with:

• Responsive design (Tailwind 4)
• Dark/light mode
• Fast load times (Astro 5.4 + Cloudflare hosting)
• Demo content for easy setup

It’s not 100% perfect—some code could be cleaner—but it’s a solid starting point. I even used WindSurf to write the README!

Why WindSurf Rocks

Compared to other AI tools (like Cursor or Replit), WindSurf stands out:

• Smarter: Powered by Claude Sonnet 3.7, it understands context well.
• Faster: Write mode skips tedious approvals.
• Affordable: Free tier available, and the Pro Plan is cost-effective.

I’ve tried rivals like Try (ByteDance) and VS Code plugins, but WindSurf’s seamless integration and results blew me away.

Get Started Yourself

Ready to try it? Here’s how:

1. Install Astro and dependencies (see “Initial Setup”).
2. Grab WindSurf (free tier or Pro with my referral link—500 bonus credits!).
3. Chat your way to a custom project.

Check my Bit Doze-Astro Theme repo for inspiration, and watch my next video on hosting it for free. Like and subscribe if you enjoyed this journey—happy coding!

Check WindSurf Bit Doze Theme