Getting Started with AstroZephyrus

Welcome to AstroZephyrus! This guide will walk you through everything you need to know to get started with this modern, developer-focused blog theme.

What is AstroZephyrus?

AstroZephyrus is a production-ready blog theme built with Astro 5 and Tailwind CSS. It’s designed for developers who want a fast, SEO-friendly blog with excellent performance scores right out of the box.

Key Features

• Lightning Fast — Built on Astro’s static site generation with View Transitions
• SEO Optimized — Structured data, Open Graph tags, sitemaps, and RSS feeds
• Dark Mode — Seamless theme switching with customizable colors
• MDX Support — Write posts in Markdown or MDX with full component support
• Image Optimization — Automatic image optimization using Astro Assets
• Code Highlighting — Beautiful syntax highlighting with Shiki
• Search — Client-side full-text search powered by Pagefind
• Comments — Built-in support for Utterances and Giscus

Quick Start

1. Clone or Fork the Template

The fastest way to get started is using the Astro CLI:

npm create astro@latest -- --template asiomchen/astrozephyrus

Or clone the repository directly:

git clone https://github.com/asiomchen/astrozephyrus.git my-blog
cd my-blog

2. Install Dependencies

Install the required packages using npm:

npm install

3. Start the Development Server

Launch the local development server:

npm run dev

Your site will be available at http://localhost:4321. The dev server includes hot module replacement, so changes you make will be reflected instantly.

Project Structure

Understanding the project structure will help you customize your blog effectively:

/
├── src/
│   ├── data/
│   │   ├── post/          # Your blog posts (MD/MDX files)
│   │   └── author/        # Author profiles
│   ├── components/
│   │   ├── blog/          # Blog-specific components
│   │   ├── widgets/       # Page sections (Header, Footer, etc.)
│   │   ├── common/        # Shared utilities
│   │   └── ui/            # UI elements
│   ├── pages/
│   │   ├── [...blog]/     # Dynamic blog routes
│   │   └── index.astro    # Homepage
│   ├── layouts/           # Page layouts
│   ├── utils/             # Helper functions
│   ├── config.yaml        # Main configuration file
│   └── navigation.ts      # Navigation links
├── public/                # Static assets
└── astro.config.ts        # Astro configuration

Creating Your First Post

Blog posts live in src/data/post/ as .md or .mdx files. Let’s create a new post:

Step 1: Create the File

Create a new file at src/data/post/my-first-post.mdx:

---
publishDate: 2026-02-08T12:00:00Z
title: My First Blog Post
excerpt: A brief description of what this post is about. This appears in post listings and social media shares.
image: https://images.unsplash.com/photo-1499750310107-5fef28a66643?ixlib=rb-4.0.3&auto=format&fit=crop&w=2070&q=80
category: Tutorial
tags:
  - blogging
  - getting-started
author: jane-doe
showToc: true
---

# Welcome to My Blog

This is my first post using AstroZephyrus!

## Code Examples

You can include syntax-highlighted code blocks:

\```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}

greet('World');
\```

## Images and More

AstroZephyrus supports all standard Markdown features plus MDX components!

Step 2: Understanding Frontmatter

The frontmatter section (between the --- markers) contains metadata about your post:

• publishDate — Publication date (ISO 8601 format)
• updateDate — Optional last updated date
• title — Post title (used in SEO)
• excerpt — Brief description for listings and SEO
• image — Cover image URL (optimized automatically)
• category — Single category for organization
• tags — Array of tags for filtering
• author — Matches filename in src/data/author/
• showToc — Enable table of contents (optional)
• draft — Set to true to hide from production (optional)

Configuration Guide

The main configuration file is src/config.yaml. Here are the key sections:

Site Settings

site:
  name: Your Blog Name
  site: 'https://yourdomain.com'
  base: '/'
  trailingSlash: false
  googleSiteVerificationId: null

SEO Metadata

metadata:
  title:
    default: Your Blog Name
    template: '%s — Your Blog Name'
  description: 'A brief description of your blog'
  robots:
    index: true
    follow: true

Blog Configuration

apps:
  blog:
    isEnabled: true
    postsPerPage: 6
    post:
      permalink: '/%slug%'

You can customize the permalink pattern using these variables:

• %slug% — Post filename
• %year%, %month%, %day% — Date components
• %category% — Post category

Comments System

Choose between Utterances or Giscus:

comments:
  isEnabled: true
  vendor: 'utterances'
  utterances:
    repo: 'yourusername/yourrepo'
    issueTerm: 'pathname'
    theme: 'preferred-color-scheme'

Customizing Colors and Fonts

Edit src/components/CustomStyles.astro to customize your theme:

:root {
  --aw-font-sans: 'Inter Variable';
  --aw-color-primary: rgb(34 197 94); /* Green */
  --aw-color-secondary: rgb(22 163 74);
  --aw-color-accent: rgb(20 184 166); /* Teal */
}

You can change fonts by importing different font families from @fontsource-variable.

Customizing Navigation

Edit src/navigation.ts to modify header and footer links:

export const headerData = {
  links: [
    {
      text: 'Blog',
      href: '/blog',
    },
    {
      text: 'About',
      href: '/about',
    },
  ],
  actions: [
    {
      text: 'GitHub',
      href: 'https://github.com/yourusername',
      target: '_blank',
    },
  ],
};

Available Commands

All commands run from the project root:

npm run dev          # Start dev server at localhost:4321
npm run build        # Build for production to ./dist/
npm run preview      # Preview production build locally
npm run check        # Run type checking and linting
npm run fix          # Auto-fix linting and formatting issues

Deploying Your Blog

AstroZephyrus works with all major hosting platforms. Here are the most popular options:

Vercel

1. Push your code to GitHub
2. Import your repository in Vercel
3. Vercel auto-detects Astro and configures build settings
4. Deploy!

Or use the one-click deploy button:

Netlify

1. Push your code to GitHub
2. Create a new site in Netlify
3. Configure build settings:
   • Build command: npm run build
   • Publish directory: dist
4. Deploy!

Or use the one-click deploy:

Cloudflare Pages

1. Push your code to GitHub
2. Create a new project in Cloudflare Pages
3. Configure build:
   • Framework preset: Astro
   • Build command: npm run build
   • Output directory: dist
4. Deploy!

GitHub Pages

To deploy to GitHub Pages, update your astro.config.ts:

export default defineConfig({
  site: 'https://yourusername.github.io',
  base: '/repository-name',
});

Then update src/config.yaml:

site:
  base: '/repository-name'

Next Steps

Now that you have AstroZephyrus set up, here are some things to explore:

1. Create more posts — Build your content library
2. Customize your author profile — Edit src/data/author/jane-doe.md
3. Add pages — Create About, Contact, or other static pages
4. Set up analytics — Configure Google Analytics or Umami
5. Optimize images — Use Astro’s Image component for better performance
6. Enable comments — Set up Utterances or Giscus for reader engagement

Getting Help

• Documentation — Check the Astro docs
• GitHub Issues — Report bugs or request features
• Community — Join the Astro Discord community

Conclusion

AstroZephyrus gives you a solid foundation for building a modern, performant blog. The theme is designed to be customizable while maintaining best practices for SEO, accessibility, and performance.

Happy blogging!