Guides -> Series
[ Astro Series ]

Build a Real Astro Site

A practical path for WordPress developers learning Astro by building a real content site: local setup, MDX, Content Collections, Tailwind, SEO, search, and deploy.

Start the story Article 00 Existing Astro guide Read now WordPress vs Astro Decision guide
Demo stack: Astro / MDX / Content Collections / Tailwind CSS / Pagefind / Vercel
22 lessons published
5 planned parts
31 Phase 1 lessons planned
WP -> Astro target reader path
Learning path

Build the content site in the order it actually makes sense

01
Orient
Part 0

Start with the messy story: the setup confusion, the localhost moment, and the two-day learning curve.

02
Build
Part 1

Create the project, understand Astro files, and deploy the first static site.

03
Model
Part 2

Turn a simple site into a real content system with MDX, YAML, collections, and page templates.

04
Ship
Part 3

Add Tailwind, SEO metadata, schema, sitemap, robots.txt, and AI-crawler files.

05
Polish
Part 4

Add search, affiliate redirects, UI components, dark mode, pagination, and the final site pass.

From Steven

This series starts with the awkward part: I came from WordPress, thought Astro would take one afternoon, then spent two days learning the workflow for real.

The point is not to pretend Astro is magic. The point is to show what actually changes when content moves from a dashboard and database into files, components, and a build step.

This is for you if
  • You know WordPress and want to understand Astro without hype
  • You want to build a blog, guide library, affiliate site, or portfolio
  • You are comfortable learning through files, terminal commands, and Git
  • You want a real project instead of another tiny starter tutorial
Skip this if
  • You need a browser-based CMS dashboard on day one
  • You are building WooCommerce, memberships, or user accounts
  • You want a no-code site builder rather than a developer workflow
How to use this series
01 Read Article 00 first if you are coming from WordPress and the local workflow feels strange.
02 Follow Parts 1 and 2 in order. They build the mental model the later SEO and UI work depends on.
03 Use the later parts as modules once you already have a working Astro content site.

Series contents

Published lessons will become clickable here as each batch moves from the draft workshop into the live guide collection.

Part 0

Orientation

Understand why this series exists, what the demo project is, and how the WordPress-to-Astro mindset shift feels.

1 of 1 live 15 min
  1. 0.1 My First Two Days Learning Astro as a WordPress Developer ->
Part 1

Astro Foundations

Set up Astro, understand pages, layouts, components, styling, static generation, and deploy the first version.

6 of 6 live 70 min
  1. 1.1 What is Astro? A WordPress Developer's Honest Take ->
  2. 1.2 How to Set Up Your First Astro Project: A Step-by-Step Beginner Guide ->
  3. 1.3 Astro Pages, Layouts and Components: The First Three Concepts to Learn ->
  4. 1.4 Styling in Astro: Start with Plain CSS Before Reaching for Tailwind ->
  5. 1.5 Static Site Generation Explained: How Astro Pre-Builds HTML ->
  6. 1.6 How to Deploy Astro to Vercel: GitHub, Auto-Deploy, and Custom Domains ->
Part 2

Content with MDX and YAML

Build the content model: Markdown, Content Collections, dynamic routes, MDX, reviews, comparisons, guides, and images.

9 of 9 live 110 min
  1. 2.1 Writing Content with Markdown in Astro: What WordPress Developers Need to Know ->
  2. 2.2 Content Collections in Astro: The Right Way to Manage Structured Content ->
  3. 2.3 Dynamic Routes in Astro: How One Template Generates Hundreds of Pages ->
  4. 2.4 MDX in Astro: Use Components Inside Your Content Without Touching Raw Code ->
  5. 2.5 Build a Review Page in Astro: Schema, Layout and Components ->
  6. 2.6 Build a Comparison Page in Astro: Side-by-Side Content with Structured Schema ->
  7. 2.7 Build a Guide Page in Astro: Step-by-Step Content with Difficulty and Time Estimates ->
  8. 2.8 Images in Astro: How to Add, Optimize and Manage Local Images ->
  9. 2.9 Cloudinary in Astro: External Image CDN for Content Sites That Scale ->
Part 3

Tailwind and Technical SEO

Move from plain styling into Tailwind, then add meta tags, Open Graph, JSON-LD, sitemap, robots.txt, and llms.txt.

6 of 6 live 80 min
  1. 3.1 How I Switched an Astro Site from Plain CSS to Tailwind v4 ->
  2. 3.2 Tailwind CSS in Astro: Refactoring Every Page and Fixing What Breaks ->
  3. 3.3 Meta Tags and Open Graph in Astro: Build One Reusable SEO Component ->
  4. 3.4 JSON-LD Schema in Astro: Article, Review, Person, and Breadcrumbs ->
  5. 3.5 Sitemap and robots.txt in Astro: Package or Custom Route? ->
  6. 3.6 llms.txt in Astro: Auto-Generate It Without Pretending It Is SEO ->
Part 4

Search, Components, and Polish

Add answer-first content patterns, go-links, UI components, dark mode, Pagefind search, pagination, and final polish.

10 planned 130 min
  1. 4.1 Content SEO and AEO
  2. 4.2 SEO/AEO/GEO/HEO theory
  3. 4.3 /go/ affiliate links
  4. 4.4 Component library
  5. 4.5 Dark mode
  6. 4.6 Pagefind search
  7. 4.7 Pagination
  8. 4.8 Homepage redesign
  9. 4.9 UI polish
  10. 4.10 Phase 1 wrap-up
Publishing plan

Parts 0–3 are live. The polish phase comes next.

Article 00 through Article 18B are live now: foundations, the complete content model, Tailwind migration, and the technical SEO layer. Part 4 moves into answer-first content, affiliate links, UI components, search, and final polish.

Read the current Astro guide ->
Need the decision first? WordPress vs Astro Astro vs Next.js